Увольнять становится проще, когда начинаешь понимать, что плохим оказался не человек, а работа предложенная этому человеку

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. Это второй, очень важный момент.

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

Настройка PHP сервера

В поле 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):

Настройка PHP CLI интерпретатора

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

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

Настройки PHP Debug

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

Сессия PHP Debug

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

3 комментария на статью:
  • Алексей:

    Все так. Только у меня:
    environment:
    — PHP_ENABLE_XDEBUG=${PHP_ENABLE_XDEBUG}
    — PHP_IDE_CONFIG=serverName=oms

    У вас:
    environment:
    PHP_IDE_CONFIG: «serverName=Docker»

    Разницы в кавыках. У меня PHP_IDE_CONFIG: «serverName=Docker» в кавычках не работает.

    Это на будущее, если кто-то будет биться головой об стену как я — почему не работает.

    • admin:

      Кавычки в YAML опциональны для строковых типов (но как по мне, читабельность лучше).
      Попробуйте у себя настроить переменные окружения, вот так:

      environment:
          PHP_ENABLE_XDEBUG: ${PHP_ENABLE_XDEBUG}
          PHP_IDE_CONFIG: "serverName=oms"
      
      • Алексей:

        Да, действительно, в нотации, как в моем первом посте, внутри контейнера:
        root@b1085e336601:/app/oms# echo $PHP_IDE_CONFIG
        «serverName=oms»

        Если писать в др. нотации, как у вас, то:
        root@b1085e336601:/app/oms# echo $PHP_IDE_CONFIG
        serverName=oms

        Странно все это. Путаница с кавычками. В одной нотации они не нужны, в др. — все ок

Ответить для admin
Обязательные поля помечены *