Коротко: Xdebug — пошаговый отладчик PHP вместо var_dump: breakpoint, просмотр переменных и стека; настраивается за 10 минут, в т.ч. в Docker.

Если вы всё ещё отлаживаете PHP через var_dump(); die(); — Xdebug сэкономит вам часы. Это пошаговый отладчик: ставите breakpoint, останавливаете выполнение в нужной точке и смотрите все переменные, стек вызовов и выполняете код построчно. Ниже — как настроить за 10 минут (в т.ч. в Docker) и пользоваться.

Установка и базовый php.ini

pecl install xdebug         # или apt install php-xdebug
# Docker (alpine): apk add ... && pecl install xdebug && docker-php-ext-enable xdebug

Конфиг (Xdebug 3 — синтаксис изменился относительно v2):

zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=trigger   ; включать отладку только по триггеру
xdebug.client_host=127.0.0.1        ; в Docker — IP хоста
xdebug.client_port=9003             ; порт по умолчанию в Xdebug 3 (был 9000)
xdebug.log=/tmp/xdebug.log          ; пригодится для диагностики

start_with_request=trigger важен для производительности: Xdebug не тормозит каждый запрос, а включается только когда вы явно дебажите.

Xdebug в Docker — главный нюанс

Контейнер должен достучаться до IDE на хосте. Ключевое — правильный client_host:

  • macOS/Windows: xdebug.client_host=host.docker.internal.
  • Linux: пробросить host.docker.internal через extra_hosts: ["host.docker.internal:host-gateway"] в compose, либо указать IP docker-моста.
  • Проверка: если не цепляется — смотрите /tmp/xdebug.log, там видно попытки соединения.

Настройка в PhpStorm

  1. Settings → PHP → Debug: порт 9003.
  2. Включите «Start Listening for PHP Debug Connections» (иконка телефона-жучка в тулбаре).
  3. Для Docker задайте «Server» с маппингом путей: путь проекта на хосте ↔ путь в контейнере (/app). Без маппинга breakpoint'ы не сработают.
  4. Поставьте breakpoint (клик по полю слева от строки) и инициируйте запрос.

Как инициировать отладку (триггер)

  • Браузер: расширение «Xdebug helper» — кнопка Debug ставит cookie XDEBUG_TRIGGER.
  • CLI: XDEBUG_TRIGGER=1 php script.php или php -d xdebug.start_with_request=yes script.php.
  • HTTP вручную: добавить ?XDEBUG_TRIGGER=1 к URL.

Что доступно на breakpoint'е

  • Variables — все переменные в текущей области, включая объекты и массивы целиком.
  • Step Over (F8) — следующая строка, Step Into (F7) — зайти внутрь вызова, Step Out (Shift+F8) — выйти из метода.
  • Call stack — как мы сюда попали.
  • Evaluate Expression — выполнить любой код в текущем контексте (проверить гипотезу, не меняя файл).
  • Conditional breakpoint — остановиться, только если условие истинно (правый клик по breakpoint): незаменимо в циклах.

Не только отладка

  • Профилирование: xdebug.mode=profile → cachegrind-файлы, открываются в KCachegrind/PhpStorm — видно, где тратится время.
  • Покрытие тестами: xdebug.mode=coverage для phpunit --coverage.
  • Режимы комбинируются: xdebug.mode=debug,coverage.

Почему это стоит освоить

Пошаговая отладка показывает реальное состояние программы в моменте — без догадок и расставленных по коду дампов, которые потом забываешь убрать. Один раз настроив Xdebug (особенно в Docker), вы перестаёте терять время на «слепую» отладку.

Если в команде до сих пор отлаживают дампами и не настроен нормальный debug-флоу — помогу наладить на консультации.