Cara Mengaktifkan dan Mengkonfigurasi Modul Xdebug di ServBay

ServBay sebagai persekitaran pembangunan web tempatan yang berkuasa tinggi, telah siap sedia dengan alat debugging dan analisis Xdebug untuk para pembangun PHP. Mengaktifkan Xdebug dapat meningkatkan kecekapan pembangunan aplikasi PHP anda dengan ketara, melancarkan proses debug kod, analisis prestasi, serta pengesanan liputan kod. Artikel ini akan menerangkan secara terperinci cara mengaktifkan dan mengkonfigurasi Xdebug dalam ServBay, serta panduan integrasi dengan persekitaran pembangunan bersepadu (IDE) popular.

Pengenalan Modul Xdebug

Xdebug ialah ekstensi PHP yang kaya dengan ciri, direka khas untuk debugging dan analisis kod PHP. ServBay telah sedia mengintegrasikan Xdebug, menghapuskan keperluan konfigurasi manual yang rumit, menjadikan pengaktifan dan konfigurasi sangat mudah.

Fungsi Utama Xdebug

• Debug Breakpoint: Membolehkan anda menetapkan breakpoint pada baris tertentu dalam kod. Sebaik sahaja eksekusi kod mencapai breakpoint, ia akan berhenti dan anda dapat memeriksa status pembolehubah, call stack, serta menjejak kod baris demi baris.
• Step Debug: Menyokong eksekusi kod secara satu persatu (Step Over), masuk ke dalam fungsi (Step Into), dan keluar dari fungsi (Step Out), memudahkan jejak aliran eksekusi program.
• Pemantauan Pembolehubah: Melihat nilai pembolehubah tempatan dan global secara masa nyata ketika debugging.
• Stack Trace: Ketika berlaku ralat atau pengecualian, Xdebug menyediakan maklumat stack panggilan perincian yang memudahkan anda mengenalpasti sumber masalah dengan cepat.
• Profiling Prestasi: Menjana laporan prestasi eksekusi kod untuk membantu mengesan leher botol (bottleneck).
• Pengesanan Liputan Kod (Code Coverage): Mengukur sejauh mana kod diuji semasa menjalankan ujian, untuk menilai keberkesanan testing.

Versi Xdebug Terbina & Pemetaan Port dalam ServBay

ServBay telah siap memasang Xdebug untuk setiap versi PHP yang disokong. Penting untuk diingat bahawa setiap versi PHP menggunakan port Xdebug tersendiri yang berkaitan dengan nombor versinya; penentuan port ini sangat penting semasa konfigurasi dalam IDE.

Versi PHP	Xdebug Pramasang	Port Xdebug Lalai
PHP 5.6	Xdebug 2.5.5	39056
PHP 7.0	Xdebug 2.5.5	39070
PHP 7.1	Xdebug 2.5.5	39071
PHP 7.2	Xdebug 3.1.6	39072
PHP 7.3	Xdebug 3.1.6	39073
PHP 7.4	Xdebug 3.1.6	39074
PHP 8.0	Xdebug 3.3.1	39080
PHP 8.1	Xdebug 3.4.0	39081
PHP 8.2	Xdebug 3.4.0	39082
PHP 8.3	Xdebug 3.4.0	39083
PHP 8.4	Xdebug 3.4.0	39084
PHP 8.5	Xdebug 3.4.0	39085

Peraturan Port

Peraturan port lalai Xdebug adalah 39000 + nombor subversi PHP. Sebagai contoh, port bagi PHP 8.3 ialah 39000 + 83 = 39083, manakala PHP 7.4 ialah 39000 + 74 = 39074. Memahami peraturan ini akan membantu anda mengenal pasti port bagi setiap versi PHP dengan pantas.

Cara Mengaktifkan Modul Xdebug

Mengaktifkan modul Xdebug dalam ServBay amat mudah, disarankan untuk menggunakan antara muka grafik pengguna (GUI) ServBay. Anda juga boleh melakukannya secara manual melalui fail konfigurasi.

