WordPress Eklenti Gelistirmeye Giris

WordPress'i dünyanın en yaygın içerik yönetim sistemi yapan şey, çekirdek yazılımın kendisinden çok onun etrafında büyüyen eklenti ekosistemidir. Bir işlevi hazır bir eklentiyle çözmek çoğu zaman mümkündür; ancak eninde sonunda "tam olarak istediğim gibi çalışan bir eklenti yok" dediğiniz an gelir. İşte o an, bir tüketiciden bir geliştiriciye dönüştüğünüz andır. İyi haber şu: WordPress eklentisi yazmaya başlamak için ileri düzey bir PHP uzmanı olmanız gerekmiyor. Temel PHP bilgisi, birkaç WordPress kuralı ve doğru zihinsel modelle ilk çalışan eklentinizi bir öğleden sonrada yazabilirsiniz.

Bu rehberde sıfırdan bir eklentinin nasıl kurulduğunu, WordPress'in çalışma mantığının kalbindeki hook sistemini (action ve filter), sayfa içine dinamik içerik gömen shortcode'ları, yönetim paneline menü eklemeyi ve en önemlisi güvenli veri işlemeyi adım adım ele alacağız. Örnekleri kopyala-yapıştır değil, anlayarak uygulamanız için her satırın neden orada olduğunu açıklayacağız. Amacımız size hazır bir kod parçası vermek değil; kendi fikirlerinizi güvenli, sürdürülebilir eklentilere dönüştürebilecek temeli kazandırmak.

Eklenti Ne Zaman Doğru Çözümdür?#

Bir işlevselliği eklentiyle mi, temaya kod ekleyerek mi yoksa hazır bir çözümle mi hayata geçireceğinize karar vermek, geliştirmenin ilk ve en önemli adımıdır. Genel kural nettir: görsel/sunum ile ilgili değişiklikler temaya, davranış/işlev ile ilgili değişiklikler eklentiye aittir. Çünkü tema değiştirdiğinizde temaya gömdüğünüz tüm işlevler kaybolur; oysa eklenti tema değişiminden bağımsızdır.

Aşağıdaki durumların hepsi birer eklenti sinyalidir: bir formdan gelen verileri özel bir tabloya kaydetmek, belirli bir kullanıcı rolüne özel içerik göstermek, üçüncü parti bir API ile konuşmak, yönetim paneline özel bir ayar sayfası eklemek ya da içeriğe otomatik olarak bir bilgi kutusu enjekte etmek. Bunları functions.php'ye yazmak kısa vadede kolay görünse de tema güncellemesinde ezilir ve taşınamaz hale gelir.

Kendi eklentinizi yazmadan önce ihtiyacınızı zaten karşılayan bir çözüm olup olmadığını da kontrol edin; temel WordPress eklentileri rehberimiz, yeniden icat etmenize gerek olmayan olgun araçları listeler. Ancak niş bir iş kuralınız varsa, üç satırlık bir eklenti onlarca ayarlı devasa bir eklentiden hem daha hızlı hem daha güvenlidir.

Eklenti Dosya Yapısı ve Plugin Header#

WordPress'in bir PHP dosyasını "eklenti" olarak tanıması için tek bir şart vardır: dosyanın başında, yorum bloğu içinde standart bir plugin header bulunması. WordPress wp-content/plugins/ klasörünü tarar ve bu başlığı taşıyan dosyaları eklenti listesine ekler.

En basit haliyle bir eklenti, wp-content/plugins/ altında tek bir .php dosyası olabilir. Ancak profesyonel yaklaşım, her eklentiye kendi klasörünü vermektir. Küçük bir örnek yapı şöyledir:

wp-content/plugins/cloutr-duyuru-kutusu/
├── cloutr-duyuru-kutusu.php   # ana dosya (plugin header burada)
├── includes/
│   ├── shortcode.php          # shortcode tanımları
│   └── admin.php              # yönetim paneli kodu
├── assets/
│   ├── css/style.css
│   └── js/script.js
├── languages/                 # çeviri dosyaları (.po/.mo)
└── readme.txt

