PHP: Настраиваем отладку. PhpStorm + PHP 8 + Docker + Xdebug 3

В очередной раз споткнувшись о собственную забывчивость, решил накидать небольшую заметку о том, как настроить отладку PHP в докере через xdebug для IDE PhpStorm. Кто-то правильно скажет, что в сети полно статей на данную тему, однако, все они не смогли спасти меня от совершения пары ошибок на которые я уже наступал ранее.

Итак, имеем следующую конфигурацию: на нашем Linux хосте есть IDE PhpStorm 2020.3, докер образ PHP версии 8.0.0, настраиваемый в контейнере через docker-compose и установленное в том-же образе расширение для отладки xdebug версии 3.0.1. Мы хотим заниматься отладкой в любимой IDE отлавливая вызовы как через веб-браузер, так и через контейнер, к примеру перехватывая из него запуски каких-либо CLI скриптов.

Первым делом читаем вот эту заметочку о том, как нам заставить работать отладку для скриптов запускаемых на удаленной стороне. Осмыслив суть, добавляем в настройку нашего контейнера с образом PHP (у меня настройки в docker-compose.yml) следующую строчку с переменной окружения PHP_IDE_CONFIG:

    ...
    environment:
        PHP_IDE_CONFIG: "serverName=Docker"
    ...

Здесь важно запомнить первый момент, что далее, при настройке PhpStorm, мы должны в точности повторить имя удаленного сервера для связки (маппинга) наших локальных исходников с исходниками на сервере. В нашем случае это имя задано как Docker. Это важный момент, не промахнитесь с регистром.

Далее, через php.ini, настраиваем xdebug, используя укороченный синтаксис от третьей версии. У меня настройки выглядят вот так:

[xdebug]
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.client_host=172.17.0.1
xdebug.start_with_request=yes

Здесь скрыт второй важный момент, который заключается в том, что необходимо правильно указать параметр xdebug.client_host, который сообщает нашему расширению xdebug на каком адресе нас ждет слушатель для передачи отладочных данных. В моем случае, так как в контейнере я использую networking по умолчанию (т.е. у меня попросту нет настраиваемой секции networks) это будет host.docker.internal, который для Linux по умолчанию поднимается на интерфейсе 172.17.0.1. Это второй, очень важный момент. (Для систем на базе Windows и macOS xdebug.client_host должен быть установлен на host.docker.internal).

Дальше, проще. Проходимся по стандартному пути настройки PhpStorm. Первым делом настраиваем PHP сервер, с которым мы будем общаться, вспоминая, что он находится на удаленной среде и для нашей IDE мы назвали его Docker. Таким образом, заходим в настройки PhpStorm (Ctrl+Alt+S) и по пути Languages & Frameworks > PHP > Servers добавляем вот такую конфигурацию:

В поле Name вводим настроенное ранее через PHP_IDE_CONFIG имя нашего сервера, т.е. Docker (см. п. 1). Поле Host содержит имя хоста, у меня оно не заполнено и поэтому используется символ подчеркивания (см. п. 2). Пункт 3 является важной составляющей связки локальных файлов с файлами сервера. Я связал свои локальные файлы, расположенные в /home/___/projects/www/___/www с файлами в контейнере, расположенными по пути /var/www/html.

Следующим шагом мы должны настроить PHP CLI интерпретатор, через который мы собственно и запускаем наши скрипты. Естественно он расположен в нашем PHP контейнере и в общем случае вся настройка, по пути Languages & Frameworks > PHP > CLI Interpreters будет выглядеть вот так (выбираем создание From Docker, ... Docker compose):

Здесь мы даем произвольное осмысленное имя нашему интерпретатору (см. п. 1). В п.2 выбираем наш созданный ранее сервер Docker. Далее, в п.3 выбираем расположение конфигурационного файла docker-compose.yml и п.4 уточняем используемый сервис с PHP (у меня в docker-compose.yml он называется php). Если контейнер запущен и мы правильно всё выбрали, то в разделе General должна появиться информация о рабочем PHP окружении (см. п. 5).

На всякий случай проверяем настройки в Languages & Frameworks > PHP > Debug. Здесь важно, что мы будем слушать приходящие в IDE запросы на порту 9003 (это теперь порт по умолчанию в xdebug 3).

Всё, мы готовы к работе. Нажимаем заветную кнопочку Start Listening for PHP Debug Connections. Ставим точку останова в нужном месте PHP скрипта и дергаем его из браузера или прямо из докера. Вуаля, получаем, желаемое:

Понимаю, что многие, понятные для меня моменты я мог упустить, но общий минимальный порядок действий для запуска отладки я изложил полностью, если есть вопросы и предложения, милости просим в комментарии. Удачной отладки!

Дополнение: так как параметры Xdebug могут быть переопределены через переменные окружения, важно помнить об этом моменте и проверять итоговую конфигурацию отладчика. К примеру, ваш xdebug.client_host указанный в php.ini может быть заменён через переменную окружения XDEBUG_CONFIG="client_host=host.docker.internal" и вы получите неправильно настроенного слушателя для Linux систем.