Mengaktifkan Xdebug melalui GUI ServBay

Ini adalah cara yang paling cepat dan mudah.

1. Buka aplikasi ServBay.
2. Pada bar navigasi sebelah kiri, pilih Bahasa (Languages).
3. Kembangkan seksyen PHP dan cari versi PHP yang anda ingin aktifkan Xdebug, contohnya PHP 8.3.
4. Klik butang Ekstensi di bahagian kanan versi tersebut.
5. Dalam senarai ekstensi yang muncul, cari modul Xdebug.
6. Klik suis di sebelah kiri modul Xdebug untuk mengaktifkannya.
7. Laraskan parameter jika perlu.
8. Klik butang Simpan di bahagian bawah antara muka.
9. ServBay akan secara automatik memulakan semula proses PHP dan memuatkan modul Xdebug.

Ilustrasi: Mengaktifkan Xdebug dalam seksyen Ekstensi

Mengesahkan Modul Xdebug Berjaya Dimuatkan

Cara paling tepat adalah dengan menggunakan fungsi phpinfo() untuk memeriksa maklumat konfigurasi PHP.

1. Di direktori root laman ServBay anda (default /Applications/ServBay/www), buat satu fail PHP mudah, contohnya phpinfo.php.
2. Tambahkan kandungan berikut ke dalam fail phpinfo.php:

```php
<?php
// Papar maklumat konfigurasi PHP
phpinfo();
?>
```

3. Akses fail tersebut melalui pelayar, contohnya https://servbay.demo/phpinfo.php (gantikan servbay.demo dengan domain laman web anda yang dikonfigurasi dalam ServBay).
4. Cari "Xdebug" pada halaman output phpinfo. Jika Xdebug telah berjaya dimuatkan, anda akan melihat seksyen konfigurasi "Xdebug" yang memaparkan maklumat versi serta parameter konfigurasinya.

Ilustrasi: Melihat maklumat Xdebug dalam output phpinfo

Mengkonfigurasi Xdebug untuk Debug dalam IDE

Aktifkan Xdebug hanyalah langkah pertama. Untuk debug menggunakan breakpoint, anda perlu mengkonfigurasi interpreter PHP, debugger, dan pemetaan server dalam IDE. Berikut adalah panduan untuk PHPStorm dan Visual Studio Code (VS Code).

Mengkonfigurasi Xdebug dalam PHPStorm

PHPStorm menawarkan sokongan penuh untuk Xdebug.

1. Buka tetapan PHPStorm: Mulakan PHPStorm dan buka tetapan melalui menu File -> Settings (Windows/Linux) atau PHPStorm -> Preferences (macOS).

2. Konfigurasi Interpreter PHP CLI:

   • Navigasi ke Languages & Frameworks -> PHP.
   • Dalam seksyen CLI Interpreter, klik butang ... di sebelah kanan.
   • Di tetingkap yang muncul, klik ikon + untuk menambah interpreter baharu.
   • Pilih laluan executable PHP yang sepadan dari pemasangan ServBay anda, misalnya /Applications/ServBay/package/php/8.3/8.3.7/bin/php (pastikan nombor versi tepat mengikut pemasangan ServBay anda).
   • PHPStorm akan secara automatik mengesan versi interpreter serta maklumat ekstensi termasuk Xdebug.
   • Klik OK untuk simpan konfigurasi interpreter. Ilustrasi: Menambah interpreter PHP ServBay dalam PHPStorm

3. Konfigurasi Parameter Debug Xdebug:

   • Navigasi ke Languages & Frameworks -> PHP -> Debug.
   • Pada seksyen Xdebug, tetapkan Debug Port mengikut port Xdebug untuk versi PHP aktif dalam ServBay (contohnya 39083 untuk PHP 8.3). Pastikan port ini sama dengan konfigurasi xdebug.client_port.
   • Tandakan pilihan Can accept external connections.
   • Klik Apply diikuti OK untuk menyimpan. Ilustrasi: Menetapkan port Xdebug dalam PHPStorm

