Argumen Bernama

Argumen bernama untuk kejelasan di titik panggil dan melompati nilai default.

Daftar isi

Pemanggilan fungsi dengan banyak parameter default sering memaksa penulisan argumen yang tidak dibutuhkan hanya demi mencapai satu posisi tertentu. Argumen bernama (named arguments), tersedia sejak PHP 8.0, menyelesaikan persoalan itu dengan memetakan nilai ke parameter melalui namanya. Topik ini membahas sintaks argumen bernama, penggunaannya pada fungsi bawaan PHP, aturan pencampurannya dengan argumen posisional, serta error yang muncul bila nama parameter keliru.

Sintaks argumen bernama#

Argumen bernama ditulis dengan nama parameter diikuti tanda titik dua dan nilainya, misalnya lebar: 30. Nama yang digunakan harus persis sama dengan nama parameter pada deklarasi fungsi, tanpa tanda $. Nilai yang dipetakan melalui nama tidak lagi bergantung pada posisi, sehingga urutan penulisannya bebas dan argumen yang tidak disebutkan tetap menggunakan nilai defaultnya. Argumen bernama juga tidak mengubah jumlah argumen yang wajib diisi, karena parameter tanpa nilai default tetap harus mendapat nilai, baik melalui nama maupun posisi.

Cara ini memberi dua keuntungan pada titik panggil. Pertama, argumen yang diubah dituliskan secara eksplisit, sehingga formatBaris('Total', lebar: 30) langsung terbaca tanpa membuka deklarasi fungsinya. Kedua, nilai default di tengah daftar dapat dilompati, karena hanya parameter yang disebut yang diisi dan sisanya menggunakan nilai bawaan deklarasinya.

Skrip berikut mendeklarasikan fungsi pemformat dengan tiga parameter default. Panggilan pertama menggunakan seluruh nilai default, panggilan kedua hanya mengubah lebar, sedangkan panggilan ketiga mengubah rata dan pengisi tanpa mengubah lebar di tengah daftar.

php format-baris.php

<?php
declare(strict_types=1);

function formatBaris(string $teks, int $lebar = 20, string $pengisi = '.', string $rata = 'kanan'): string
{
    $panjang = mb_strlen($teks);
    if ($panjang >= $lebar) {
        return $teks;
    }
    $pengisiPenuh = str_repeat($pengisi, $lebar - $panjang);
    if ($rata === 'kiri') {
        return $teks . $pengisiPenuh;
    }
    return $pengisiPenuh . $teks;
}

echo formatBaris('Total'), "\n";
echo formatBaris('Total', lebar: 30), "\n";
echo formatBaris('Keterangan', rata: 'kiri', pengisi: '-'), "\n";

text Keluaran

...............Total
.........................Total
Keterangan----------

Panggilan ketiga memperlihatkan manfaat utamanya, yaitu lebar tetap bernilai 20 tanpa perlu menuliskan 20 pada posisi kedua.

Melewatkan nilai default pada fungsi bawaan#

Fungsi bawaan PHP dapat menggunakan argumen bernama dengan nama parameter yang tercantum pada dokumentasinya. Fungsi bawaan dengan banyak parameter opsional adalah kandidat terbaik, karena argumen posisional memaksa penulisan seluruh parameter yang mendahului parameter yang ingin diubah.

Dua contoh yang sering digunakan adalah htmlspecialchars() dan number_format(). Fungsi htmlspecialchars() menerima parameter $string, $flags, $encoding, dan $double_encode, sehingga panggilan dengan double_encode: false langsung menuju parameter keempat tanpa mengisi $flags maupun $encoding. Fungsi number_format() menerima $decimals, $decimal_separator, dan $thousands_separator, sehingga ketiganya dapat dituliskan dengan namanya agar maksud pemanggilan terbaca jelas.

php fungsi-bawaan-bernama.php

<?php
declare(strict_types=1);

$rumus = 'Panjang &amp; lebar';

echo htmlspecialchars($rumus), "\n";
echo htmlspecialchars($rumus, double_encode: false), "\n";
echo number_format(1234567.891, decimals: 2, decimal_separator: ',', thousands_separator: '.'), "\n";

text Keluaran

Panjang &amp;amp; lebar
Panjang &amp; lebar
1.234.567,89

Baris pertama menyandikan ulang karakter & pada & menjadi &amp;, sedangkan baris kedua membiarkan entitas HTML yang sudah ada, karena parameter double_encode dimatikan melalui namanya.

Nama parameter fungsi bawaan dapat dilihat pada halaman dokumentasi masing-masing fungsi, tepat pada tanda tangan fungsinya. Editor teks yang memiliki dukungan penyelesaian kode biasanya menampilkan daftar nama parameter beserta nilai defaultnya sebagai saran, sehingga risiko salah nama berkurang. Kebiasaan membaca tanda tangan fungsi juga membantu ketika versi PHP menambahkan parameter baru pada fungsi yang sudah ada.

Aturan pencampuran dengan argumen posisional#

Argumen posisional dan argumen bernama boleh dicampur pada satu pemanggilan, dengan satu aturan tegas, yaitu seluruh argumen posisional harus ditulis lebih dahulu. Setelah satu argumen bernama muncul, argumen berikutnya wajib dituliskan dengan nama juga, karena parser PHP tidak lagi dapat menetapkan posisi parameter bagi nilai yang menyusul.

