PHP Debugger — пошаговый отладчик для PHP, который можно держать включённым
📂 Исходный код на GitHubПошаговый отладчик для PHP на базе Xdebug: только отладка, без профилировщика, покрытия и трассировки. Почти нулевое замедление, когда клиент отладки не подключён, настройки Xdebug принимает как есть, а через DBGP Client отладку может вести AI-агент.
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 этого проекта не было бы.