Wordpress Hooks Actions Filters Priorities Callbacks

Definisi singkat

Hooks di WordPress adalah mekanisme untuk menyisipkan kode tanpa mengubah core, theme, atau plugin lain secara langsung. Dengan hooks, WordPress membuka titik sambung di alur eksekusi: ada yang dipakai untuk menjalankan aksi pada momen tertentu, ada yang dipakai untuk mengubah nilai sebelum dipakai lebih lanjut.

Secara praktis, hooks adalah salah satu alasan ekosistem WordPress bisa sangat extensible. Plugin, theme, dan child theme bisa saling menambah perilaku tanpa saling menimpa file inti.

Jenis hook

WordPress punya dua jenis hook utama:

• Actions: dipakai saat kamu ingin menjalankan sesuatu pada momen tertentu.
• Filters: dipakai saat kamu ingin menerima nilai, mengubahnya, lalu mengembalikan nilai baru.

Kapan pakai action

Pakai action kalau tujuanmu adalah efek samping, misalnya:

• enqueue CSS/JS
• kirim email
• simpan log
• register CPT atau taxonomy
• menampilkan banner atau notice
• menginisialisasi state atau service

Action cocok ketika kamu tidak perlu mengembalikan nilai untuk dipakai alur berikutnya.

Contoh:

php

add_action('wp_enqueue_scripts', function () {
    wp_enqueue_style('theme-main', get_stylesheet_uri());
});

Di sini callback hanya menjalankan pekerjaan. Tidak ada nilai yang harus diteruskan kembali.

Kapan pakai filter

Pakai filter kalau kamu ingin mengubah data yang sedang lewat, misalnya:

• ubah judul post
• ubah excerpt
• ubah URL
• ubah konten sebelum tampil
• ubah argumen query
• ubah label atau teks default

Filter harus mengembalikan nilai. Kalau tidak return, hasilnya bisa rusak atau jadi null.

Contoh:

php

add_filter('the_title', function ($title) {
    return '[Draft] ' . $title;
});

Kalau yang dibutuhkan adalah transformasi nilai, filter adalah pilihan yang benar. Kalau hanya menjalankan proses samping, action lebih tepat.

Cara kerja hook

Urutan dasarnya begini:

1. WordPress mencapai titik hook tertentu.
2. WordPress mencari semua callback yang terdaftar pada hook itu.
3. Callback dieksekusi sesuai priority.
4. Untuk filter, hasil callback diteruskan ke callback berikutnya.
5. Untuk action, callback dijalankan tanpa perlu mengembalikan nilai.

Secara mental model:

• action = “jalankan ini saat momen X terjadi”
• filter = “ambil nilai ini, ubah, lalu teruskan”

Callback

Callback adalah fungsi yang dipanggil saat hook aktif. Callback bisa berupa:

• named function
• anonymous function / closure
• method pada object
• static method

Contoh named function:

php

function mytheme_add_body_class($classes) {
    $classes[] = 'has-custom-banner';
    return $classes;
}
add_filter('body_class', 'mytheme_add_body_class');

Contoh object method:

php

class Theme_Hooks {
    public function register() {
        add_action('init', [$this, 'register_post_types']);
    }
 
    public function register_post_types() {
        register_post_type('book', []);
    }
}
 
$hooks = new Theme_Hooks();
$hooks->register();

Callback yang baik

Callback yang sehat biasanya:

• kecil dan fokus
• jelas tanggung jawabnya
• mudah dilepas dengan remove_action() / remove_filter() bila perlu
• tidak bergantung pada state global yang terlalu banyak

Kalau callback terlalu besar, susah ditebak efeknya dan susah di-debug.

Priority

Priority menentukan urutan eksekusi callback pada hook yang sama.

• angka lebih kecil dijalankan lebih dulu
• angka lebih besar dijalankan belakangan
• default WordPress adalah 10

Contoh:

php

add_action('wp_head', 'mytheme_output_meta', 5);
add_action('wp_head', 'mytheme_output_ads', 20);

mytheme_output_meta dijalankan sebelum mytheme_output_ads.

Dampak priority

Priority penting saat:

• callback lain bergantung pada hasil callback sebelumnya
• kamu ingin menyisipkan output sebelum/sesudah plugin lain
• kamu ingin mengubah data setelah plugin lain memprosesnya

Untuk filter, urutan ini bahkan lebih terasa karena hasil callback pertama menjadi input callback berikutnya.

Contoh filter dengan beberapa tahap:

php

add_filter('the_content', 'add_notice', 5);
add_filter('the_content', 'wrap_content', 20);

Kalau add_notice() menambahkan markup di awal, wrap_content() akan menerima hasil yang sudah dimodifikasi.

Jebakan priority

Jebakan umum:

• menganggap 10 selalu “paling akhir” — padahal cuma default
• lupa bahwa plugin lain bisa pakai priority lebih kecil atau lebih besar
• membuat filter bergantung pada urutan tanpa dokumentasi internal
• mencoba memperbaiki urutan dengan menaruh semua logic di satu callback besar

Kalau urutan itu penting, tulis eksplisit priority-nya dan beri komentar singkat.

Hook utama yang sering dipakai

Beberapa hook WordPress yang sering muncul di theme/plugin work:

Action umum

• init — register post type, taxonomy, rewrite, atau inisialisasi ringan
• wp_enqueue_scripts — enqueue asset frontend
• admin_enqueue_scripts — enqueue asset admin
• after_setup_theme — setup theme support
• widgets_init — register widget area
• save_post — reaksi saat post disimpan
• admin_init — setup admin-side behavior
• wp_head / wp_footer — output markup tambahan