Ana dosyanın en başındaki header, WordPress'in eklentiyi tanıması için zorunludur:

<?php
/**
 * Plugin Name: Clou.TR Duyuru Kutusu
 * Plugin URI:  https://clou.tr
 * Description: İçeriklere ve sayfalara shortcode ile duyuru kutusu ekler.
 * Version:     1.0.0
 * Author:      Sizin Adınız
 * Author URI:  https://clou.tr
 * License:     GPL-2.0-or-later
 * Text Domain: cloutr-duyuru
 * Domain Path: /languages
 */

// Dosyaya doğrudan erişimi engelle — her eklenti dosyasının başına eklenmeli
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

if ( ! defined( 'ABSPATH' ) ) exit; satırı küçük ama kritiktir: birisi tarayıcıdan doğrudan cloutr-duyuru-kutusu.php adresini çağırırsa, WordPress yüklenmediği için ABSPATH tanımlı olmaz ve dosya hiçbir şey yapmadan sonlanır. Bu, en temel güvenlik alışkanlıklarından biridir ve istisnasız her PHP dosyanızın başında bulunmalıdır.

Hook Mantığı: Action ve Filter#

WordPress geliştirmenin kalbi hook sistemidir. Hook'ları, WordPress'in çalışırken belirli noktalarda "burada bir şey yapmak isteyen var mı?" diye seslendiği kancalar olarak düşünün. Sizin işiniz o kancalara kendi fonksiyonunuzu bağlamaktır. İki tür hook vardır ve aralarındaki farkı anlamak her şeyi çözer.

Action (eylem) hook'ları bir olay gerçekleştiğinde bir şey yapmak içindir; bir değer döndürmezler. Örneğin sayfanın <head> bölümüne kod eklemek, bir yazı kaydedildiğinde e-posta göndermek gibi. add_action() ile bağlanırsınız:

// wp_head action'ı sayfanın <head> bölümü render edilirken tetiklenir
add_action( 'wp_head', 'cloutr_ozel_meta_ekle' );

function cloutr_ozel_meta_ekle() {
    echo '<meta name="tema-rengi" content="#4f46e5">' . "\n";
}

Filter (süzgeç) hook'ları ise bir veriyi değiştirmek içindir; kendilerine gelen değeri alır, işler ve mutlaka döndürürler. En sık kullanılan örnek, yazı içeriğini ekranda gösterilmeden hemen önce süzmektir:

// the_content filter'ı, yazı gövdesi görüntülenmeden önce içeriği süzer
add_filter( 'the_content', 'cloutr_icerik_sonuna_not_ekle' );

function cloutr_icerik_sonuna_not_ekle( $icerik ) {
    // Sadece tekil yazı sayfalarında ve ana sorguda çalış
    if ( is_single() && in_the_loop() && is_main_query() ) {
        $not = '<p class="cloutr-not">Bu yazı Clou.TR Bilgi Merkezi için hazırlanmıştır.</p>';
        $icerik .= $not;
    }
    return $icerik; // filter fonksiyonu değeri MUTLAKA geri döndürmeli
}

İki tür arasındaki farkı özetleyen tablo işinizi kolaylaştırır:

add_action() ve add_filter() fonksiyonlarının üçüncü parametresi öncelik (varsayılan 10; küçük sayı önce çalışır), dördüncü parametresi ise fonksiyonunuzun kaç argüman alacağıdır. Aynı hook'a bağlı birden fazla fonksiyon varsa çalışma sırasını bu öncelik belirler.

Yaşam Döngüsü: Aktivasyon, Deaktivasyon ve Kaldırma#

Bir eklenti etkinleştirildiğinde bir kereye mahsus bazı hazırlıklar yapmak isteyebilirsiniz: bir veritabanı tablosu oluşturmak, varsayılan ayarları kaydetmek ya da rewrite kurallarını yenilemek gibi. WordPress bunun için üç özel kanca sunar ve bunlar normal action hook'larından farklı çalışır.

// Eklenti ETKİNLEŞTİRİLDİĞİNDE bir kez çalışır
register_activation_hook( __FILE__, 'cloutr_aktivasyon' );

