Giriş

Öncelikle herkese merhabalar.

Rooteto‘ya yazdığım son yazının üzerinden aylar geçtikten sonra farkettim ki WordPress filter ve action‘larla ilgili Türkçe kaynak neredeyse hiç yok. WordPress öğrenmek için İngilizce’nin şart olmamasını ve yazılım alanında Türkçe kaynak sayısının artmasını isteyen biri olarak “filter ve action nedir, nerede kullanılır, ne işe yarar” temalı bu makaleyi yazmaya karar vermiş bulunmaktayım. Hadi bakalım.

Nedir bunlar?

Filter (filtre olarak çevrilebilir), WordPress’in çekirdek fonksiyonlarında bolca bulunan, böylelikle tema ve eklenti geliştiricilerine çekirdek dosyalarını değiştirmeye gerek bırakmadan ilgili değişkeni/fonksiyonun döndüreceği değeri manipule etmeye olanak tanır.

Action’lar (aksiyon) da filter’lar gibi WordPress çekirdek fonksiyonlarında bolca bulunur. Filter’lardan farkı, döndürülecek sonucu manipule etmek yerine, fonksiyon çalışırken içerisinde tema ve eklenti geliştiricilerinin kendi fonksiyonlarını çalıştırabilmelerini sağlamasıdır.

Çok karışık mı oldu? Ne işe yaradıklarını öğrendiğinizde tanıma gerek kalmayacaktır. 🙂

Nasıl Kullanılır?

Filter:

WordPress’te birçok fonksiyonda filter uygulanır. Bize düşen ise, manipule edeceğimiz değişkende kullanılan filter etiketini öğrenmek ve temamızda/eklentimizde kullanmak. Filtreleme yapan fonksiyonun kullanımı ve parametreleri şu şekilde:

add_filter( $etiket, $uygulanacak_fonksiyon, $oncelik, $parametre_sayisi );

1. $etiket (string): filter’ın etiketi. Zorunludur.
2. $uygulanacak_fonksiyon (string): filtrelemeyi yapacak fonksiyonun adı. Zorunludur.
3. $oncelik (integer): 1-10 arası öncelik sayısı. Aynı etiketi kullanan filtrelerden, öncelik parametresi daha düşük olan daha önce çalıştırılır. Opsiyonel bir parametredir.
4. $parametre_sayisi (integer): Filtre fonksiyonunun kabul edeceği parametre sayısı. Opsiyoneldir

Örnek Kullanım:

the_content etiketli filter’ı kullanarak örnek verelim.

add_filter( 'the_content', 'yazi_sonuna_hoscakal_ekle' );
function yazi_sonuna_hoscakal_ekle( $content ) {
    $hoscakal = "<p>Bir sonraki yazıda görüşmek üzere, hoşçakalın.</p>";

    // içeriğin sonuna hoşçakal cümlesini ekle.
    $content .= $hoscakal;

    // filtrelenmiş içeriği döndür.
    return $content;
}

Java kullanıcılarının “tıpkı @Override gibiymiş” dediğini duyar gibiyim.

Yukarıdaki kodu temanızın functions.php dosyasına eklediğinizde, tüm yazılarınızın sonunda $hoscakal cümlesinin yazdırıldığını göreceksiniz.

Action:

