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:

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

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

Здесь скрыт второй важный момент, который заключается в том, что необходимо правильно указать параметр 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 добавляем вот такую конфигурацию:

В поле 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 в PhpStorm

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

Для языка программирования PHP используется отладчик Xdebug, PHPStorm — это одна из самых популярных сред разработки. В этой статье мы рассмотрим как настроить Xdebug в PhpStorm для отладки на локальном компьютере и в Docker.

Настройка Xdebug в PhpStorm

1. Отладка на локальном компьютере

Все настройки будут показаны на примере Ubuntu и интерпретатора PHP, настроенного вместе с Apache. Для других конфигураций пути к файлам могут отличаться, но суть останется та же. Давайте разберемся как это будет работать. Отладчик Xdebug позволяет приостанавливать выполнение кода, смотреть стек вызовов и содержимое переменных. Однако удобного интерфейса управления у него нет. Поэтому для управления отладкой будем использовать IDE. Но IDE не может никак сообщить отладчику что надо запустить отладку, потому что она отвечает только за код. Для этого понадобится ещё расширение для браузера Debug Helper, с помощью которого вы сможете включить режим отладки.

Сначала необходимо установить Xdebug. Для этого выполните:

sudo apt install xdebug

После завершения установки Xdebug надо настроить программу так, чтобы при запуске сеанса отладки она пыталась подключится к нашей IDE для управления отладкой. Для этого добавьте такие строчки в файл /etc/php/7.4/apache2/conf.d/20-xdebug.ini в версии Xdebug 2:

sudo vi /etc/php/7.4/apache2/conf.d/20-xdebug.ini

zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_connect_back=1
xdebug.remote_port=9000
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_autostart=false

Для новой версии Xdebug 3 старая конфигурация тоже будет работать, но лучше использовать новый стандарт:

xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.discover_client_host = false
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9000

Давайте рассмотрим эти настройки подробнее. Первый параметр xdebug.mode — режим отладки, возможные варианты:

• develop — включает вывод дополнительной информации, переопределяет var_dump;
• debug — режим построчного выполнения кода, именно он нужен в данном случае;
• profile — профилирование;
• trace — трассировка выполнения программы.

Если необходимо, вы можете включить несколько режимов, перечислив их через запятую. Вторая строчка xdebug.start_with_request определяет как будет запускаться отладчик для режимов debug, trace и им подобных:

• yes — всегда, при запуске php скриптов;
• no — запуск только из кода с помощью специальных функций;
• trigger — по запросу, с помощью специальной переменной в $_ENV, $_POST, $COOKIE или в другом массиве. Этот вариант подходит лучше всего в данном случае чтобы отладчик не запускался когда в этом нет необходимости.

Если третья строка xdebug.discover_client_host имеет значение true, то xdebug пытается подключится к хосту, переданному в заголовке HTTP_X_FORWARDED_FOR. Но так как хост указывается в следующей строке, в данном случае эта возможность не нужна. Дальше указывается хост клиента, куда надо подключится для управления отладкой 127.0.0.1 и порт 9000. Именно этот порт используется в PhpStorm по умолчанию на данный момент. После сохранения настроек перезапустите Apache:

sudo systemctl restart apache2

Теперь надо настроить PhpStorm. Запустите программу, затем откройте меню Run -> Edit Configurations. Перед вами откроется окно, в котором надо настроить отладчик.

Нажмите кнопку + и в открывшемся списке выберите PHP Remote Debugger:

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

Если вам нужно изменить порт, к которому будет подключаться Xdebug откройте меню File -> Settings -> PHP -> Debug -> DBGp Proxy. Здесь можно указать нужный порт:

Теперь IDE готова. Кликните по значку жука на верхней панели инструментов чтобы программа начала ожидать подключения отладчика и поставьте несколько точек останова в коде просто кликнув перед строчкой с кодом:

Дальше осталось настроить браузер. Для Chrome можно скачать это расширение. Установите его и откройте страницу, которую надо отлаживать. Кликните по значку расширения и выберите Debug. Значок расширения станет зеленым:

Обновите страницу и возвращайтесь к PHPStorm. Если всё было сделано верно, там запустится сеанс отладки. При первом запуске программа может попросить настроить соответствия локальных путей к файлам с удаленными. Для локального сервера здесь ничего настраивать не надо, достаточно нажать Accept:

Дальше отладчик остановит выполнение на выбранной точке останова и в программе появится интерфейс отладки:

Как видите всё довольно просто. Дальше давайте разберемся как настроить Xdebug PhpStorm и Docker.

2. Отладка Php в Docker

C Docker возникает одна сложность. Поскольку отладчик должен сам подключится к IDE, необходимо пробросить хост в контейнер. В windows это можно сделать с помощью адреса host.docker.internal. Но в Linux, по умолчанию это не происходит. Для того чтобы добавить такой адрес надо добавить в docker-compose такие строчки:

Давайте для этого примера будем использовать такую структуру директорий:

Минимально необходимый docker-compose.yaml будет выглядеть вот так:

