PHP, Docker & Xdebug: с чем едят и как пользоваться

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

Что понадобится?

Чтобы следовать этому руководству, убедитесь, что у вас установлен Docker для вашей операционной системы, в идеале последняя версия, и один из поддерживаемых Xdebug клиентов. Вы можете найти все инструкции, необходимые для установки Docker — независимо от того, используете ли вы Linux, macOS или Windows — в документации по Docker.

Базовая конфигурация Docker Compose

Для простоты предположим, что ваша конфигурация Docker Compose, хранящаяся в файле docker-compose.yml в корне каталога проекта, выглядит так, как показано в примере ниже.

docker-compose.yml

Исходный код приложения, независимо от того, использует ли оно такие фреймворки, как Laravel или Symfony, находится в корневом каталоге проекта на машине разработки и будет доступен для контейнера в /var/www/html. 

Установка Xdebug 3 в контейнер PHP

Контейнер php использует пользовательский файл Dockerfile (./docker/php/Dockerfile) для определения шагов сборки, которые вы можете увидеть в примере ниже. Это связано с тем, что Xdebug не поставляется «в комплекте» с официальными контейнерами PHP Docker Hub. 

./docker/php/Dockerfile

Однако для его установки и включения требуется всего два дополнительных шага, как вы можете видеть выше. Это:

• Установка с помощью Pecl
• Включение его с помощью docker-php-ext-enable. Эта команда избавляет нас от необходимости писать собственный сценарий оболочки.

Настройка Xdebug для пошаговой отладки

Когда Xdebug установлен и включен, нам нужно включить пошаговую отладку. Для этого создайте файл конфигурации: docker/php/conf.d/xdebug.ini; и пути, если у вас еще не настроена структура каталогов.

Чтобы сэкономить время, вы можете использовать следующие команды.

В docker/php/conf.d/xdebug.ini добавьте следующую конфигурацию для настройки Xdebug.

Объяснение файла xdebug.ini:

• mode — этот параметр определяет, какие функции Xdebug включены. Мы установили develop для включения вспомогательных средств разработки, таких как получение улучшенных сообщений об ошибках, и debug для включения пошаговой отладки.
• client_host — этот параметр сообщает Xdebug IP-адрес или имя хоста компьютера, на котором работает ваш текстовый редактор или IDE.
• client_port — этот параметр сообщает порт, к которому Xdebug пытается подключиться на удаленном хосте
• idekey — этот параметр указывает какой ключ IDE Xdebug должен передать клиенту отладки или прокси-серверу, мы установили “VSCODE”, но это может быть любой кастомный ключ, который впоследствии будет указан в расширении браузера
• start_with_request — этот параметр определяет, активируются ли трассировка функции, статистика сборки мусора, профилирование или пошаговая отладка в начале запроса PHP. Установка его в yes указывает Xdebug всегда инициировать сеанс отладки.

Затем в определении сервиса php в docker-compose.yml добавьте следующую запись в элемент volumes.

А также создайте новый элемент extra_hosts на том же уровне что и volumes:

Создав ini-файл и обновив docker-compose.yml, чтобы использовать его в php-контейнере, перезапустите и пересоберите его, выполнив следующую команду.

Флаг —build создает образы перед запуском контейнеров. Очень важно использовать этот флаг, потому что без него изменения, которые мы сделали в docker/php/Dockerfile, не вступят в силу.

Настройка Xdebug в текстовом редакторе или IDE

Теперь, когда мы закончили настройку контейнера PHP, нам нужно настроить наш клиент. Это зависит от клиента, который вы используете. Для целей этой статьи я опишу настройку в VSCode и PhpStorm.

Visual Studio Code

Как вы, возможно, уже знаете, Visual Studio Code или сокращенно VSCode — это редактор исходного кода, созданный Microsoft для Windows, Linux и macOS. Функции включают поддержку отладки, подсветку синтаксиса, интеллектуальное завершение кода, фрагменты кода, рефакторинг кода и встроенный Git.

С учетом сказанного вам может быть интересно… что нам нужно, чтобы VSCode со всеми аспектами IDE с полнофункциональной отладкой?

Для начала нам потребуется установить плагин PHP Debug:

После этого необходимо сгенерировать файл с именем launch.json, этот файл используется отладчиком на любом языке, что означает, что часть этого процесса может быть повторно использована при настройке отладчика в VSCode для других языков.

Вы можете сгенерировать файл, щелкнув Run and Debug > create a launch.json file > Docker: Debug in Container, как показано на следующем снимке экрана:

Наконец, файл launch.json будет создан с указанием версии и пустым массивом конфигураций, как показано на следующем снимке экрана:

Теперь, чтобы правильно настроить файл launch.json, вам нужно добавить в массив configurations объект со свойствами name, type, request, port и pathMappings, результат будет выглядеть следующим образом:

Объяснение файла launch.json

• name — указывает имя, присвоенное объекту конфигурации.
• type — указывает на использование базового отладчика.
• request — указывает, предназначена ли конфигурация для запуска программы или для подключения к уже работающему экземпляру.
• port — указывает порт, на котором следует прослушивать Xdebug (точно такой же, который был указан в конфигурации xdebug.ini в предыдущем шаге).
• pathMappings — указывает сопоставление путей сервера с локальными путями. При использовании /var/www/html/ в качестве ключа VSCode знает, что файлы в контейнере находятся по этому пути, а при использовании ${workspaceFolder} в качестве значения VSCode знает, что локально файлы проекта находятся в текущем открытом каталоге.

Я рекомендую вам оставить этот файл launch.json с его содержимым в проекте, чтобы другие члены команды могли просто клонировать проект, запускать контейнеры и пользоваться полнофункциональным решением для отладки, работающим в среде контейнера.

После этого во вкладке Run and Debug можем запустить прослушивание нашим сконфигурированным отладчиком.

PhpStorm

Как вы, возможно, уже знаете, PhpStorm — это проприетарная кроссплатформенная среда разработки для PHP, созданная чешской компанией JetBrains. PhpStorm предоставляет редактор для PHP, HTML и JavaScript с анализом кода «на лету», предотвращением ошибок и автоматическим рефакторингом кода PHP и JavaScript.

Для начала нам нужно проверить, может ли IDE правильно подключиться к Docker:

После этого нам нужно настроить PHP-сервер. Это можно сделать, выбрав File > Settings > PHP > Servers, затем щелкните знак «плюс», как показано на следующем снимке экрана:

После того, как вы нажмете на знак плюса, откроется форма, в которой необходимо заполнить Имя, Хост, Порт и Абсолютный путь к серверу:

Обратите внимание, что порт соответствует порту из нашего предварительно созданного файла docker-compose.yml, а абсолютный путь на сервере соответствует рабочему каталогу из нашего ранее созданного файла Dockerfile.

Теперь, когда сервер создан, мы можем перейти к конфигурации отладки, давайте начнем с нажатия кнопки «Add Configuration…», как показано на следующем снимке экрана:

Затем нажмите Add new… > PHP Remote Debug, как показано на снимке экрана ниже:

Затем откроется форма, в ней заполните имя своей конфигурацией удаленной отладки, затем проверьте параметр «Filter debug connection by IDE key», затем выберите ранее созданный сервер и, наконец, заполните ключ IDE (идентификатор сеанса) с тем же значением который использовался в директиве xdebug.idekey в нашем xdebug.ini. Подробнее на иллюстрации внизу:

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

Теперь Xdebug окончательно настроен в вашем PhpStorm, и вы можете пользоваться более надежным инструментом отладки, способным ускорить весь рабочий процесс.

Удачного кодинга!