Как работать с XDebug

Сколько лет уже пишу на PHP, давно пользуюсь XDebug, но все как-то боком проходили вопросы его настройки и принципа работы. Об этом написано много в разных местах, включая мануал. И вот наконец я сам разобрался, как и что..

Сам отладчик (расширение XDebug) является клиентом. Он пытается подключиться к заданному порту. А открытием и прослушиванием этого порта занимается IDE обычно. Т.е. IDE тут - сервер, обслуживающий порт. Это самая важная мысль, которая позволила мне осознать все аспекты работы отладчика и его настройку. Пройдемся по этим моментам.

Настройки соединения

Тут наглядно показано, как работает установка соединения XDebug с "сервером", см. в разделе Communication Set-up.

Рассмотрим те настройки расширения, которые важны для установки соеднинения (файл xdebug.ini):

[xdebug]
xdebug.remote_port=9000
xdebug.remote_host=127.0.0.1  ; Либо одно,
xdebug.remote_connect_back=on ; либо другое

• xdebug.remote_port - порт, куда соединяться для трансляции процесса
• xdebug.remote_host - хост, на котором искать указанный выше порт.
• xdebug.remote_connect_back - в случае, когда нельзя явно указать хост, соединиться на тот адрес, с которого пришел запрос к PHP-препроцессору.

Вот две последние настройки как раз нужны для того, чтобы дебаггер знал, куда ему соединяться для передачи своей отладочной инфы. Если отладка ведется на локальной машине одним разработчиком, тогда можно явно прописать хост - localhost.

Но если дебаггер запущен на удаленном сервере, а мы подключаемся к этом серваку с серым IP, то не получится явно прописать свой адрес, где мы открыли порт и ждем трансляцию. Поэтому включаем xdebug.remote_connect_back, и дебаггер подключится на тот адрес, с которого пришел запрос к веб-серверу и PHP.

Так же включенный remote_connect_back полезен, если нас, как разработчиков, несколько и все мы подключаемся к одному серверу. Т.е. XDebug будет вести трансляцию на вычисленный адрес и 9000-й порт для каждого запроса отдельно.

Идентификация отладочной сессии

В настройках отладчика есть xdebug.idekey=session_name. Я не до конца понял, что тут к чему. Предположительно, IDE слушая порт, будет проверять, что передаваемые данные "подписаны" этим ключом. Если подпись не совпадает с той, что задана в настройках проекта, IDE игнорирует запрос отладочной сессии.

Выбор значения для session_name зависят от переменных окружения ОС, в итоге это может оказаться имя юзера или вообще пусто. Это не секретная информация. Она нужна только серверу, чтобы игнорировать левые входящие данные.

Короче, чтобы сессия была предсказуемо подписана, явно пишем в этом параметре что-нибудь. Я прописываю так: xdebug.idekey=PHPSTORM. В настройках Шторма тот же ключ указываю.

Проброс порта через SSH

Сам рецепт выглядит так

Что у нас тут:

• server.com - некий физический сервер, где крутится веб-сервер, PHP c расширением XDebug и настройкой xdebug.remote_port=127.0.0.1.
• ssh -R - открыть шелл (Secure Shell) с перенаправлением данных из него на наш комп.
• 9000:localhost:9000 первый порт - это на сервере, потом пара ip:port - это уже на локалке.

Подключаемся к серверу с пробросом порта в нашу сторону. Теперь, когда на веб-сервер придет запрос (с включенной отладкой) XDebug начнет трансляцию в 127.0.0.1:9000 на сервере. И весь поток в 9000-й порт будет перенаправляться к нам (ssh -R) на такой же порт - 9000.

А что, если локально тоже есть веб-сервер и XDebug, нацеленный на тот же 9000-й порт? Да ничего! :) XDebug всего лишь клиент. Когда я в IDE включу прослушивание 9000 порта, тогда начну получать трансляцию от любого клиента, будь он локальный или на удаленном сервере через шелл ко мне стучит.

Автозапуск отладки

