Named Arguments Bisa Diam-Diam Merusak Hook WordPress-mu

Pluginmu bisa lolos test, aman di staging, lalu pecah setelah dependency kecil mengganti nama parameter callback. Bukan karena hook WordPress berubah total. Justru karena PHP named arguments membuat nama parameter yang dulu “detail internal” berubah menjadi kontrak publik.

Masalahnya Bukan Hook, Tapi Nama yang Mendadak Jadi API

Sejak PHP 8, named arguments memberi developer opsi memanggil function berdasarkan nama parameter. Fitur ini nyaman untuk API eksplisit, tetapi cukup berbahaya untuk ekosistem WordPress yang sangat bergantung pada action, filter, callback, dan extension point.

Di WordPress, banyak callback awalnya ditulis seperti ini:

add_filter('my_plugin_price', 'format_price', 10, 3);

function format_price($price, $product, $context) {
    return $price;
}

Lalu pada versi berikutnya, author mengganti nama parameter agar lebih jelas:

function format_price($amount, $item, $args) {
    return $amount;
}

Secara positional, ini aman. Namun, kalau ada kode internal, framework bridge, atau test helper yang memanggil callback dengan price:, perubahan itu langsung jadi breaking change.

Kenapa Advanced WP Dev Perlu Peduli

Core WordPress sendiri masih banyak memakai pola procedural dan positional. Namun, plugin modern sering membungkus hook dalam service container, event dispatcher, REST layer, GraphQL resolver, atau automation runner. Di titik inilah risiko muncul.

Biasanya bug muncul dari kombinasi ini:

• Callback dipanggil manual oleh test suite atau framework adapter.
• Hook API dibungkus menjadi event object atau callable map.
• Parameter rename dianggap refactor aman.
• Integrasi pihak ketiga memakai named arguments karena terlihat lebih readable.

Akibatnya, perubahan kecil seperti $post menjadi $wp_post bisa memecahkan consumer yang memanggil post:.

Aturan Praktis: Kalau Callback Bisa Dipanggil Orang, Namanya Publik

Framework author sering menjaga signature function, tetapi lupa menjaga nama parameter. Padahal, pada PHP 8+, signature bukan cuma tipe, default value, dan urutan. Nama parameter juga masuk zona kompatibilitas.

Pakai mental model sederhana ini:

• Private callback, bebas rename jika tidak diekspos.
• Hook callback publik, nama parameter harus stabil.
• Documented API, named arguments perlu dianggap supported atau sengaja dilarang.
• Extension point, parameter name adalah bagian dari kontrak developer experience.

Ini terasa berlebihan, tetapi justru mengurangi support ticket aneh setelah update minor.

Pola Aman untuk WordPress Hooks dan Named Arguments

1. Jangan Rename Parameter Publik Tanpa Deprecation Path

Kalau callback, filter helper, atau service method sudah dipakai consumer, jangan ubah $post_id menjadi $id diam-diam. Lebih baik pertahankan nama lama, lalu benahi clarity lewat PHPDoc.

/**
 * @param int $post_id The WordPress post ID.
 */
function sync_post_meta($post_id, array $payload = []) {
    // stable API
}

2. Pisahkan Hook Adapter dari Logic Internal

Ini pola paling bersih. Hook adapter menjaga signature stabil. Logic internal bebas memakai nama yang lebih bagus.

add_action('save_post', [SyncController::class, 'on_save_post'], 10, 3);

final class SyncController {
    public static function on_save_post($post_id, $post, $update): void {
        self::sync(
            contentId: $post_id,
            entity: $post,
            isUpdate: $update
        );
    }

    private static function sync(int $contentId, WP_Post $entity, bool $isUpdate): void {
        // internal names can evolve safely
    }
}

Dengan begitu, hook contract tetap kompatibel, sementara domain code tetap rapi.

3. Untuk Filter Publik, Dokumentasikan Nama Parameter

Jika kamu membuat filter untuk plugin lain, dokumentasi harus jelas. Jangan cuma sebut jumlah argumen.

/**
 * Filters computed discount.
 *
 * @param float $discount Stable parameter name.
 * @param int   $user_id  Stable parameter name.
 * @param array $context  Stable parameter name.
 */
$discount = apply_filters('acme_discount', $discount, $user_id, $context);

Selain itu, jangan mengganti nama di contoh kode antar versi. Dokumentasi yang berubah-ubah sering jadi sumber copy paste bug.

Checklist Audit 10 Menit Sebelum Rilis Minor

Sebelum publish versi baru, jalankan audit kecil ini. Cepat, tetapi efeknya besar untuk plugin yang punya banyak integrasi.

• Cari perubahan pada function, method public, dan static callback.
• Bandingkan nama parameter dengan versi rilis sebelumnya.
• Tandai callback yang terdaftar via add_action() dan add_filter().
• Review method yang dipakai container, REST route, WP-CLI command, shortcode, block render callback.
• Tambahkan test untuk pemanggilan named arguments pada API yang memang kamu support.
• Tambahkan dokumentasi jika named arguments sengaja tidak dijamin stabil.

Kalau kamu sudah punya CI untuk kompatibilitas PHP, gabungkan audit ini dengan matrix PHP 8.0 sampai versi target. Untuk konteks upgrade lebih luas, baca juga checklist PHP 8.4 untuk plugin WordPress.

Cara Menulis Kebijakan Kompatibilitas yang Nggak Membingungkan

Kamu bisa memilih mendukung named arguments, atau tidak. Yang penting, tulis eksplisit.

Contoh kebijakan yang aman:

Public API methods support positional arguments. Named arguments are only supported for methods documented as stable. Hook callback parameter names may remain stable across minor releases, but private methods are not covered by backward compatibility.

Kalimat seperti ini membantu framework/plugin authors menghindari asumsi liar. Selain itu, tim internal juga punya batas jelas saat refactor.

Rujukan Teknis yang Perlu Kamu Simpan

Untuk memahami behavior resminya, baca dokumentasi PHP named arguments. Untuk sisi WordPress, cek referensi add_filter() dan apply_filters(). Kombinasi tiga halaman itu cukup untuk melihat kenapa parameter name sekarang punya bobot lebih besar.

FAQ

Apakah WordPress hooks otomatis memakai named arguments?

Tidak. WordPress hooks umumnya meneruskan argumen secara positional. Namun, wrapper, adapter, test helper, dan kode integrasi bisa memanggil callback dengan named arguments.

Apakah mengganti nama parameter selalu breaking change?

Untuk private code, biasanya aman. Untuk public API, documented callback, atau method yang bisa dipanggil consumer, anggap breaking change sejak PHP 8.

Bagaimana cara paling aman refactor callback hook?

Pertahankan signature adapter hook, lalu pindahkan logic ke method internal dengan nama parameter baru. Jadi kompatibilitas publik tetap aman, sementara kode domain tetap bersih.

Penutup: Stabilkan Kontrak Kecil Sebelum Jadi Insiden Besar

named arguments WordPress hooks bukan sekadar detail sintaks PHP. Ini soal kontrak API yang diam-diam melebar. Karena itu, sebelum rename parameter pada callback publik, cek dulu siapa yang mungkin memanggilnya.

Kalau kamu membangun framework, plugin komersial, atau library WordPress, mulai audit hook signature dari rilis berikutnya. Mau dapat checklist WordPress engineering yang lebih tajam? Subscribe newsletter Google lewat blok di bawah ini.