Здесь объявляется два контейнера, nginx и php-fpm. В первый не надо вносить никакие изменения, поэтому можно просто брать официальный образ, монтировать папку с исходниками, конфигурационный файл и пробрасывать порт. Во второй контейнер надо установить и настроить Xdebug поэтому его придется собрать на основе официального контейнера php. Для этого же контейнера надо указать директиву extra_hosts, без неё ничего работать не будет. Конфигурация Nginx тоже вполне стандартная:

Здесь настроена обработка PHP скриптов в контейнере php-fpm, и редирект несуществующих URL на index.php, что вполне стандартно для многих фреймворков и CMS. Самое интересное — Dockerfile контейнера php-fpm, он выглядит вот так:

FROM php:8.0.3-fpm-buster
RUN pecl install xdebug \
&& docker-php-ext-enable xdebug
COPY xdebug.ini /usr/local/etc/php/conf.d/xdebug.ini

Здесь устанавливается xdebug с помощью pecl, а затем копируется его конфигурационный файл в контейнер. Вот этот конфигурационный файл:

xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.discover_client_host = false
xdebug.client_host = host.docker.internal
xdebug.client_port = 9000

В контейнере установлен Xdebug 3 для PHP 8, потому что старая версия с этой версией языка уже не работает, поэтому используется новый синтаксис конфигурации. Ну и хост, host.docker.internal, который раньше был прописан в docker-compose.yaml. Настройка xdebug PHPStorm docker завершена. Дальше вы можете запустить проект:

docker-compose up —build

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

Выводы

В этой статье мы рассмотрели как выполняется настройка xdebug PHPStorm на локальном компьютере и в Docker контейнере. Если всё сделать правильно отладчик будет работать и помогать вам искать ошибки в коде.

Быстрый старт с Docker в PhpStorm

Это руководство является вольным переводом поста из блога PhpStorm со значительными дополнениями и описывает детали начала использования ПО Docker в связке с PhpStorm.

Итак, сегодня ты решил попробовать что-то новое и начать проект с нуля. Твоим первым шагом будет настройка среды разработки: как минимум, ты захочешь запустить веб-сервер и интерпретатор PHP (желательно — с установленным движком отладки).

С помощью Docker ты можешь начать разработку, запуск и отладку кода за считанные минуты!

Вероятно, самый простой способ интеграции Docker с PhpStorm — это использование данной страницы публичного реестра Docker Hub. Она представляет собой набор предварительно настроенных образов Docker, курируемых командой PhpStorm, которые охватывают наиболее распространённые потребности разработки на PHP.

Прежде чем продолжить, убедись, что у тебя на компьютере установлен Docker. Если у тебя его нет, то прочитай, как его установить на Windows или macOS.

Далее руководство описывает работу с Docker с помощью приложения Docker Desktop под Windows c использованием Linux контейнеров. Чтобы двигаться дальше, тебе следует использовать такое же окружение.

Docker Desktop — это новое приложение, которое пришло на смену устаревшему приложению Docker Toolbox. Docker Desktop для работы использует систему виртуализации Hyper-V от Windows, а Docker Toolbox использует VirtualBox от Oracle. Нативная виртуализация Hyper-V для Windows работает быстрее и надежнее, чем VirtualBox.

Стоит отметить, что после включения службы Hyper-V пропадёт возможность запускать и создавать x64 виртуальные машины на VirtualBox. Другими словами, ты можешь использовать либо Docker Desktop, либо Docker Toolbox. В последнем используется виртуальная машина на VirtualBox с минималистичным Linux окружением. Хотя Docker Toolbox и признан устаревшим, работа с ним слабо отличается от Docker Desktop.

1. Необходимые условия

Во-первых, тебе следует добавить нового локального пользователя в систему, эта новая учётная запись в будущем будет использоваться ПО Docker. Для этого нажми горячие клавиши Win + R и введи следующую команду в открывшемся окне:

Нажми Enter . Затем в левой части открывшегося окна выбери группу Пользователи . Теперь в списке пользователей (средняя часть окна), используя контекстное меню, выбери Новый пользователь. , как на скриншоте ниже.

Задай для нового пользователя, например, следующие параметры:

Чтобы назначить группу для нового пользователя, кликни правой кнопкой мыши на его имени и выбери пункт Свойства . Затем, на вкладке Членство в группах нажми кнопку Добавить , набери docker-users и нажми Ок . Готово, теперь этот пользователь будет иметь только те права, которые необходимы для работы ПО Docker.

Если с созданием нового пользователя возникли трудности, то тебе также может помочь следующая справка Windows: Создание учётной записи локального пользователя или администратора в Windows 10.

Во-вторых, убедись, что Docker доступен для связи через порт 2375. Для этого в разделе General настроек приложения Docker Desktop включи опцию Expose daemon on tcp://localhost:2375 without TLS option , как на скриншоте ниже.