Action’lar belli olaylar sırasında tetiklenerek, temanızda, eklentinizde belirlediğiniz fonksiyonların çalıştırılmasını sağlar. jQuery kullanıyorsanız $(element).on("click", function() { // elemente tıklandı }) kullanımıyla bağlantı kurabilirsiniz.

Kullanım şekli ve parametreleri:

add_action( $etiket, $uygulanacak_fonksiyon, $oncelik, $parametre_sayisi );

1. $etiket (string): action (hook)’ın etiketi. Zorunludur.
2. $uygulanacak_fonksiyon (string): action’ı gerçekleştirecek fonksiyonun adı. Zorunludur.
3. $oncelik (integer): 1-10 arası öncelik sayısı. Aynı etiketi kullanan action’lardan, öncelik parametresi daha düşük olan daha önce çalıştırılır. Opsiyonel bir parametredir.
4. $parametre_sayisi (integer): action fonksiyonunun kabul edeceği parametre sayısı. Opsiyoneldir

Örnek Kullanım

Örneğin siteye yeni bir kayıt yapıldığında, wp_insert_user() fonksiyonu yeni üye bilgilerini veritabanına ekledikten hemen sonra “user_register” etiketli bir action uygular. Bu action’ı kullanarak yeni üyeye “hoşgeldin” temalı bir e-posta gönderelim:

add_action( 'user_register', 'hosgeldin_maili_gonder' );
function hosgeldin_maili_gonder( $user_id ) {
    // kaydolan kullanıcının ID'sini kullanarak e-posta adresini al.
    $alici = get_userdata( $user_id )->user_email;

    $konu = "Sitemize Hoşgeldiniz";

    $mesaj = "Sitemize kaydolduğunuz için teşekkür ederiz :)";

    // mail'i gönder.
    wp_mail( $alici, $konu, $mesaj );
}

Bu kodu temanızın functions.php dosyasına eklediğinizde, sitenize kaydolan kişiye ilgili mesaj gönderilecektir.

Nasıl çalışırlar?

Filter:

WordPress çekirdek fonksiyonlarında apply_filters() fonksiyonuyla değişkenlerin filtrelenmesine imkan verilir. İlgili etiketli filter’a add_filter() fonksiyonunu kullanarak müdahale ettiğimizde, çekirdek fonksiyondaki apply_filters fonksiyonu manipulasyonu gerçekleştirir.

Hepimiz, yazı içeriğinin bir WordPress çekirdek fonksiyonu olan the_content() fonksiyonuyla yazdırıldığını biliyoruz. WordPress kaynak kodlarında bu fonksiyona baktığımızda şöyle bir şeyle karşılaşırız:

function the_content( $more_link_text = null, $strip_teaser = false) {
	$content = get_the_content( $more_link_text, $strip_teaser );

	/**
	 * Filter the post content.
	 *
	 * @since 0.71
	 *
	 * @param string $content Content of the current post.
	 */
	$content = apply_filters( 'the_content', $content );
        ...
	echo $content;
}

$content = apply_filters( 'the_content', $content ); kodunun bulunduğu satır, tam olarak filtrenin uygulandığı satır. Böylelikle ‘the_content’ etiketine uyguladığımız her filter, $content değişkenini, haliyle de the_content() fonksiyonunun çıktısını değiştirecektir.

Action:

WordPress’te birçok önemli olayı gerçekleştiren fonksiyonda do_action() fonksiyonunun çalıştırıldığını görebilirsiniz. Örneğin WordPress’in üye kaydını veritabanına eklemek için kullandığı wp_insert_user() fonksiyonu, tüm işlemler bittikten sonra “user_register” etiketli bir action çalıştırır:

function wp_insert_user( $userdata ) {
    global $wbdb;
    // --kullanıcı bilgileri kontrolü ve veritabanına ekleme--

    /**
    * Fires immediately after a new user is registered.
    *
    * @since 1.5.0
    *
    * @param int $user_id User ID.
    */
    do_action( 'user_register', $user_id );
}

Yukarıdaki WordPress çekirdek fonksiyonundan da anlaşıldığı üzere “user_register” etiketli action’a add_action() fonksiyonuyla referans verdiğiniz her fonksiyon, wp_insert_user() fonksiyonu çalışırken do_action( 'user_register', $user_id ) satırında çağrılacaktır. Böylelikle yeni kayıt sonrası (Nasıl Kullanılır? bölümündeki örnekteki gibi) yeni kullanıcıya e-posta gönderebilecek, yeni kullanıcının user meta’sını güncelleyebileceksiniz.

Kendi Filter ve Action’ınızı Tanımlama

Bir tema ya da eklenti yazıyorsanız, yazılımınızı kullanacak kişilerin kodlarınızı değiştirmek yerine fonksiyonlarınızı manipule etmesini isteyebilirsiniz. Action ve filter’ları tema/eklentinizde kullanmak diğer geliştiricilere temanızı/eklentinizi mükemmelleştirecek eklentiler yazabilmesine de olanak tanır. Bu şekilde temanız/eklentiniz çok daha “geliştirici dostu” olacaktır.

Örneğin yeni kaydolan kullancııya e-posta gönderen bir eklenti hazırladınız ve WordPress Eklenti’lerine eklediniz. Yeni kullanıcıya gönderilecek e-posta’nın başlık ve içeriğine filter ekleyebilir, e-posta gönderildikten önce ve sonrasına action uygulayabilirsiniz.

add_action( 'user_register', 'hosgeldin_maili_gonder' );
function hosgeldin_maili_gonder( $user_id ) {
    // kaydolan kullanıcının ID'sini kullanarak e-posta adresini al.
    $alici = get_userdata( $user_id )->user_email;

    $konu = "Sitemize Hoşgeldiniz"; // varsayılan e-posta başlığı.
    $konu = apply_filters( 'eklentim_mail_basligi', $konu );

    $mesaj = "Sitemize kaydolduğunuz için teşekkür ederiz :)"; // varsayılan mesaj.
    $mesaj = apply_filters( 'eklentim_mail_mesaji', $mesaj );

    do_action( 'eklentim_mail_gondermeden_once' );

    // mail'i gönder.
    wp_mail( $alici, $konu, $mesaj );

    do_action( 'eklentim_mail_gonderdikten_sonra' );
}

Bu sayede geliştiriciler fonksiyon içeriğini değiştirmeye gerek duymadan mail başlık ve içeriğini filtreleyebilir, mail gönderilmeden önce ve sonrasında diledikleri işlemi yapabilirler.

Not: Yukarıdaki eklentiyi yazmayı ve bu şekilde filtrelemek pek de mantıklı olmaz. Ancak adı üstünde bu bir örnek.

Meraklısına:

• add_action() fonksiyonu add_filter() fonksiyonunu döndürür. Ancak add_action() yerine add_filter() kullanılmamalıdır.
• Custom Post Type oluştururken WordPress’in ‘init‘ isimli action’ı kullanılır.

Kapanış

Tema/eklenti yazarken filter ve action’ları kullanarak kolayca WordPress fonksiyonlarını manipule edebilir, bu manipulasyona gerek duymadığımızda kolayca kaldırabiliriz. Ayrıca tema/eklentimizin kolayca manipule edilebilir olması da esneklik ve “kolay düzenlenebilirlik” açısından oldukça işimize yarar.

• Function Reference/add action
• Function Reference/add filter
• Plugin API/Action Reference/user register
• Filters vs Actions