function cloutr_aktivasyon() {
    // Varsayılan ayarı sadece daha önce yoksa ekle
    if ( false === get_option( 'cloutr_duyuru_metni' ) ) {
        add_option( 'cloutr_duyuru_metni', 'Hoş geldiniz!' );
    }
    // Özel bir sayfa tipi eklediyseniz kalıcı bağlantıları yenileyin
    flush_rewrite_rules();
}

// Eklenti DEVRE DIŞI BIRAKILDIĞINDA çalışır — geçici temizlik
register_deactivation_hook( __FILE__, 'cloutr_deaktivasyon' );

function cloutr_deaktivasyon() {
    flush_rewrite_rules();
}

Önemli bir ayrım vardır: deaktivasyon kullanıcının veriyi kaybetmesi anlamına gelmez, sadece eklentiyi geçici olarak durdurur; dolayısıyla burada ayarları silmeyin. Kalıcı temizlik (tabloları düşürme, option silme) için uninstall.php adında ayrı bir dosya ya da register_uninstall_hook() kullanılır ve bu yalnızca kullanıcı eklentiyi tamamen sildiğinde çalışır. Bu üçlüyü karıştırmak, "eklentiyi kapattım ama ayarlarım silindi" gibi can sıkıcı hatalara yol açar.

Shortcode ile Dinamik İçerik Ekleme#

Shortcode, kullanıcıların bir yazı veya sayfaya [cloutr_duyuru] gibi köşeli parantezli kısa bir etiket yazarak dinamik içerik gömmesini sağlayan pratik bir mekanizmadır. Kod bilmeyen bir editör bile bunu içeriğe ekleyebilir. add_shortcode() ile tanımlanır ve fonksiyonunuz her zaman çıktıyı echo etmez, döndürür:

add_shortcode( 'cloutr_duyuru', 'cloutr_duyuru_shortcode' );

function cloutr_duyuru_shortcode( $atts ) {
    // Öznitelikler için varsayılan değerler tanımla ve birleştir
    $atts = shortcode_atts(
        array(
            'renk'   => 'indigo',
            'baslik' => 'Duyuru',
        ),
        $atts,
        'cloutr_duyuru'
    );

    // Ayarlardan gelen metni al (varsayılanla birlikte)
    $metin = get_option( 'cloutr_duyuru_metni', 'Merhaba!' );

    // Çıktı üretirken TÜM değişkenleri kaçış (escape) fonksiyonundan geçir
    $html  = '<div class="cloutr-duyuru cloutr-' . esc_attr( $atts['renk'] ) . '">';
    $html .= '<strong>' . esc_html( $atts['baslik'] ) . '</strong> ';
    $html .= esc_html( $metin );
    $html .= '</div>';

    return $html; // shortcode ÇIKTIYI DÖNDÜRÜR, echo ETMEZ
}

Kullanıcı içeriğe [cloutr_duyuru baslik="Kampanya" renk="mint"] yazdığında, shortcode_atts() verdiğiniz varsayılanlarla kullanıcının değerlerini birleştirir. Dikkat edilecek en kritik nokta, çıktının echo yerine return ile döndürülmesidir; aksi halde shortcode içerik neresinde olursa olsun kutu sayfanın en tepesinde belirir. Bu, yeni başlayanların en sık yaptığı hatalardan biridir ve WordPress hata çözümü yazımızda değindiğimiz "içerik yanlış yerde görünüyor" tipi sorunların kökeninde çoğunlukla bu yatar.

Yönetim Paneline Menü ve Ayar Sayfası Ekleme#

Eklentinizin yapılandırılabilir olması için genellikle yönetim panelinde bir ayar sayfası gerekir. Menü öğesi eklemek admin_menu action'ına bağlanan bir fonksiyonla yapılır. En üst seviye bir menü için add_menu_page(), mevcut bir menünün altına alt öğe için add_submenu_page() (ya da doğrudan add_options_page()) kullanılır.

add_action( 'admin_menu', 'cloutr_admin_menu_ekle' );