В-третьих, с помощью пункта главного меню PhpStorm [File → Settings → Build, Execution, Deployment → Docker] установи параметры доступа к Docker API. Главное здесь это указать способ подключения к демону Docker. Выбери переключатель TCP socket , а в поле Engine API URL укажи следующее значение (если его ещё там нет):

Параметры подключения зависят от используемой версии Docker и операционной системы. Дополнительные сведения по этому вопросу ты можешь узнать из следующей справки PhpStorm: Настройки соединения с Docker.

IDE автоматически проверит твои настройки и покажет сообщение Connection successful в случае успешного подключения к Docker API. Оно должно появиться в нижней части диалогового окна, под окном сопоставления путей, как на скриншоте ниже.

Также в подразделе [Build, Execution, Deployment → Docker → Tools] настроек PhpStorm обязательно укажи или проверь актуальность указанных путей исполняемых файлов:

• docker-machine.exe (поле Docker Machine executable )
• docker-compose.exe (поле Docker Compose executable )

Если возникли сложности в этом вопросе, то изучи справку PhpStorm: Инструменты Docker.

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

2. Определение окружения

Для начала создай новый проект в PhpStorm. Затем добавь в его корень новый файл с именем docker-compose.yml . Он позволяет описать конфигурацию сервисов твоего приложения для утилиты Docker Compose с помощью YAML формата.

Docker Compose — это CLI инструмент для автоматизации процесса создания и выполнения приложений, скомпонованных из нескольких Docker-контейнеров.

В данном случае будет задействован один сервис — веб-сервер:

Как ты мог заметить, в этом конфиге используется предварительно настроенный образ Docker, содержащий веб-сервер Apache и PHP 7.1 с расширением Xdebug.

Обрати внимание, что для настройки Xdebug в директиве remote_host используется значение host.docker.internal для ссылки на удалённый адрес хоста. В Docker для Windows и macOS он автоматически преобразуется во внутренний адрес хоста, позволяя легко подключиться к нему из контейнера.

Значение host.docker.internal на Linux в настоящее время не поддерживается. Вместо этого ты можешь использовать имя хоста своей локальной машины (чтобы его узнать, введи в терминале команду hostname ).

Соответствующий раздел конфигурации окружения для Linux будет выглядеть следующим образом:

Для получения более подробной информации по этому вопросу, смотри сюда.

Конфигурация окружения полностью готова.

Теперь ты можешь использовать её с помощью Docker Compose, создав специальную конфигурацию запуска или отладки в PhpStorm.

3. Создание конфигурации запуска или отладки

Сделай клик правой кнопкой мыши на файле docker-compose.yml и выбери пункт Create. из контекстного меню:

В открывшемся диалоговом окне задай имя конфигурации, например, Start application . Затем сделай необходимые правки и сохрани конфигурацию запуска с параметрами, как на скриншоте ниже:

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

Первый запуск данной конфигурации, скорее всего, будет довольно длительным, тебе придётся немного подождать. Дело в том, что образ, указанный в docker-compose.yml наверняка отсутствует в твоей системе, следовательно, он будет скачен из Docker Hub, на это и требуется дополнительное время. Позже он всегда будет использоваться для того, чтобы развернуть необходимый контейнер.

Если ранее, в разделе Shared Drives настроек приложения Docker Desktop, ты не настроил диски, которые должны быть доступны для контейнеров, то получишь следующее уведомление:

Нажми в нём кнопку Share it . Затем должно появиться окно File Sharing . В нём тебе следует ввести имя и пароль ранее созданного пользователя, затем нажми OK .

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

В итоге PhpStorm должен автоматически загрузить нужный образ, развернуть на его основе необходимый контейнер и запустить веб-сервер:

На самом деле, в итоге будут загружены 2 образа: docker4w/nsenter-dockerd и phpstorm/php-71-apache-xdebug-26 , смотри скриншот выше. Первый не указан в конфигурации окружения для Docker Compose, cчитай его служебным, он используется для настройки монтирования файловой системы в Docker Desktop.

Теперь всё готово для запуска и отладки кода.

4. Запуск или отладка кода

Убедись, что всё работает как надо. Для этого создай самый простой PHP файл и попробуй отладить его, следуя подходу PhpStorm Zero-Configuration Debugging.

Поскольку Xdebug уже установлен и настроен, тебе нужно лишь сделать следующее:

• Установить и включить расширение отладки для браузера:
• Установить точку останова в коде:
• Включить прослушивание входящих отладочных соединений в PhpStorm:

Теперь, просто открой страницу в браузере, и сеанс отладки будет запущен автоматически:

В данном руководстве был рассмотрен очень простой случай, но ты можешь использовать описанный метод, чтобы предоставить своей среде, например, базу данных или сервер SFTP. Далее, дополнительно, попробуй изучить страницу PhpStorm реестра Docker Hub. Использование образов Docker от команды PhpStorm сэкономит тебе много усилий и позволит начать кодирование в считанные минуты.

Чтобы узнать больше о Docker и о том, как его использовать в PhpStorm, обязательно ознакомься с отличной обучающей серией уроков от Pascal Landau и документацией PhpStorm.