Aturan tersebut tetap berlaku meskipun nilai yang menyusul kebetulan cocok dengan posisi parameter berikutnya. Pencampuran yang lazim dan benar adalah menuliskan argumen wajib secara posisional, lalu argumen opsional yang diubah secara bernama, misalnya formatBaris('Keterangan', 20, rata: 'kiri'). Pola ini menjaga daftar argumen tetap pendek dan menonjolkan argumen yang berubah.

Potongan berikut memperlihatkan bentuk yang ditolak PHP. Kesalahannya berupa error fatal yang terdeteksi pada tahap kompilasi berkas. Karena itu, potongan ini tidak dijalankan, dan bentuk yang ditolak beserta pesannya dituliskan sebagai komentar.

php Contoh: argumen posisional setelah argumen bernama

// tidak-dijalankan
// formatBaris(teks: 'Total', 30);
// Error: Cannot use positional argument after named argument

Pengujian pada berkas sungguhan memperlihatkan bahwa error tersebut muncul pada tahap kompilasi, bukan saat fungsi dideklarasikan, sehingga tidak ada satu pernyataan pun yang sempat dieksekusi. Pesannya menyebut argumen posisional yang bermasalah, sehingga penulisannya diperbaiki dengan menambahkan nama parameter pada nilai yang menyusul atau dengan menuliskan ulang seluruh pemanggilan secara posisional.

Nama parameter yang tidak dikenal#

Nama argumen harus cocok dengan nama parameter yang dideklarasikan. Apabila nama yang ditulis tidak ada pada deklarasi, PHP melemparkan Error dengan pesan Unknown named parameter saat fungsi dipanggil. Error ini dapat ditangkap dengan try/catch, sehingga pemeriksaan nama parameter dapat diuji tanpa menghentikan program.

Nama parameter pada proyek sendiri juga dijaga dengan aturan yang konsisten, karena nama itulah yang menjadi kontrak bagi seluruh titik panggil argumen bernama. Mengganti nama parameter berarti mengubah kontrak tersebut meskipun tipe dan urutannya tidak berubah, sehingga pemanggilan yang menggunakan nama lama langsung gagal saat berkas dijalankan. Karena itu, penggantian nama parameter diperlakukan sebagai perubahan yang dapat memutus kode lain, sama seperti penggantian nama fungsi.

Sumber kesalahan yang paling sering adalah menulis nama versi Inggris atau versi lain yang mirip, misalnya username padahal deklarasinya menggunakan $namaPengguna, serta menuliskan tanda $ pada nama argumen yang memang tidak boleh ada. Membaca deklarasi fungsi di dokumentasi resmi atau di definisi kodenya sebelum menulis argumen bernama mencegah kesalahan semacam ini.

php nama-tidak-dikenal.php

<?php
declare(strict_types=1);

function sapa(string $nama, string $salam = 'Halo'): string
{
    return $salam . ', ' . $nama . '!';
}

echo sapa(nama: 'Budi'), "\n";

try {
    echo sapa(pengguna: 'Budi');
} catch (Error $e) {
    echo $e->getMessage(), "\n";
}

text Keluaran

Halo, Budi!
Unknown named parameter $pengguna

Kesalahan umum#

Menulis argumen posisional setelah argumen bernama. PHP menolak bentuk ini dengan error fatal pada tahap kompilasi karena posisi parameter tidak dapat ditetapkan lagi. Solusinya, urutkan ulang pemanggilan sehingga seluruh argumen posisional berada di depan.
Menyalin nama parameter dari versi PHP yang berbeda. Nama parameter fungsi bawaan dapat berubah antar versi, misalnya ketika parameter baru ditambahkan. Pastikan nama yang ditulis sesuai dengan versi PHP yang digunakan dan baca bagian tanda tangan fungsi pada dokumentasinya.
Menganggap argumen bernama mengubah definisi fungsi. Argumen bernama hanya berlaku pada titik panggil, sehingga urutan parameter pada deklarasi tidak berubah. Deklarasi tetap ditulis dengan urutan yang logis, sedangkan kebebasan urutan hanya milik pemanggil.
Menggunakan argumen bernama pada setiap pemanggilan tanpa memandang panjang daftar argumennya. Setiap nama ditulis dan dibaca secara eksplisit, sehingga baris pemanggilan menjadi lebih panjang dibandingkan bentuk posisional. Untuk fungsi sederhana dengan satu atau dua argumen, bentuk posisional tetap lebih ringkas, sedangkan argumen bernama dicadangkan untuk pemanggilan dengan banyak opsi.

Ringkasan#

Argumen bernama ditulis namaParameter: nilai dan memetakan nilai ke parameter lewat namanya, sehingga urutan di titik panggil menjadi bebas.
Parameter default di tengah daftar dapat dilompati, dan hanya parameter yang disebut yang diisi.
Fungsi bawaan PHP menerima argumen bernama dengan nama parameter dari dokumentasinya, contohnya double_encode: false pada htmlspecialchars().
Argumen posisional wajib mendahului argumen bernama, dan nama yang tidak dikenal melemparkan Error berupa Unknown named parameter.

Referensi#

Argumen bernama — Manual PHP — Menetapkan sintaks, aturan urutan, dan perilaku argumen bernama di PHP 8.0.
Argumen fungsi — Manual PHP — Mencantumkan nama parameter resmi yang dipakai oleh fungsi bawaan PHP.