Як налаштувати Xdebug з PHPStorm

Xdebug це модуль PHP. Його можна встановити собі щоб розширити можливості PHP. Написаний на C так же як і сам PHP.
Репозиторій Xdebug: https://github.com/derickr/xdebug

Принцип роботи Xdebug

1. Користувач робить запит на сайт.
2. Сервер читає запит, бачить що зроблено запит на PHP файл index.php
3. Сервер звертається до PHP інтерпритатора і надсилає йому на опрацювання цей файл index.php.
4. Запускається PHP інтерпритатор, парсить отриманий код і кладе його собі у памʼять.
5. PHP інтерптитатор запускає модуль Xdebug, цей модуль уже буде мати доступ до усього коду котрий потрібно виконати.
6. Xdebug модуль надсилає запит на зʼєднання до IDE, так званого Client по протоколу DBGp.

Детальніше про DBGp: https://xdebug.org/docs/dbgp

Client — у даному випадку це програма котра має можливість редагувати код і включає у себе сервер котрий запущений і слухає 9000 порт. (PhpStorm, VScode, Sublime, повний список клієнтів https://xdebug.org/docs/remote#clients)

7. Client уже був запущений і працює на 9000 порту. Приймає цей запит і надсилає відповідь до PHP інтерпритатора, цю відповідь прийме модуль Xdebug і встановиться зʼяднання DBGp. Через це зʼєднання Client (IDE) і отримає всю інформацію котру про стан виконання скрипта котру згенерував Xdebug.

1. Встановлення модуля Xdebug

Windows:
Розкоментувати в php.ini: zend_extension з xdebug.dll
На windows з великою кількістю можливих локальних серверів вказати точне місце розташування php.ini неможливо. Де цей файл знаходиться у вас можна таким чином:
Вивести на екран phpinfo, подивитись розташування файлу php.ini

phpinfo();

phpinfo()

Linux:

sudo apt install php7.2-xdebug

Перевірити наявність /etc/php/7.2/mods-available/xdebug.ini

1.1 Перевірка вірності встановлення модуля Xdebug.

Виводимо на екран той же самий phpinfo()

Якщо у вас немає вказаного що PHP працює with Xdebug отже встановлення і увімкнення відбулось невірно. Потрібно повертатись назад і перевіряти усі кроки. Продовжувати виконувати наступні кроки немає сенсу тому що Xdebug не увімкнений.

2. Налаштування зʼєднання Xdebug з IDE

З’єднання може працювати у двох варіантах
https://xdebug.org/docs/remote#communication

• встановлювати зʼєднання зі статичним IP адресом
• встановлювати зʼєднання з усіма IP адресами котрі надіслали запит на сервер.

Отже потрібно змінити налаштування модуля xdebug
у windows це буде робитись у php.ini, а у linux у xdebug.ini.

xdebug.remote_handler=dbgp

Протокол по котрому буде працювати Xdebug, іншого протоколу не підтримується тому вирішувати не доведеться. Налаштування уже вставновлене по замовчуванню, вказано для перевірки.

xdebug.remote_enable=1

Параметр вказує що Xdebug буде намагатись встановити зʼєднання з Client (PHPStorm). Якщо зʼєднання встановити не вийде (невірно вказано IP або ж порт, також може бути причина firewall котрий блокує зовнішнє підключення) тоді PHP інтерптитатор продовжить виконання скрипта.

xdebug.remote_autostart=1

Потрібно включити для того щоб Xdebug запускався і встановлював зʼєднання на кожен запит. В іншому випадку потрібно буде використовувати GET параметр XDEBUG_SESSION_START щоб запустити Xdebug. Інколи зручніше вручну запускати Xdebug, тому що запущеним Xdebug використовує більше ресурсів і може привести до сповільнення роботи. Тому тут на власний розсуд.

xdebug.remote_host=127.0.0.1

або ж

xdebug.remote_connect_back=1

Працюють дані параметри наступним чином. В момент коли прийшов запит та Xdebug запустився він перевіряє чи потрібно встановлювати зʼєднання. Можна вказати встановлювати зʼєднання і надсилати інформацію тільки на один IP адрес xdebug.remote_host, а можна вказати просто xdebug.remote_connect_back=1. Тоді Xdebug буде встановлюти зʼєднання у відповідь на усі запити. В принципі локально немає різниці, другий варіант є простішим в налаштуванні. Тому його частіше використовують коли налаштовують Xdebug з Docker і дізнаватись усі IP адреси немає бажання.

xdebug.remote_port=9000

Порт котрий слухає Client (PhpStorm).

2.1 Налаштування коротко

xdebug.remote_handler=dbgp
xdebug.remote_enable=1 
xdebug.remote_autostart=1
xdebug.remote_connect_back=1
xdebug.remote_port=9000

2.2 Перевірка встановлення зʼєднання Xdebug

Щоб перевірити що PhpStorm слухає порібний потрібний порто можна використати таку команду

sudo netstat -tulpn | grep LISTEN
> tcp6 0 0 :::9003  :::*    LISTEN      348800/java

Під час виникнення проблем важливо зрозуміти на чиїй стороні відбулась помилка. На стороні PhpStorm або ж на стороні Xdebug

Для цього можна запустити https://xdebug.org/docs/dbgpClient

sudo chmod +x ./dbgpClient
./dbgpClient -p 9000

Максимально корисну інформацію і розглянуті усі можливі випадки проблем з PHPStorm можна знайти на офіційному сайті JetBrains за даним посиланням.

Troubleshooting common PHP debugging issues

Тут же можу назвати два основні правила це перевірити на вірність налаштування та читати детально логи в Xdebug та PHPStorm. Це дозволить зрозуміти чому відбувається проблема, а якщо і не буде зрозуміло то з логами можна буде зручно запитати допомоги.

Вивести на екран phpinfo(); і перевірити чи дійсно там встановленні необхідні налаштування.

Якщо ж налаштування вірні і проблема залишається тоді потрібно увімкнути логи Xdebug і почитати їх. Тобто потрібно добавити такий параметр

xdebug.remote_log=path_to_log/xdebug.log

Потім знову виконати спробу запустити Xdebug і прочитати логи за вказаним шляхом у файлі. Варто памʼятати що PHP інтерптитатор повинен мати права на створення такого файлу. В іншому випадку файл логів не створиться і буде помилка уже в логах PHP.

Також і сам PHPStorm може писати свої логи котрі під час проблем потрібно включати і перечитати.