WordPress 6.9 ile birlikte çekirdeğe eklenen WordPress Abilities API, bir eklentinin ya da temanın yapabildiklerini makine tarafından okunabilir ve standart bir şema ile beyan etmesini sağlar. Bu kayıtlar sayesinde site içi bileşenler, diğer eklentiler ve yapay zekâ ajanları tek bir merkezi kayıt üzerinden keşif yapabilir, izinleri denetleyebilir ve yeteneği çalıştırabilir. Amaç; her eklentinin kendi özel fonksiyonunu kendi belgelendirmesiyle gizlemesi yerine, WordPress’in ortak dilinden konuşmasıdır.
Bu rehber; Abilities API’nin gerçek bileşenlerini (WP_Ability, WP_Ability_Category, WP_Abilities_Registry), kayıt için kullanılan iki kancayı (wp_abilities_api_categories_init, wp_abilities_api_init), JSON Schema ile giriş ve çıkış doğrulamasını ve permission_callback ile erişim kontrolünü çalışan PHP örnekleriyle ele alır. Ayrıca gerçek projede sık yapılan üç hatayı, name çakışması sorununu ve wp_abilities_api_init kancasının önceliğini de gösterir.
WordPress Abilities API nedir ve neden önemlidir?
Abilities API; yetenek (ability), kategori (category) ve kayıt (registry) olmak üzere üç temel kavram üzerine kurulu bir sistemdir. Her yetenek, namespace/ability-name biçiminde tekil bir ada sahiptir, JSON Schema ile tanımlanmış giriş ve çıkış bekler, opsiyonel bir izin geri çağırımı taşır ve WP_Ability::execute() ile çalıştırılır. Kategori, birbiriyle ilgili yetenekleri gruplar; her yetenek tam olarak bir kategoriye aittir. Kayıt ise tüm bu nesneleri tutan, sorgulayan ve kaldıran tekil (singleton) bir PHP sınıfıdır.
API’nin değeri keşfedilebilirlikten gelir. Bir yapay zekâ ajanı veya otomasyon aracı, registry üzerinden sitenin tüm yeteneklerini listeleyebilir, her birinin şemasını okuyabilir, izinlerini denetleyebilir ve execute() çağrısıyla çalıştırabilir. Bu sayede her eklentinin “API belgelerini ayrı oku, kendi entegrasyonunu yaz” döngüsü ortadan kalkar.
Abilities API yalnızca WordPress 6.9 ve üzeri için kullanılabilir. 6.8 ve öncesinde wp_register_ability() fonksiyonu tanımsız olduğundan kayıt çağrısı Call to undefined function hatasıyla sonuçlanır. Üretim sitesinin sürümünü önce get_bloginfo('version') ile doğrulamak, sonra kayıt yapmak en güvenli yoldur.
WordPress Abilities API hangi durumlarda kullanılır?
- Yapay zekâ entegrasyonu: Bir ajanın veya WP AI Client çağrısının “bu sitede şu yetenekler var, şu şemayla, şu izinle” demesini istediğinizde.
- Eklenti birlikte çalışabilirliği: A eklentisinin B eklentisinin fonksiyonunu kendi kancası yerine standart bir yetenek üzerinden çağırması gerektiğinde.
- Kurumsal otomasyon: Bir destek botunun “bilet kapat”, “abone bilgisi getir”, “fatura oluştur” gibi eylemleri manuel kod yerine registry üzerinden tetiklemesi gerektiğinde.
- Geliştirici belgelendirmesi: Eklenti yeteneklerini README’de değil, makine tarafından okunabilir şema olarak kendi içinde beyan etmek istediğinizde.
- REST API köprüsü: Bir yeteneğe dışarıdan HTTP üzerinden erişilmesi gerektiğinde
meta.show_in_rest => trueile otomatik REST rotası üretildiğinde.
WordPress Abilities API için temel kavramlar ve gereksinimler
| Kavram | Sınıf / Fonksiyon | Açıklama |
|---|---|---|
| Ability | WP_Ability |
Tekil bir yetenek; label, description, category, input_schema, output_schema, execute_callback, permission_callback taşır |
| Category | WP_Ability_Category |
Yetenekleri gruplar; her yetenek tam olarak bir kategoriye bağlıdır |
| Registry | WP_Abilities_Registry |
Singleton; register(), unregister(), find(), query() metotları sağlar |
| Category Registry | WP_Abilities_Category_Registry |
Kategorileri ayrıca tutan ikinci tekil kayıt |
| Kayıt | wp_register_ability() |
Eklentilerin yetenek beyan ettiği global fonksiyon |
| Kategori kayıt | wp_register_ability_category() |
Kategorileri beyan eden global fonksiyon |
| Kategori kancası | wp_abilities_api_categories_init |
Kategori kayıtlarının yapıldığı erken aksiyon |
| Yetenek kancası | wp_abilities_api_init |
Yetenek kayıtlarının yapıldığı ana aksiyon |
JSON Schema doğrulaması ajv-draft-04 üzerinden yapılır; bu nedenle type, properties, required, enum, items gibi şema anahtarları geçerlidir. Şema boş bırakılırsa giriş veya çıkış doğrulanmaz; bu durum geliştirici sorumluluğunda kalır.
WordPress Abilities API nasıl kurulur ve uygulanır?
Abilities API, WordPress 6.9 çekirdeğinde yerleşik olarak gelir. Ek eklenti veya paket kurulumu gerekmez; yalnızca wp-content/plugins dizinindeki eklentinin wp_abilities_api_init kancasına bağlanması yeterlidir. Ancak wordpress/abilities-api Composer paketi, 6.8 ve altındaki sürümlere geriye dönük destek sağlar; henüz 6.9’a geçmemiş kurulumlar için bu paket tercih edilir.
Bir eklentinin wp_abilities_api_init kancasına bağlanabilmesi için PHP 7.4+ gerekir (WP 6.9’un kendi PHP minimumu). Composer kullanılmıyorsa wp_register_ability() fonksiyonunun varlığını function_exists() ile kontrol etmek iyi bir savunma hattıdır.
WordPress Abilities API adım adım uygulama rehberi
Aşağıdaki akış, sıfırdan çalışan bir yetenek kaydının tamamını gösterir. Kod, wp-content/plugins/site-info-ability/site-info-ability.php yolundaki tek dosyalık eklentinin içine yazılır.
Adım 1 — Eklenti başlığı: PHP dosyasının başında standart WordPress eklenti başlığı olmalıdır.
<?php
/**
* Plugin Name: Site Info Ability
* Description: Abilities API ile site bilgisi yeteneği kaydeder.
* Version: 1.0.0
* Requires at least: 6.9
* Requires PHP: 7.4
*/
Adım 2 — Kategori kaydı: Her yetenek bir kategoriye bağlı olmalıdır. Kategori kaydı wp_abilities_api_categories_init kancasında yapılır ve yetenek kaydından önce tamamlanmalıdır.
add_action( 'wp_abilities_api_categories_init', 'sia_register_category' );
function sia_register_category() {
wp_register_ability_category(
'site-information',
array(
'label' => __( 'Site Information', 'site-info-ability' ),
'description' => __( 'Abilities that provide information about the WordPress site.', 'site-info-ability' ),
)
);
}
Adım 3 — Yetenek kaydı: Yetenek kaydı wp_abilities_api_init kancasında yapılır. output_schema JSON Schema olduğundan type, properties gibi anahtarlar geçerlidir.
add_action( 'wp_abilities_api_init', 'sia_register_ability' );
function sia_register_ability() {
wp_register_ability(
'site-info-ability/site-info',
array(
'label' => __( 'Site Info', 'site-info-ability' ),
'description' => __( 'Returns information about this WordPress site.', 'site-info-ability' ),
'category' => 'site-information',
'input_schema' => array(),
'output_schema' => array(
'type' => 'object',
'properties' => array(
'site_name' => array( 'type' => 'string' ),
'site_url' => array( 'type' => 'string' ),
'active_theme' => array( 'type' => 'string' ),
'php_version' => array( 'type' => 'string' ),
'wordpress_version' => array( 'type' => 'string' ),
),
),
'execute_callback' => 'sia_get_siteinfo',
'permission_callback' => function () {
return current_user_can( 'manage_options' );
},
'meta' => array( 'show_in_rest' => true ),
)
);
}
Adım 4 — Çalıştırma geri çağırımı: Yetenek çalıştırıldığında dönen veri output_schema ile doğrulanır. Şemayla uyuşmayan alanlar sessizce düşürülebilir.
function sia_get_siteinfo() {
return array(
'site_name' => get_bloginfo( 'name' ),
'site_url' => get_bloginfo( 'url' ),
'active_theme' => wp_get_theme()->get( 'Name' ),
'php_version' => PHP_VERSION,
'wordpress_version' => get_bloginfo( 'version' ),
);
}
Adım 5 — REST üzerinden erişim: meta.show_in_rest true olduğunda /wp-json/wp/v2/abilities/site-info-ability/site-info adresinden yeteneğe dışarıdan erişilebilir. İzin geri çağırımı reddedilirse REST 403 döner.
WordPress Abilities API için gerekli ayarlar ve ön hazırlık
Yeteneklerin çalışması için kullanıcının manage_options yeteneği veya eşdeğer bir permission_callback kararı gerekir. Bu geri çağırım, ajan bağlamında da çalışır; ajan application_password ile kimlik doğruladığında current_user_can() yine o kullanıcının yeteneklerini döner. Sonuç olarak bir ajana “şu yeteneği kullan” demek için o kullanıcının manage_options (veya sizin belirlediğiniz) rolü alması yeterlidir.
Çoklu ortam (multisite) kurulumlarında permission_callback içinde is_user_member_of_blog() veya is_user_member_of_network() ile site veya network kapsamı ekleyebilirsiniz. Tekil bir manage_options çağrısı subsite yöneticilerine sızma riski taşır; manage_network_options veya manage_specific_site benzeri kontroller daha sağlıklıdır.
Dikkat edilmesi gerekenler ve yaygın hatalar
En sık yapılan hatalar, kanca sırasını atlamak, aynı ada iki kez kayıt denemek ve şemayı boş bırakmaktır. WordPress aynı yetenek adının ikinci kez kaydını WP_Abilities_Registry::register() içinde already_registered hatası fırlatarak reddeder; bu da PHP hata günlüğüne düşer ve isteğin tamamlanmasını yarıda keser. Resmi belgelendirmede de vurgulandığı gibi kayıt sırası ve çakışma kontrolleri geliştiricinin sorumluluğundadır.
Performans açısından her sayfa yüklemesinde aynı ağır callback’in çalıştırılması gereksizdir. Kayıt bloğu yalnızca kanca anında çalıştığı için runtime maliyeti minimumdur; ancak execute_callback içinde veritabanı sorgusu veya HTTP çağrısı varsa bu maliyet çağrı anına ertelenir. Sık çalıştırılan yetenekler için sonuç önbelleği (wp_cache_* veya transients) kullanmak en sağlıklı yoldur. WP AI Client ve benzeri ajan entegrasyonlarında bu önbellek, özellikle birden çok ajanın aynı siteye bağlandığı durumlarda belirgin fark yaratır.
Sık yapılan hatalar
- Aynı
nameile ikinci kayıt: Registry, mükerrer kayıtları sert şekilde reddeder. Çakışma olmadan öncewp_has_ability( 'ns/name' )ile kontrol edin. - Kategorisiz yetenek kaydı:
categoryalanı boş bırakılırsa kayıt başarısız olur. Kategori, yetenekten önce tanımlanmış olmalıdır. - Şemada eksik
properties:output_schemaiçintypebelirtildiği haldepropertiestanımlanmadığında doğrulama her değeri geçirir; bu istenmeyen sızıntıya yol açabilir. permission_callbackdöndürmeme: Geri çağırımnullveya hiçbir şey döndürdüğünde izinfalsesayılır; yetenek çalıştırılamaz.execute_callbackiçinde kullanıcı verisi döndürme: Şema olmadan dönen alanlar maskelenmediğinden e-posta veya API anahtarı gibi hassas bilgi sızabilir.wp_abilities_api_initöncesindewp_register_abilityçağrısı: Çok erken yapılan kayıtWP_Abilities_Registryhenüz başlatılmadığı için “registry not initialized” hatası verir.
WordPress Abilities API performans ve güvenlik kontrolleri
permission_callback her çalıştırmada çağrıldığı için pahalı işlemlerden kaçınmak gerekir. Ağır bir kontrolü bir kez yapıp sonucu static değişkende tutmak en pratik yöntemdir:
add_action( 'wp_abilities_api_init', function () {
static $checked = false;
if ( ! $checked ) {
$checked = sia_is_environment_safe();
}
if ( ! $checked ) {
return;
}
sia_register_ability();
} );
Yetenek adlarında kullanıcı girdisini doğrudan birleştirmek WP_Ability adının namespace/ability-name formatını kırmasına yol açar. Ad yalnızca küçük harf, rakam, tire ve alt çizgi içerebilir; bunun dışındaki karakterler kayıt anında reddedilir. REST üzerinden gelen name parametresi mutlaka sanitize_key() ile süzülmelidir.
REST üzerinden gelen yetenek adı, URL’de yer aldığı için izin geri çağırımı döndürülen veriyle sınırlı olsa bile URL’in loglanması hassas bilgi sızıntısına yol açabilir. Üretim kurulumlarında REST istek loglarında X-WP-Nonce ve Authorization başlıklarının maskelendiğinden emin olun.
En iyi uygulamalar ve kontrol listesi
Yetenekleri sürdürülebilir yazmanın temel ilkesi tek sorumluluk ve açık şemadır. Bir yetenek “fatura oluştur” kadar küçük, “kullanıcıyı sil” kadar büyük olabilir; ancak her ikisi de kendi şeması, izni ve kategorisiyle kayıt altına alınmalıdır. Yüzlerce yeteneği tek dosyada toplamak yerine her yetenek için ayrı bir register_*_ability() fonksiyonu yazmak, sürüm güncellemelerinde gerilemeleri azaltır. Bu yaklaşım, WordPress çekirdek geliştirici rehberinde de önerilen modüler kayıt desenine uygundur.
Belgelendirme için description alanının İngilizce ve net yazılması, ajan ve geliştiricinin yeteneği doğru anlaması için yeterlidir. Türkçe açıklama ihtiyacı varsa meta.translation anahtarı kullanılabilir; ancak bu anahtarı okuyan tüketiciler henüz dardır.
Gerçek proje senaryoları
Gerçek bir projede yetenekler genellikle üç katmanda yaşar. Birinci katman site bilgisi, sunucu sağlığı, aktif eklenti listesi gibi salt okunur keşif yetenekleridir. İkinci katman “taslak yazı oluştur”, “kullanıcıya bildirim gönder” gibi içerik/iletişim eylemleridir. Üçüncü katman ise ödeme çek, abonelik iptal et gibi geri dönüşü olmayan işlemlerdir. Üçüncü katmanda permission_callback tek başına yetmez; ek olarak meta.confirm => true veya meta.idempotent => false gibi meta alanları tüketicinin “emin misin?” diyaloğu açmasını zorunlu kılar.
Bir ajan entegrasyonunda üç katman ayrı rollerle eşleşir: okuma yetenekleri salt okunur bir application_password ile çalışırken yazma yetenekleri editor rolünde, geri dönüşü olmayan işlemler ise administrator rolünde bir kullanıcı gerektirir. Bu ayrım permission_callback içinde current_user_can( 'editor' ) veya current_user_can( 'administrator' ) ile yapılır. Sitemizdeki WordPress Yapay Zeka Entegrasyonu rehberi de ajan bağlantılarında benzer bir katmanlı izin yapısı kullanır.
Sıkça Sorulan Sorular
WordPress Abilities API hangi sürümde varsayılan olarak gelir?
WordPress 6.9 ve üzeri. 6.8 ve altında wp_register_ability() fonksiyonu tanımsızdır. Geriye dönük destek için wordpress/abilities-api Composer paketi kullanılabilir. Paket, Composer registry’sinde yayımlanmıştır.
Bir yetenek birden fazla kategoriye ait olabilir mi?
Hayır. Her yetenek tam olarak bir kategoriye bağlıdır. Birden fazla kategoride görünmesi gereken yetenek için kategori hiyerarşisi veya ayrı kayıtlar kullanılabilir. Örneğin “site-bilgisi” kategorisinde “site-info” yeteneği, “kullanıcı” kategorisinde ise “kullanıcı-listesi” yeteneği ayrı ayrı tanımlanır.
REST üzerinden yetenek çalıştırmak güvenli mi?
Güvenli, ancak permission_callback her çağrıda çalıştırılır. manage_options gibi yüksek yetki gerektiren bir geri çağırım, REST üzerinden gelen isteğin de aynı kontrolü geçmesini zorunlu kılar. application_password kullanan bir ajan için de aynı kullanıcı rolü gerekir. Sitemizdeki WP API Auth rehberi uygulama parolası ile kimlik doğrulama adımlarını örnekler.
Şema doğrulaması başarısız olursa ne olur?
execute_callback çağrılmadan önce input_schema doğrulanır. Hatalı girişte WP_Ability::execute() WP_Error döner. Çıkış tarafında output_schema doğrulaması başarısız olursa geri çağırım çıktısı filtrelenir, hata loglanır. Şema, JSON Schema draft-04 spesifikasyonuna uygun yazılmalıdır.
Abilities API ile WP-CLI komutu yazılabilir mi?
Evet. WP-CLI komutu içinde wp_register_ability() çağrısı yapmak yerine, wp ability list, wp ability execute ns/name gibi komutlar için ayrı bir eklenti yazılabilir; komutlar registry üzerinden okur ve WP_Ability::execute() ile çalıştırır. Bu yapı, komut satırından otomasyona uygun bir köprü sağlar.
Yetenek adı çakışırsa hangisi kazanır?
İlk kayıt kazanır. WP_Abilities_Registry::register() aynı adla ikinci çağrıda already_registered hatası fırlatır. Eklentilerin sıralaması (plugins_loaded önceliği) hangi kaydın önce geleceğini belirler; bu nedenle çekirdek yetenekler genellikle yüksek öncelikle kaydedilir. Çakışmayı önceden tespit etmek için wp_has_ability() fonksiyonu kullanılabilir.
Sonuç
WordPress Abilities API, eklenti ve temaların yeteneklerini standart bir dilde beyan etmesini, JSON Schema ile doğrulamasını ve permission_callback ile korumasını sağlayan merkezi bir kayıt sistemidir. WordPress 6.9 ile çekirdeğe gelmesi, ajan ve otomasyon araçlarının siteye güvenli ve standart bir yoldan bağlanmasını mümkün kılar. Kurulumu yalnızca wp_abilities_api_init kancasına bağlanmak ve wp_register_ability() çağrısı yapmaktan ibarettir; başarılı bir entegrasyon için en kritik adımlar kategori kaydının önce yapılması, şemanın eksiksiz tanımlanması ve izin geri çağırımının her çağrıda çalıştırılabilir kalmasıdır.
Gerçek projelerde en sık karşılaşılan üç hata — aynı name ile ikinci kayıt, kategorisiz yetenek kaydı ve şema olmadan dönen alanlar — yalnızca kod incelemesiyle yakalanabilir; üretimde fark edilmeleri geç olur. Bu nedenle her yeni yetenek için birim testi yazmak, en sağlıklı korumadır.
Dahili linkler:
