WordPress Eklenti Geliştirmeye Giriş: Plugin Header Nasıl Yazılır

WordPress'te bir eklenti yazmaya başlamanın ilk adımı, tek bir satır kod çalıştırmadan önce gelir: PHP dosyasının en üstüne doğru bir yorum bloğu (docblock) eklemek. Bu blok küçük görünse de WordPress'in eklentinizi tanıması, Eklentiler ekranında doğru bilgilerle listelemesi ve çeviri sisteminin çalışması bu birkaç satıra bağlıdır. Bu yazıda plugin header'ın nasıl çalıştığını, hangi alanların gerçekten zorunlu olduğunu ve geliştiricilerin en sık düştüğü hataları ele alıyoruz.

WordPress Bir Dosyayı Eklenti Olarak Nasıl Tanır?

WordPress, wp-content/plugins/ dizinindeki her PHP dosyasını tarayarak standart bir docblock formatı arar. Bir dosyada bu formatta bir yorum bulunduğunda WordPress onu kurulu bir eklenti olarak tanır ve yönetim panelindeki Eklentiler ekranında listeler. Bu tarama işlemi dosyanın geri kalan koduyla ilgilenmez; sadece dosyanın başındaki yorum bloğunu okur.

Bu blokta teknik olarak zorunlu olan tek alan Plugin Name'dir. Diğer tüm başlıklar — Plugin URI, Description, Version, Author, Author URI, License, License URI, Text Domain — opsiyoneldir. Ancak bu alanlar bulunduğunda Eklentiler ekranındaki açıklamayı, sürüm numarasını, yazar bağlantısını ve lisans bilgisini otomatik olarak doldurur; yani opsiyonel olmaları önemsiz oldukları anlamına gelmez, sadece dosyanın eklenti olarak tanınması için gerekli değildirler.

Eklenti Dosyasının Yeri Neden Önemli

Header'ın çalışması için sadece doğru formatta yazılması yetmez, doğru dosyada da bulunması gerekir. Küçük, tek dosyalık bir eklenti doğrudan wp-content/plugins/eklenti-adi.php şeklinde tek bir dosya olarak durabilir. Daha büyük, birden fazla dosyadan oluşan bir eklentide ise standart yaklaşım kendi klasörünü oluşturmaktır: wp-content/plugins/eklenti-adi/eklenti-adi.php. Header docblock'u bu ana dosyanın en başında yer almalıdır; eklenti klasörü içindeki yardımcı bir sınıf dosyasına veya alt dizindeki bir dosyaya konursa WordPress bunu taramaz ve eklenti tanınmaz.

Somut bir örnekle düşünelim: wp-content/plugins/site-yedekle/ klasöründe site-yedekle.php, includes/class-backup.php ve assets/style.css dosyaları olan bir eklenti geliştirdiğinizi varsayın. Header yalnızca site-yedekle.php dosyasının en tepesinde olmalıdır. Aynı yorum bloğunu yanlışlıkla includes/class-backup.php dosyasının başına koyarsanız, WordPress klasörü tararken bu alt dizine hiç bakmaz ve eklenti Eklentiler ekranında hiç görünmez — herhangi bir hata mesajı da vermez, sadece listede yer almaz.

Header Alanları: Zorunlu ve Opsiyonel

Tam Kod Örneği

Aşağıdaki örnek, eksiksiz bir plugin header'ının ve ardından gelen temel güvenlik korumasının nasıl görünmesi gerektiğini gösterir:

<?php
/**
 * Plugin Name:       My Awesome Plugin
 * Plugin URI:        https://example.com/my-awesome-plugin
 * Description:       A short description of what the plugin does.
 * Version:           1.0.0
 * Author:            Your Name
 * Author URI:        https://example.com
 * License:           GPL v2 or later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       my-awesome-plugin
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit; // Exit if accessed directly.
}

ABSPATH Koruması Neden Gerekli?

Dosyanın header'ından hemen sonra gelen if ( ! defined( 'ABSPATH' ) ) { exit; } satırı, dosyanın WordPress çekirdeği dışında doğrudan bir URL üzerinden çağrılmasını engeller. ABSPATH sabiti yalnızca wp-load.php üzerinden WordPress tam olarak yüklendiğinde tanımlanır. Bir saldırgan veya bot dosyayı doğrudan site.com/wp-content/plugins/eklenti/dosya.php gibi bir adresten çağırmaya çalıştığında bu sabit tanımlı olmayacağı için kontrol devreye girer ve betik çalışmadan sonlanır.

Bu kontrolün mantığı basittir: wp-load.php WordPress'i başlatırken çekirdek dosyaları, veritabanı bağlantısını ve genel ayarları yükler ve bu süreçte ABSPATH sabitini tanımlar. Eklenti dosyanız normal akışta, yani bir sayfa yüklenirken WordPress tarafından include edildiğinde bu sabit zaten tanımlı olur ve kontrol sorunsuz geçilir. Ancak dosya sunucuda herkese açık bir dizindeyse ve biri onu doğrudan tarayıcı adres çubuğundan çağırırsa, WordPress hiç devrede olmadığı için ABSPATH tanımsız kalır ve exit çalışır.

Text Domain ve Çeviri Sistemi

Text Domain, eklentinin çeviri dizelerini gruplamak için kullanılan benzersiz bir kimliktir. Bu değer, load_plugin_textdomain() fonksiyonuna verilen slug ile (veya WordPress.org üzerinde barındırılan eklentilerde otomatik yüklenen çevirilerde kullanılan slug ile) birebir eşleşmelidir. İki değer eşleşmediğinde WordPress hangi çeviri dosyasını yükleyeceğini bulamaz; sonuç olarak dize çevirileri (i18n) hiç yüklenmez ve arayüz her zaman İngilizce ya da kaynak dilde görünür. Bu hata genellikle sessiz kalır — herhangi bir PHP hatası fırlatmaz, sadece çeviriler çalışmaz.

Sık Yapılan Hatalar

• Plugin Name eksik veya boş bırakılmış: Diğer tüm alanlar doğru yazılsa bile Plugin Name yoksa WordPress dosyayı eklenti olarak hiç tanımaz ve Eklentiler ekranında listelemez.
• Text Domain uyumsuzluğu: Header'daki Text Domain değeri ile load_plugin_textdomain() çağrısındaki veya çeviri dosyası adındaki slug birbirini tutmuyorsa, çeviriler sessizce çalışmaz.
• ABSPATH kontrolünün unutulması: Bu satır atlanırsa dosya WordPress dışında doğrudan çağrılabilir hale gelir; bu, temel bir güvenlik pratiğinin eksik bırakılması demektir.
• Header'ın yanlış dosyaya konması: Bu yorum bloğu, eklentinin ana PHP dosyasının en başında olmalıdır — genellikle wp-content/plugins/eklenti-adi/eklenti-adi.php yolunda ya da tek dosyalık bir eklentide doğrudan o dosyada. Alt dizinlerdeki başka bir dosyaya konursa WordPress bunu taramaz.

Header'ı elle yazmak hata payı bırakır, özellikle Text Domain ile dosya/slug eşleşmesinde. Aşağıdaki araç, gerekli tüm alanları eksiksiz ve doğru formatta üreterek bu adımı hızlandırır.

WP Eklenti Header Oluşturucu

Plugin Name, Text Domain ve diğer header alanlarını doğru formatta oluşturup kopyalamaya hazır hale getirin.