Xdebug — розширення PHP для покрокового налагодження і профілювання коду. Воно перехоплює виконання скрипта, показує стек викликів при помилці і вміє вимірювати час кожної функції. На проді Xdebug вмикати не можна: він сповільнює виконання в рази і відкриває зайвий вектор атаки, тому ставте його лише на staging або в контейнер розробника.

Навіщо потрібен Xdebug, якщо є error_log

Звичайний error_log показує, що впало, але не показує, чому значення змінної виявилося не тим, яке очікувалося. Xdebug дозволяє поставити точку зупинки в конкретному рядку, подивитися всі змінні в поточній області видимості і пройти код крок за кроком прямо в IDE. Для розбору вже наявних фаталів без зупинки процесу знадобиться стаття про розбір логів помилок PHP.

Окремий режим — профілювання. Він не зупиняє код, а записує час виконання кожної функції у файл формату cachegrind, який потім відкривають у KCachegrind або Webgrind, щоб знайти найповільніше місце в запиті.

Встановлення на сервері з Ubuntu і Debian

Xdebug ставиться як звичайне PECL-розширення поверх уже встановленого PHP. Версія розширення має відповідати версії PHP-FPM:

sudo apt install php8.3-dev php-pear
sudo pecl install xdebug
echo "zend_extension=xdebug.so" | sudo tee /etc/php/8.3/mods-available/xdebug.ini
sudo phpenmod xdebug
sudo systemctl restart php8.3-fpm

Якщо на сервері кілька версій PHP одночасно, ставити Xdebug варто для кожної окремо — подробиці у статті про кілька версій PHP на одному сервері.

Налаштування режиму step debug

Із версії Xdebug 3 конфігурація стала явною: режим роботи задається однією директивою замість десятка прапорців.

Параметр	Значення	Призначення
xdebug.mode	debug	вмикає покрокове налагодження
xdebug.client_host	ip IDE	куди надсилати сигнал налагодження
xdebug.client_port	9003	порт, який слухає IDE
xdebug.start_with_request	trigger	налагодження за прапорцем у запиті

Значення trigger в останньому параметрі важливе: без нього Xdebug намагається під'єднатися до IDE на кожному запиті і помітно гальмує навіть staging.

Типові проблеми підключення

Налагоджувач не підключається до IDE майже завжди з однієї з цих причин:

Файрвол на сервері блокує вихідний трафік на порт 9003 — додайте дозвільне правило для staging-оточення.
IDE слухає не той порт: у PhpStorm за замовчуванням 9003, але за старою інструкцією може бути вказано 9000, що конфліктує з FastCGI.
Шлях на сервері і шлях в IDE не збігаються через path mapping — тоді точки зупинки просто не спрацьовують.
У php.ini одночасно завантажені Xdebug і OPcache з JIT — їхнє поєднання знижує вигоду від обох і плутає профілювання.

Профілювання повільного запиту

Щоб знайти вузьке місце в конкретному обробнику, увімкніть режим profile точково, через параметр в URL, не чіпаючи загальний конфіг:

xdebug.mode=profile
xdebug.start_with_request=trigger
xdebug.output_dir=/var/log/xdebug
# запит виду:
# https://staging.example.com/checkout?XDEBUG_PROFILE=1

Файл cachegrind.out.* покаже дерево викликів із часом кожної функції. Часто виявляється, що гальмує не PHP, а зайвий запит до бази всередині циклу — це видно одразу за кількістю повторів однієї й тієї ж функції.

Чек-лист безпечного використання

Xdebug — інструмент розробки, а не продової інфраструктури. Тримайтеся такого порядку:

Ставте Xdebug лише на staging або локально, на проді — режим xdebug.mode=off або розширення взагалі не підключене.
Використовуйте start_with_request=trigger, щоб налагодження не вмикалося на кожен випадковий запит.
Після профілювання видаляйте старі cachegrind-файли: за день їх може накопичитися кілька гігабайт.

Xdebug на сервері: налагодження і профілювання PHP-коду