Приходит запрос бразура, PHP собирает ответ. Если в нем установлено расширение XDebug, то дебаггер попутно анализирует поступивший запрос. Если в настройках отладчика включен автозапуск (xdebug.remote_autostart=on), при любом запросе с вовлечением PHP дебаггер заводится и начинает трансляцию в порт. При этом его не парит, открыт или нет порт, куда он сейчас передает данные.

Прим: если порт закрыт, то при отладке через ssh можно увидеть в консоли появляющиеся ошибки. Это ситуация, когда включили отладку, а IDE не слушает порт.

Ручной запуск отладки

При отключенном автозапуске нужно явно сообщать отладчику о своих желаниях. Делается это несколькими способами, описанными в мануале, в разделе Starting The Debugger. Тут - пересказ в чистом виде :)

Консольная отладка

По заданной переменной окружения отладчик поймет, что ему нужно начинать трансяцию. Свою передачу он "подпишет" ключом, указанным в idekey. О ключе рассказано выше, в разделе Идентификация отладочной сессии.

Отладка запросов браузера

Дебаггер проверяет в запросе наличие особой печеньки или особый GET/POST-параметр (после чего сам создаст нужную печеньку). Параметр - XDEBUG_SESSION_START=session_name, печенька - XDEBUG_SESSION с тем же значением ключа. Для удобства есть расширения под ведущие браузеры, с помощью которых можно создавать нужную печеньку. Я использую Chome и Xdebug helper. Расширения для других бразеров ищите в приведенном выше мануале.

Что же выбрать, ручной или автозапуск

Если автозапуск не включать, проблематично отлаживать консольные вызовы, т.к. нужно доп.параметры передавать, чтобы сервер XDebug включался. А это невсегда возможно, да и вообще - муторно.

С другой стороны, можно бы включить автозапуск. Но в фоне у проекта может много чего работать, не только какие-нибудь воркеры, но даже банальный ajax с запросами по таймеру. И будет это все цепляться, если в IDE прослушивание порта включено.

Короче, я пока не знаю, как лучше.

Ругань Composer на XDebug

В новой версии Composer я такое уже не вижу, но раньше было: "The XDebug extension is loaded, this can slow down Composer a little. Disabling it when using Composer is recommended."

Теперечи зная, как именно работает этот отладчик, я понимаю, на что ругался Composer. Он ведь на PHP написан, и его выполнение при включенном автозапуске дебаггера инициирует отладку с трансляцией в порт. Даже если автозапуск выключен, все равно XDebug будет лезть с проверками в поступающие к PHP запросы.

Собственно я ничего по этому поводу не предпринимаю. Переключать расширение заколебешься. На своем опыте, если IDE порт не слушает, то выполнение приложения не сильно тормозит, включая и запуски Composer.

IDE

На примере PhpStorm.

Итак, IDE - это наш сервер. В нужный нам момент включаем в нем прослушивание 9000 порта. Когда дебаггер начнет трансляцию, он кроме прочего сообщает, какой скрипт сейчас в работе. При этом IDE проецирует (маппит) эту инфу на файлы проекта. Если она не может найти подходящий файл, тогда спросит юзера, куда маппить. Все это настраивается, но не об этом сейчас речь.

Я ловил такие приколы. Открыто несколько проектов, в одном из них включил прослушивание порта и забыл выключить. Работаю в другом проекте, перегружаю страницу и запрос уходит в бесконечность.. Или еще круче, запустил php-скрипт в консоли, и он повис. Дело в том, что IDE с открытым портом поймала соединение от дебаггера, но не знает куда его смаппить. Она у меня спросила, а я окно не вижу. Теперь-то понятно, почему так :)

Ну а в целом настройка IDE как сервера сводится к минимуму. Порт по умолчанию уже прописан, ключ сессии (xdebug.idekey=session_name) указать такой же, как у дебаггера задано. Если все на одной машине - исходники, веб-сервер с отладчиком, - то даже маппить ничего не надо. Включил прослушивание порта и вперед.

Есть некоторые тонкости по настройке удаленной отладки, но они становятся очевидны, когда понимаешь, как именно работает XDebug. И мануал по IDE в помощь.