function cloutr_admin_menu_ekle() {
    add_menu_page(
        'Clou.TR Duyuru Ayarları', // sekme başlığı (<title>)
        'Duyuru Kutusu',           // menüde görünen ad
        'manage_options',          // gereken yetki — kritik güvenlik kontrolü
        'cloutr-duyuru',           // menü slug'ı (benzersiz olmalı)
        'cloutr_ayar_sayfasi',     // sayfayı çizen fonksiyon
        'dashicons-megaphone',     // ikon
        80                         // menüdeki konum
    );
}

function cloutr_ayar_sayfasi() {
    // Ekstra güvenlik: yetkisi olmayan doğrudan erişemesin
    if ( ! current_user_can( 'manage_options' ) ) {
        return;
    }
    ?>
    <div class="wrap">
        <h1>Duyuru Kutusu Ayarları</h1>
        <form method="post" action="options.php">
            <?php
            settings_fields( 'cloutr_ayar_grubu' );
            do_settings_sections( 'cloutr-duyuru' );
            submit_button();
            ?>
        </form>
    </div>
    <?php
}

Buradaki manage_options, WordPress'in yetenek (capability) sistemine ait bir izindir ve yalnızca yöneticilerde bulunur. Menüyü bu yetkiye bağlamak, sıradan bir editörün ayar sayfasını hiç görememesini sağlar. Ayarların gerçekten kaydedilmesi için register_setting() ve add_settings_field() ile WordPress Settings API'sini kullanmak, kendi form işleme kodunuzu yazmaktan hem daha güvenli hem daha az bakım gerektiren yoldur.

Güvenlik: Nonce, Sanitize ve Escape#

Bir eklentinin işlevini yazmak kolay kısımdır; onu güvenli yazmak, sizi amatörden profesyonele ayıran şeydir. WordPress güvenliğinin üç ayağı vardır ve bunları bir cümlede özetleyebiliriz: gelen veriyi temizle (sanitize), çıkan veriyi kaçış yap (escape), işlemleri doğrula (nonce).

Sanitize (temizleme), kullanıcıdan veya dış bir kaynaktan gelen veriyi veritabanına kaydetmeden önce zararsız hale getirmektir. Escape (kaçış), veritabanından okuduğunuz veriyi ekrana basmadan önce, içindeki HTML/JS'in çalışmasını engelleyecek şekilde kodlamaktır. Nonce ise bir formun ya da bağlantının gerçekten sizin sayfanızdan, bilerek gönderildiğini doğrulayan tek kullanımlık bir jetondur; CSRF (siteler arası istek sahteciliği) saldırılarını engeller.

// FORM GÖSTERİLİRKEN: gizli bir nonce alanı ekle
function cloutr_form_goster() {
    ?>
    <form method="post">
        <?php wp_nonce_field( 'cloutr_kaydet', 'cloutr_nonce' ); ?>
        <input type="text" name="cloutr_metin" value="">
        <?php submit_button( 'Kaydet' ); ?>
    </form>
    <?php
}

// FORM İŞLENİRKEN: önce nonce'ı ve yetkiyi doğrula
function cloutr_form_isle() {
    // 1) Nonce geçerli mi? Değilse hiçbir şey yapma
    if ( ! isset( $_POST['cloutr_nonce'] ) ||
         ! wp_verify_nonce( $_POST['cloutr_nonce'], 'cloutr_kaydet' ) ) {
        wp_die( 'Güvenlik doğrulaması başarısız.' );
    }

    // 2) Kullanıcının yetkisi var mı?
    if ( ! current_user_can( 'manage_options' ) ) {
        wp_die( 'Yetkiniz yok.' );
    }

    // 3) Gelen veriyi kaydetmeden önce TEMİZLE
    $temiz_metin = sanitize_text_field( wp_unslash( $_POST['cloutr_metin'] ) );
    update_option( 'cloutr_duyuru_metni', $temiz_metin );
}

Sanitize ve escape için WordPress bağlama göre farklı fonksiyonlar sunar; doğru olanı seçmek önemlidir:

Doğrudan SQL yazmanız gereken nadir durumlarda mutlaka $wpdb->prepare() kullanın; kullanıcı girdisini sorgu metnine birleştirmek SQL enjeksiyonuna açık kapı bırakır:

