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

> Xdebug: встановлення на сервері, налаштування step debug в IDE, режим профілювання і чому не можна вмикати його на проді.

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

## Навіщо потрібен Xdebug, якщо є error\_log

Звичайний `error_log` показує, що впало, але не показує, чому значення змінної виявилося не тим, яке очікувалося. Xdebug дозволяє поставити точку зупинки в конкретному рядку, подивитися всі змінні в поточній області видимості і пройти код крок за кроком прямо в IDE. Для розбору вже наявних фаталів без зупинки процесу знадобиться стаття [про розбір логів помилок PHP](https://www.zevshost.net/uk/kb/php-logi-oshibok-razbor/).

Окремий режим — профілювання. Він не зупиняє код, а записує час виконання кожної функції у файл формату 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 на одному сервері](https://www.zevshost.net/uk/kb/php-multi-version-linux/).

## Налаштування режиму 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 — інструмент розробки, а не продової інфраструктури. Тримайтеся такого порядку:

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

---

Джерело: https://www.zevshost.net/uk/kb/php-xdebug-nastroika/