4. Konfigurasi Pemetaan Server PHP:

   • Navigasi ke Languages & Frameworks -> PHP -> Servers.
   • Klik ikon + di sebelah kanan untuk menambah server baharu.
   • Isikan nama server (cth. ServBay Localhost).
   • Tetapkan Host dengan domain laman web yang anda gunakan dalam ServBay (cth. servbay.demo).
   • Tetapkan Port mengikut port laman web anda, biasanya 443 (HTTPS) atau 80 (HTTP).
   • Pilih Debugger sebagai Xdebug.
   • Tandakan Use path mappings.
   • Tetapkan pemetaan folder projek tempatan (Absolute path to local source) dengan laluan yang sepadan di server (Absolute path on the server). Misalnya, projek anda dalam /Applications/ServBay/www/myproject yang diakses melalui https://servbay.demo/ perlu dipetakan ke root (/). Jika menggunakan subdomain seperti https://myproject.servbay.demo/, projek root juga dipeta ke /. Tetapan path mapping yang betul amat penting untuk keberhasilan debugging Xdebug.
   • Klik OK untuk simpan tetapan. Ilustrasi: Tetapan server dan path mapping dalam PHPStorm

5. Mulakan Sesi Debug:

   • Buka fail PHP projek anda dalam PHPStorm.
   • Klik di bahagian kiri nombor baris untuk menetapkan breakpoint (bulatan merah).
   • Klik butang Start Listening for PHP Debug Connections (ikon pepijat) di bar alat PHPStorm. Ikon akan bertukar warna hijau menandakan PHPStorm kini mendengar sambungan Xdebug.
   • Layari aplikasi PHP anda di pelayar (contohnya https://servbay.demo/index.php).
   • Jika semua konfigurasi betul, Xdebug akan menyambung ke PHPStorm dan execution akan berhenti pada breakpoint yang anda tetapkan; kini anda boleh debug dalam PHPStorm. Ilustrasi: Mula mendengar sambungan Xdebug dalam PHPStorm

Mengkonfigurasi Xdebug dalam Visual Studio Code (VS Code)

VS Code juga popular untuk pembangunan PHP dan menyokong Xdebug melalui pemasangan ekstensi.

1. Pasang Ekstensi PHP Debug:

   • Buka VS Code.
   • Pergi ke paparan ekstensi (Ctrl+Shift+X atau Cmd+Shift+X).
   • Cari "PHP Debug" dan pasangkan ekstensi oleh Felix Becker.

2. Konfigurasi launch.json:

   • Buka folder projek PHP anda.
   • Pilih paparan Run & Debug (Ctrl+Shift+D atau Cmd+Shift+D).
   • Klik ikon gear di toolbar atas, pilih "PHP". VS Code akan menjana fail launch.json dalam folder .vscode di akar projek anda.
   • Edit launch.json dan pastikan konfigurasi "Listen for Xdebug" menggunakan port yang sepadan dengan port Xdebug untuk versi PHP diaktifkan dalam ServBay (cth. 39083 untuk PHP 8.3).
   • Konfigurasi Path Mapping: Ini sangat penting. Dalam launch.json cari atau tambah entri pathMappings untuk memetakan struktur folder projek anda di ServBay ke struktur pada sistem fail tempatan anda.

     {
         "version": "0.2.0",
         "configurations": [
             {
                 "name": "Listen for Xdebug",
                 "type": "php",
                 "request": "launch",
                 "port": 39083, // Ubah port mengikut versi PHP anda
                 "pathMappings": {
                     // Petakan folder projek root ServBay ke root tempatan
                     "/": "${workspaceRoot}"
                     // Jika anda menggunakan subdomain, root server juga tetap "/"
                     // "/": "${workspaceRoot}"
                 }
             },
             {
                 "name": "Launch currently open script",
                 "type": "php",
                 "request": "launch",
                 "program": "${file}",
                 "cwd": "${fileDirname}",
                 "port": 39083 // Ubah port mengikut versi PHP anda
             }
         ]
     }

     Sesuaikan pathMappings mengikut struktur projek dan tetapan domain ServBay anda. ${workspaceRoot} biasanya merujuk kepada akar folder projek yang dibuka dalam VS Code.

3. Mulakan Sesi Debug:

   • Buka fail kod PHP projek anda dalam VS Code.
   • Klik di tepi nombor baris untuk tambahkan breakpoint (bulatan merah).
   • Pergi ke paparan Run & Debug (Ctrl+Shift+D atau Cmd+Shift+D).
   • Pilih konfigurasi "Listen for Xdebug" dalam menu dropdown debugging.
   • Klik butang hijau "Start Debugging". Bar status VS Code akan berubah menjadi jingga menandakan ia sedang mendengar sambungan Xdebug.
   • Layari aplikasi PHP anda di pelayar. Jika konfigurasi betul, Xdebug akan menyambung dan VS Code akan berhenti di breakpoint.

Soalan Lazim (FAQ)

• S: Modul Xdebug tidak muncul dalam phpinfo()?

  • J: Pastikan anda telah mengaktifkan Xdebug melalui GUI ServBay atau edit manual xdebug.ini.
  • Sahkan anda telah memulakan semula servis PHP berkaitan.
  • Semak jalan fail xdebug.ini betul, dan baris zend_extension = xdebug.so tidak diulas.
  • Semak log ServBay (/Applications/ServBay/logs/php/<version>/error.log) untuk melihat jika ada ralat ketika memuatkan Xdebug.

• S: Sudah letak breakpoint dalam IDE, tapi kod tidak berhenti?

  • J: Pastikan IDE anda sedang mendengar sambungan Xdebug (ikon pepijat hijau di PHPStorm, bar status jingga di VS Code).
  • Semak port Xdebug dalam konfigurasi IDE sama seperti port xdebug.client_port dan port lalai untuk versi PHP berkenaan.
  • Semak path mapping dalam IDE sudah betul, supaya laluan fail server boleh dipadankan dengan fail projek tempatan anda – ini punca kesilapan paling biasa.
  • Semak tetapan firewall agar IDE boleh mendengar port Xdebug (biasanya julat 390xx).
  • Jika anda guna xdebug.start_with_request=trigger dalam xdebug.ini, pastikan anda memberi trigger dalam browser (cth. gunakan ekstensi Xdebug helper atau tambah ?XDEBUG_TRIGGER=1 pada URL).

• S: Sambungan Xdebug terputus selepas beberapa ketika?

  • J: Semak parameter xdebug.remote_autostart atau xdebug.start_with_request dalam xdebug.ini. Jika dipasang sebagai yes, debug akan bermula setiap kali request – disarankan gunakan mod trigger.
  • Semak tetapan timeout dalam IDE anda.

Kesimpulan

Dengan integrasi sedia ada dan proses konfigurasi yang mudah, ServBay banyak memudahkan pembangun PHP untuk mengaktifkan dan menggunakan Xdebug. Sama ada melalui antara muka GUI yang mesra pengguna atau pengeditan fail konfigurasi secara manual, anda boleh mengaktifkan Xdebug untuk setiap versi PHP dalam ServBay dengan pantas. Digabungkan dengan ciri debug canggih daripada IDE seperti PHPStorm dan VS Code, anda boleh menjejak bug, menambah baik prestasi serta meningkatkan kualiti kod PHP dengan jauh lebih efisien. Kuasai penggunaan bersama ServBay dan Xdebug – ia pasti menjadi aset berharga dalam aliran kerja pembangunan PHP tempatan anda.