global $wpdb;
// DOĞRU: parametreler prepare ile bağlanır, enjeksiyon önlenir
$sonuc = $wpdb->get_results(
    $wpdb->prepare(
        "SELECT * FROM {$wpdb->prefix}cloutr_kayitlar WHERE durum = %s LIMIT %d",
        'aktif',
        10
    )
);

Bu üç alışkanlığı baştan içselleştirirseniz, eklentiniz büyüdükçe ortaya çıkacak güvenlik açıklarının büyük çoğunluğunu daha yazarken engellemiş olursunuz. Güvenli veri işleme, sonradan eklenen bir katman değil, kodun dokusudur.

Kodlama Standartları ve Dağıtıma Hazırlık#

Çalışan bir eklenti ile sürdürülebilir bir eklenti arasındaki fark, kodlama standartlarına uymaktır. WordPress'in resmi kod standartları vardır ve bunlara uymak hem başkalarının kodunuzu okumasını kolaylaştırır hem de çakışmaları azaltır. En pratik kurallar şunlardır: tüm fonksiyon, sabit ve global değişken adlarına benzersiz bir önek (cloutr_) verin — böylece başka bir eklentiyle aynı isimde fonksiyon tanımlayıp WordPress'i çökertme riskini ortadan kaldırırsınız.

Metinleri çeviriye hazır yazmak da erken kazanılması gereken bir alışkanlıktır. Kullanıcıya görünen her metni __() veya esc_html__() gibi fonksiyonlarla sarın ve text domain'i header'daki değerle aynı tutun. Böylece eklentiniz ileride kolayca çok dilli hale gelir:

// Çeviriye hazır ve aynı anda kaçış yapılmış metin
echo esc_html__( 'Ayarlar kaydedildi.', 'cloutr-duyuru' );

Geliştirme sırasında hataları görebilmek için yerel ya da test ortamınızda wp-config.php içinde hata ayıklamayı açın; canlıda ise kapalı tutun:

// Sadece geliştirme ortamında — canlıda false yapın
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );    // hataları wp-content/debug.log dosyasına yazar
define( 'WP_DEBUG_DISPLAY', false ); // ekrana basmasın, sadece log'a

Eklentinizi denerken üretim sitenizde değil, ayrı bir kopyada çalışmanız şarttır; canlı siteyi riske atmadan test etmek için staging veya yedekleme altyapısı kullanın. Kod olgunlaştığında readme.txt dosyasını WordPress standardına uygun doldurup eklentiyi bir .zip olarak paketleyebilir, isterseniz resmi eklenti deposuna gönderebilir ya da kendi projelerinizde kullanabilirsiniz. Eklentinizi barındıracağınız ortamın PHP sürümü ve kaynaklarının yeterli olması da performans için önemlidir; bu yüzden geliştirme öncesi altyapınızı gözden geçirmek zaman kazandırır.

Sıkça Sorulan Sorular#

WordPress eklentisi yazmak için hangi bilgi seviyesi gerekir?#

Temel düzeyde PHP bilmek ve HTML ile biraz aşinalık ilk çalışan eklentinizi yazmanız için yeterlidir. WordPress'in kendi fonksiyonlarını (hook, shortcode, option API) öğrenmek programlama deneyiminden çok kalıpları tanımakla ilgilidir; bu rehberdeki örnekleri anlayarak uygularsanız, karmaşık bir bilgisayar bilimi altyapısına ihtiyaç duymadan işlevsel eklentiler geliştirebilirsiniz. İleride veritabanı ve nesne yönelimli PHP bilgisi işinizi kolaylaştırır ama başlangıç için zorunlu değildir.

Kodu functions.php dosyasına yazmak yerine neden eklenti yapmalıyım?#

Temanın functions.php dosyasına yazdığınız her şey o temaya bağlıdır ve tema değiştirdiğinizde ya da temayı güncellediğinizde kaybolur. Eklenti ise temadan tamamen bağımsızdır; sitenizin görünümünü değiştirseniz bile işlevleri çalışmaya devam eder ve başka bir siteye kolayca taşıyabilirsiniz. Görsel olmayan, davranışsal her özelliği eklentiye taşımak profesyonel ve sürdürülebilir bir yaklaşımdır.