Filter umum

• the_title — ubah judul sebelum render
• the_content — ubah konten sebelum tampil
• excerpt_length — ubah panjang excerpt
• body_class — tambah class body
• upload_mimes — tambah tipe file upload
• redirect_canonical — kontrol canonical redirect
• posts_where / posts_join / posts_clauses — ubah query SQL level tertentu

Hook debugging

Debugging hook sering terasa susah karena masalahnya bukan di syntax, tapi di kapan hook jalan, siapa yang mendaftar, dan priority mana yang menang.

Langkah debugging yang berguna

1. Pastikan hook memang dieksekusi

Kadang callback benar, tapi hook-nya tidak pernah terpanggil karena dipasang di tempat yang salah.

Contoh: wp_enqueue_scripts hanya relevan untuk frontend, bukan untuk semua context.

2. Log sederhana di callback

Tambahkan error_log() sementara untuk memastikan callback dipanggil.

php

add_action('init', function () {
    error_log('init dipanggil');
});

3. Cek priority dan jumlah argumen

Masalah umum adalah callback menerima argumen yang salah jumlahnya.

php

add_filter('the_content', function ($content, $post_id) {
    return $content;
}, 10, 2);

Kalau kamu lupa angka 2 di akhir, WordPress tidak akan mengirim argumen tambahan ke callback.

4. Cari hook ganda

Callback yang sama bisa terdaftar dua kali tanpa sadar, terutama kalau file include dipanggil berulang.

5. Periksa remove_action() / remove_filter()

Removal harus cocok dengan:

• nama hook
• callback yang sama persis
• priority yang sama

Kalau salah satu beda, hook tidak terhapus.

Alat bantu debugging

Beberapa pendekatan yang biasa dipakai:

• error_log() untuk cek runtime
• plugin seperti Query Monitor untuk melihat hook, query, dan request flow
• pencarian global di codebase untuk menemukan add_action() / add_filter()
• inspeksi struktur callback saat refactor plugin besar

Jebakan umum saat menyusun plugin atau theme

1. Memilih action padahal butuh filter

Kalau kamu perlu mengubah nilai dan justru memakai action, hasilnya tidak akan masuk ke alur data.

Contoh salah:

php

add_action('the_title', function ($title) {
    return 'X ' . $title;
});

the_title adalah filter, bukan action. Harus pakai add_filter().

2. Lupa return pada filter

Ini salah satu bug paling sering.

php

add_filter('the_content', function ($content) {
    $content .= '<p>Catatan tambahan</p>';
});

Callback di atas tidak mengembalikan apa pun. Hasil akhirnya bisa kacau.

3. Hook terlalu awal atau terlalu lambat

Ada hook yang baru aman dipakai setelah WordPress selesai inisialisasi tertentu.

Contoh:

• register CPT terlalu awal bisa bentrok dengan dependensi lain
• enqueue script terlalu akhir bisa tidak ikut tercetak
• modify query di hook yang salah bisa tidak berpengaruh

4. Bergantung pada urutan plugin lain tanpa kontrol

Kalau sistemmu bergantung pada plugin pihak ketiga, priority dan presence plugin lain harus dianggap sebagai dependency nyata.

5. Menaruh terlalu banyak logic di closure anonim

Closure kecil itu oke. Tapi kalau logic-nya besar, lebih baik pindahkan ke method atau function bernama supaya:

• bisa di-reuse
• lebih mudah diuji
• lebih mudah di-remove
• lebih mudah dibaca

6. remove_action() gagal karena callback tidak identik

Closure anonim yang dibuat inline sulit dihapus karena referensinya tidak sama.

Kalau kamu tahu hook akan di-remove, pakai named function atau method class.

7. Hook dan state global bercampur

Hook sering jalan di banyak context: frontend, admin, AJAX, REST, cron. Kalau callback tidak cek context, theme/plugin bisa memunculkan side effect yang aneh.

Pola implementasi yang sehat

Untuk theme

• pakai after_setup_theme untuk theme support
• pakai wp_enqueue_scripts untuk asset
• pakai filter untuk ubah output yang memang harus ikut flow rendering
• simpan hook di satu tempat yang jelas, misalnya class atau file hooks.php

Untuk plugin

• pisahkan registration, callback, dan business logic
• hindari side effect global di file utama plugin
• gunakan priority secara sadar, bukan kebetulan
• dokumentasikan hook custom jika plugin menyediakan extensibility point

Untuk custom hooks

Kalau plugin/theme kamu menyediakan extensibility, kamu bisa membuat hook sendiri:

php

do_action('myplugin_before_render');
 
$value = apply_filters('myplugin_price', $value);

Gunakan do_action() untuk action custom dan apply_filters() untuk filter custom.

Ringkasan cepat

• Action dipakai untuk menjalankan pekerjaan pada momen tertentu.
• Filter dipakai untuk mengubah nilai lalu mengembalikannya.
• Priority menentukan urutan callback; angka kecil jalan lebih dulu.
• Callback adalah fungsi/method yang menempel ke hook.
• Debugging hook biasanya soal context, urutan, jumlah argumen, dan callback identik atau tidak.
• Untuk plugin/theme, masalah paling sering bukan konsep dasar, tapi salah memilih hook, lupa return, dan mengandalkan urutan yang tidak dikontrol.

Referensi terkait

• WordPress Plugin Handbook
• WordPress Theme Handbook
• add_action() / add_filter() / do_action() / apply_filters() di dokumentasi WordPress