Debugging dengan Xdebug

Membaca stack trace dan menabur echo diagnostik memang menolong, tetapi keduanya pasif: kita hanya bisa mengamati hasil akhirnya. Xdebug adalah ekstensi PHP yang mengubah cara kita bekerja — eksekusi bisa dijeda di baris mana pun, isi variabel diperiksa langsung, dan setiap langkah dipantau tanpa menyentuh satu baris kode pun. Chapter ini membahas apa saja yang ditambahkan Xdebug, cara memasang dan mengaktifkannya, konsep mode, serta pengaturan step debugging bersama IDE. Lingkungan buku ini sengaja tidak memasang Xdebug, jadi kita akan memeriksa ketidakhadirannya secara jujur lewat kode, sambil mempelajari konfigurasi yang Anda perlukan di mesin sendiri.

Apa yang Ditambahkan Xdebug #

Xdebug bukan sekadar pengganti var_dump(). Ekstensi ini menyuntikkan kemampuan observasi ke dalam runtime PHP itu sendiri, dan kemampuannya dikelompokkan dalam beberapa mode yang bisa aktif bersamaan:

Mode-mode inilah yang kita aktifkan atau matikan lewat satu directive xdebug.mode, sehingga ekstensi yang sama melayani kebutuhan debugging sehari-hari maupun analisis kinerja. Kita akan bahas tiap mode setelah urusan pemasangan selesai.

Memeriksa Status Xdebug dengan Jujur #

Sebelum mengandalkan Xdebug, pastikan ekstensi tersebut benar-benar dimuat oleh PHP yang sedang berjalan. Cara tercepat dari terminal adalah menyaring daftar ekstensi:

php -m | grep -i xdebug

Pada lingkungan buku ini, perintah di atas tidak menghasilkan keluaran apa pun — artinya Xdebug tidak termuat. Pemeriksaan yang lebih portabel dilakukan dari dalam kode, karena cara ini juga bisa dipakai aplikasi Anda untuk mendeteksi ketersediaan fitur:

<?php
$ekstensiAktif = get_loaded_extensions();

echo "Ekstensi xdebug dimuat: ";
echo in_array("xdebug", $ekstensiAktif, true) ? "ya" : "tidak";
echo "\n";

echo "Function xdebug_info() tersedia: ";
echo function_exists("xdebug_info") ? "ya" : "tidak";
echo "\n";

Output yang Dihasilkan:

Ekstensi xdebug dimuat: tidak
Function xdebug_info() tersedia: tidak

Dua baris keluaran tersebut adalah hasil nyata di lingkungan buku ini: tidak dan tidak. Di mesin Anda yang sudah memasang dan mengaktifkan Xdebug, kedua baris akan berubah menjadi ya. Function xdebug_info() memang hanya ada ketika ekstensi termuat, sehingga function_exists() adalah detektor paling andal; daftar dari get_loaded_extensions() menjadi konfirmasi kedua.

Instalasi dan Aktivasi #

Xdebug dikembangkan terpisah dari PHP, sehingga pemasangannya berbeda antar sistem. Di Ubuntu/Debian, paketnya tersedia lewat apt:

sudo apt install php-xdebug

Sementara itu, pengguna PECL dapat mengompilasinya sendiri:

pecl install xdebug

Langkah penting berikutnya adalah mendaftarkannya di berkas php.ini. Xdebug harus dimuat sebagai zend_extension, bukan extension biasa, karena Xdebug menghubungkan dirinya langsung ke engine Zend untuk bisa mengendalikan eksekusi:

zend_extension=xdebug.so

Mode Xdebug #

Satu ekstensi, banyak peran — dan peran tersebut dipilih lewat directive xdebug.mode. Nilainya boleh lebih dari satu, dipisah koma:

xdebug.mode=develop,debug

Tabel berikut merangkum mode yang tersedia beserta gunanya:

Untuk step debugging, mode yang wajib aktif adalah debug. Mode develop layak menyertainya karena manfaatnya terasa langsung setiap hari.

Step Debugging Bersama IDE #

Step debugging membutuhkan dua pihak yang saling terhubung: PHP yang berjalan dengan Xdebug, dan IDE yang mendengarkan. Sisi PHP diatur lewat php.ini:

xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003

Directive xdebug.start_with_request=yes memerintahkan Xdebug segera menghubungi IDE setiap kali skrip atau request dimulai. Sisi IDE perlu “mendengarkan” di port yang sama. Di VS Code, konfigurasi tersebut ditulis pada berkas launch.json setelah memasang ekstensi PHP Debug:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003
        }
    ]
}