Action ile filter arasındaki fark tam olarak nedir?#

Action hook'ları bir olay anında bir şey yapmak içindir ve değer döndürmezler; örneğin bir e-posta göndermek veya sayfaya script eklemek gibi. Filter hook'ları ise kendilerine gelen bir veriyi alıp değiştirmek ve mutlaka geri döndürmek içindir; örneğin bir yazının içeriğini ekranda gösterilmeden önce süzerek sonuna bir not eklemek gibi. Kısacası action "yap", filter "değiştir ve döndür" demektir; filter fonksiyonunda return yazmayı unutmak en sık yapılan hatadır.

Shortcode çıktım neden hep sayfanın en üstünde görünüyor?#

Bu sorunun neredeyse tek nedeni, shortcode fonksiyonunuzun çıktıyı echo etmesidir. WordPress bir shortcode'u işlerken fonksiyonunuzun döndürdüğü değeri içeriğin ilgili yerine yerleştirir; eğer siz echo kullanırsanız çıktı içerik oluşturulmadan çok önce basılır ve sayfanın en tepesinde belirir. Çözüm, tüm HTML'i bir değişkende toplayıp fonksiyonun sonunda return ile döndürmektir.

Eklentimin güvenli olması için minimum neler yapmalıyım?#

En az üç şeyi alışkanlık haline getirmelisiniz: dış kaynaktan gelen tüm veriyi kaydetmeden önce sanitize_* fonksiyonlarıyla temizlemek, ekrana bastığınız her değeri esc_html veya esc_attr gibi fonksiyonlarla kaçış yapmak ve form gönderimlerini wp_nonce_field ile wp_verify_nonce kullanarak doğrulamak. Buna ek olarak her dosyanın başına ABSPATH kontrolü eklemek ve yetki gerektiren işlemlerde current_user_can ile izin doğrulamak, açıkların büyük bölümünü daha kod aşamasında engeller.

Eklentimi canlı sitede mi geliştirmeliyim?#

Kesinlikle hayır; eklenti geliştirmeyi her zaman yerel bir kurulumda veya canlıdan bağımsız bir test ortamında yapmalısınız. Yazdığınız bir kod hatası tüm siteyi erişilemez hale getirebilir ve ziyaretçilerinizi doğrudan etkiler. Bir staging ortamı kullanmak, düzenli yedek almak ve WP_DEBUG ile hata ayıklamayı açık tutmak, sorunları kullanıcılarınız görmeden yakalamanızı sağlar; kod olgunlaştığında değişiklikleri canlıya güvenle taşıyabilirsiniz.

Kapanış#

WordPress eklenti geliştirme, dışarıdan bakıldığında ürkütücü görünse de aslında birkaç sağlam prensibin tekrarından ibarettir: doğru bir plugin header, hook'larla WordPress'in akışına bağlanma, çıktıyı return ile döndürme ve her adımda veriyi temizleyip kaçış yapma. Bu temeli kavradığınızda, basit bir duyuru kutusundan başlayıp kendi iş kurallarınıza özel gelişmiş eklentilere kadar uzanan bir yol açılır. En iyi öğrenme yöntemi de küçük bir fikri alıp bu rehberdeki iskeleti üzerine kurarak gerçekten çalıştırmaktır.

Geliştirdiğiniz eklentileri sorunsuz çalıştırmak, yeterli PHP sürümü ve kaynak sunan sağlam bir altyapı ile başlar. Clou.TR'nin WordPress hosting paketleri güncel PHP, hızlı disk ve kolay yedekleme ile geliştirme yaptığınız siteyi güvenle taşırken; daha fazla kontrol istediğinizde VDS sunucularımız kendi test ve üretim ortamlarınızı özgürce kurmanıza olanak tanır. Projelerinizi büyütmek ve hazır uygulamaları denemek için App Center ile ücretsiz araçlarımıza da göz atabilir, ihtiyacınıza en uygun ortamı bir arada bulabilirsiniz.