PHP Debugger — пошаговый отладчик для PHP, который можно держать включённым

· 5 мин чтения
php debugging xdebug mcp ai-agents
📂 Исходный код на GitHub

Пошаговый отладчик для PHP на базе Xdebug: только отладка, без профилировщика, покрытия и трассировки. Почти нулевое замедление, когда клиент отладки не подключён, настройки Xdebug принимает как есть, а через DBGP Client отладку может вести AI-агент.

PHP Debugger — пошаговый отладчик для PHP, который можно держать включённым

PHP Debugger — пошаговый отладчик для PHP, в котором оставили только отладку. Профилировщик, сборщик покрытия кода и трассировщик из него убрали. Получился отладчик, который можно держать включённым всегда: пока отладка не нужна, он почти не заметен. Проект собран на основе Xdebug и говорит по протоколу DBGp — тому же, на котором общаются с отладчиком PhpStorm и VS Code. Поэтому работают они с ним без плагинов и адаптеров. Настройки, триггеры и функции Xdebug отладчик принимает как свои, так что в большинстве проектов переезжать почти нечего.

Коротко о главном:

  • почти нулевое замедление, когда отладочный клиент не подключён;
  • поддержка AI-агентов: через DBGP Client агент сам ставит точки останова, шагает по коду и читает переменные;
  • совместимость с Xdebug без правок: старые INI-настройки, конфиги IDE и вспомогательные функции продолжают работать;
  • отладка включена всегда — не нужно помнить про триггер;
  • ставится как отдельное расширение или как интерпретатор PHP с отладчиком внутри.

Полная документация — на сайте php-debugger.dev.

Зачем нужен ещё один отладчик

Xdebug делает много работы: пошаговую отладку, профилирование, покрытие кода тестами, трассировку. Всё это полезно, но большую часть времени разработчику нужен только отладчик. Остальные модули в это время просто висят в памяти и замедляют каждый запуск скрипта. Авторы PHP Debugger убрали лишнее и оставили одну задачу: пошаговая отладка по протоколу DBGp.

Отсюда два следствия. Первое — замедление близко к нулю, когда IDE не подключена. Второе — отладку можно не выключать никогда: сессия стартует на каждом запросе сама. Не нужно помнить про параметр ?XDEBUG_SESSION_START=1 в адресе страницы и не нужно ставить расширение в браузер.

Замедление: цифры

Измерения сделаны в GitHub Actions через Valgrind. Считали машинные инструкции, а не время на конкретной машине — так результат не зависит от железа. Цифры усреднены по всем поддерживаемым версиям PHP. Расширение загружено, IDE не подключена — это состояние, в котором машина находится почти всё время.

Тест Xdebug PHP Debugger
bench.php — синтетический, тяжёлый по вычислениям +661.6% +12.9%
Rector — правило RectorPHP над PHP-файлом +124.5% +3.6%
Symfony — простой запрос на демо-проекте +35.3% +1.3%

Синтетический тест — худший случай: плотные циклы из вызовов функций, замедлению негде спрятаться. Чем ближе нагрузка к настоящему приложению, тем меньшую долю работы отладчик затрагивает.

Установка

Нужен PHP 8.2, 8.3, 8.4, 8.5 или 8.6.

Сначала установщик. macOS и Linux:

curl -fsSL https://github.com/php-debugger/installer/releases/latest/download/install.sh | sh

Windows:

powershell -c "irm https://github.com/php-debugger/installer/releases/latest/download/install.ps1 | iex"

Потом сам отладчик:

php-debugger install

Эта команда ставит самодостаточный интерпретатор PHP с отладчиком внутри и делает его активным php в PATH. Если хочется оставить свой PHP и добавить только расширение, есть вариант php-debugger install --extension-only. В обоих случаях заменённые файлы резервируются, а php-debugger uninstall возвращает всё как было. Полный список флагов — в документации по установке.

Docker

Образы на Docker Hub — замена официальных образов PHP без переделок. Меняется одна строка:

FROM phpdebugger/php:8.4-fpm

Есть все варианты официальных образов: cli, fpm, apache, zts и их Alpine-версии. Поддержаны PHP 8.2–8.6 на amd64 и arm64. Всё, что работает в официальных образах, включая docker-php-ext-install, работает и здесь. Подробнее — в документации по Docker.

Ещё два пути: PIE и готовые бинарники, плюс сборка из исходников. Об этом — страница вариантов установки.

Настройка IDE

Менять, скорее всего, нечего. Отладчик говорит на протоколе, который редактор уже знает, и слушает тот же порт — 9003. Без плагинов, без адаптеров, без новых конфигов: включите прослушивание порта, поставьте точку останова, запустите код.

Меняется привычка, а не настройка. Отладка доступна всегда, поэтому выключателем становится кнопка прослушивания в редакторе, а не конфигурация отладчика. Подробные гиды: поддержка IDE, PhpStorm и VS Code.

Отладка с AI-агентами

DBGP Client даёт AI-агентам настоящий отладчик. Его команда dbgp mcp — это MCP-сервер. Агент сам запускает PHP-код — как скрипт или как веб-запрос, ставит точки останова, шагает по коду и читает стек вызовов, переменные, вывод и предупреждения. Те же данные, которые вы смотрели бы в IDE.

Установка клиента. macOS и Linux:

curl -fsSL https://github.com/php-debugger/dbgp-client/releases/latest/download/install.sh | sh

Windows:

powershell -c "irm https://github.com/php-debugger/dbgp-client/releases/latest/download/install.ps1 | iex"

Подключение к Claude Code:

claude mcp add dbgp -- dbgp mcp

Другие агенты принимают ту же команду dbgp mcp в своих настройках MCP. Дальше агенту можно просто попросить отладить что-нибудь:

Разберись, почему сумма на странице оформления заказа неправильная: отладь запрос к /checkout с точкой останова в CartService::total().

Связка рассчитана друг на друга. PHP Debugger включён всегда, поэтому агенту не нужны триггер и правки конфигов, чтобы начать сессию. А dbgp слушает порт только пока агент отлаживает код, в остальное время PHP работает с почти нулевым замедлением. Работает это и с PHP в контейнере, и с PHP на сервере. Флаг -no-eval оставляет агента в режиме «только чтение» — он видит всё, но не может выполнять код. Опции клиента и отдельный консольный отладчик для ручной работы в терминале описаны в README DBGP Client.

Совместимость с Xdebug

Возможность PHP Debugger Xdebug
Пошаговая отладка (DBGp) да да
INI-настройки xdebug.* да да
xdebug_break() да да
Триггер XDEBUG_SESSION да да
Покрытие кода нет, используйте pcov да
Профилирование убрано да
Трассировка убрано да

pcov — это отдельное лёгкое расширение, которое делает только покрытие кода. Если оно нужно, его ставят рядом, а не вместо отладчика.

Лицензия

Проект выпущен под The Xdebug License версии 1.03 на основе The PHP License. PHP Debugger построен на фундаменте Xdebug, который Дерик Ретанс создаёт и поддерживает с 2002 года — без его двадцати с лишним лет работы над инструментами отладки PHP этого проекта не было бы.

Источник: https://github.com/php-debugger/php-debugger