Pengguna PhpStorm tidak perlu konfigurasi JSON: cukup klik ikon “Start Listening for PHP Debug Connections”. Setelah kedua sisi siap, alur kerjanya terasa seperti magic: kita jalankan skrip biasa, eksekusi berhenti di breakpoint yang dipasang di IDE, dan seluruh isi variabel pada saat itu tersedia untuk diperiksa.

Kode berikut dapat dijalankan apa adanya tanpa Xdebug — tetapi dengan breakpoint pada baris $total += $nilai;, kita bisa menghentikan eksekusi pada tiap iterasi dan memeriksa $nilai serta $total tanpa satu pun echo diagnostik:

<?php
$total = 0;

foreach ([100, 250, 75] as $nilai) {
    $total += $nilai;
    echo "Iterasi: nilai=$nilai, total=$total\n";
}

echo "Total akhir: $total\n";

Output yang Dihasilkan:

Iterasi: nilai=100, total=100
Iterasi: nilai=250, total=350
Iterasi: nilai=75, total=425
Total akhir: 425

Tanpa debugger, kita terpaksa menambahkan baris echo seperti di atas untuk mengintip perkembangan $total, lalu menghapusnya lagi setelah selesai. Dengan breakpoint, kode produksi tetap bersih: seluruh pengintaian terjadi di sisi IDE.

xdebug_info() sebagai Halaman Diagnostik #

Xdebug menyediakan function khusus untuk memeriksa kondisinya sendiri. Panggilan xdebug_info() merender halaman diagnostik yang memuat versi Xdebug, mode yang aktif, dan tabel seluruh pengaturan beserta nilainya — sangat berguna saat konfigurasi tidak berperilaku seperti dugaan:

<?php
xdebug_info();

Blok di atas tidak bisa dijalankan pada lingkungan buku ini karena ekstensi Xdebug tidak termuat — memanggilnya justru memicu error Call to undefined function. Di mesin Anda yang sudah mengaktifkan mode develop, buka halaman tersebut lewat browser atau CLI dan pastikan baris xdebug.mode menampilkan mode yang Anda harapkan sebelum melanjutkan ke step debugging.

Xdebug di dalam Container #

Tim modern kerap menjalankan aplikasi di Docker atau container lain, dan di sinilah letak kejebakan klasiknya. Xdebug menginisiasi koneksi dari PHP menuju IDE, bukan sebaliknya. Ketika PHP berjalan di dalam container sementara IDE berada di komputer host, alamat 127.0.0.1 justru menunjuk ke container itu sendiri.

Solusinya, arahkan xdebug.client_host ke host dari sudut pandang container:

xdebug.client_host=host.docker.internal

Nama host.docker.internal adalah alias bawaan Docker Desktop yang menunjuk ke komputer host; pada lingkungan Linux, alias tersebut bisa ditambahkan lewat flag --add-host=host.docker.internal:host-gateway. Setelah koneksi berhasil, pengalaman debugging di dalam container sama persis dengan debugging lokal.

Kapan var_dump Masih Cukup #

Semua kecanggihan Xdebug tidak menghapus kegunaan alat sederhana. Untuk memeriksa satu struktur data sekali jalan, var_dump() tetap cara tercepat:

<?php
$pelanggan = [
    "nama" => "Budi",
    "poin" => 120,
    "aktif" => true,
];

var_dump($pelanggan);

Output yang Dihasilkan:

array(3) {
  ["nama"]=>
  string(4) "Budi"
  ["poin"]=>
  int(120)
  ["aktif"]=>
  bool(true)
}

Output di atas adalah tampilan var_dump() polos tanpa Xdebug. Ketika mode develop aktif, Xdebug mengubah keluaran yang sama menjadi berwarna, merapikan indentasi, membatasi kedalaman array, dan menyembunyikan path yang panjang — cukup untuk banyak pemeriksaan harian tanpa memasang breakpoint sama sekali.

Ringkasan #

Xdebug menambahkan kemampuan observasi aktif ke runtime PHP: step debugging, stack trace yang diperkaya, var_dump() yang terbaca, profiling, dan code coverage. Pemasangannya menuntut zend_extension di php.ini, perilakunya dipilih lewat xdebug.mode, dan step debugging bekerja ketika IDE mendengarkan di xdebug.client_port — dengan penyesuaian xdebug.client_host untuk container. Pemeriksaan ketersediaannya sendiri bisa diuji jujur lewat function_exists("xdebug_info"). Kini kita mengerti infrastrukturnya; chapter berikutnya membedah jantung penggunaannya sehari-hari: breakpoint dan watch expressions.

Referensi #

• Instalasi Xdebug
• Step Debugging dengan Xdebug
• Development Helpers (mode develop)
• var_dump — php.net