Дебаг в PhpStorm с помощью XDebug под Docker, локально

Задача

Запустить в PhpStorm дебаг php-приложения, запущенного в docker-контейнере на том же компьютере, где работает PhpStorm.
Уточняю особенно, что контейнер на той же машине, где IDE, потому что с задачей дебага на удалённом сервере я пока не справилась.

Настройка Docker

Я пользуюсь генератором docker-compose PHPDocker.io, возьмём его результат за основу. Не забыть в поле Extensions поставить галочку напротив XDebug.
После, как обычно, скачать архив, распаковать файлы в корневую папку проекта.
В папке /phpdocker/php-fpm, где уже лежит файл с настройками php-ini-overrides.ini, я создала ещё один файл - xdebug.ini.

1
2
3
4
5
6
7
8
9
; ./phpdocker/php-fpm/xdebug.ini

zend_extension=/usr/lib/php/20170718/xdebug.so
xdebug.remote_enable=on
xdebug.remote_handler=dbgp
xdebug.remote_port=9000
xdebug.remote_autostart=on
xdebug.remote_connect_back=0
xdebug.idekey=PHPSTORM

За точными объяснениями настроек отсылаю к официальной документации. Замечу только, что порт 9000 можно изменить, но тогда его же нужно изменить в настройках PhpStorm. Кстати, remote_host можно указывать в этом же файле. Перейдём к нему вот-вот, я его указываю в docker-compose для удобства изменения.

Итак, перейдём к docker-compose.yml в корневой папке проекта. Все изменения делаются в сервисе php-fpm.

  1. Подключаем сделанные выше настройки xdebug.ini - добавить в раздел volumes строку

    1
    - ./phpdocker/php-fpm/xdebug.ini:/etc/php/7.2/mods-available/xdebug.ini
  2. Установим переменные среды.
    Cначала для этого стоит узнать ip docker-сети. Обычно это 172.17.0.1, в linux проверить можно командой

    1
    ifconfig docker0

И придумать имя сервера для PhpStorm, его будем указывать в настройках. Я ввожу “xdebug-docker”.
Добавляем ещё три строчки в docker-compose.yml, в сервис php-fpm:

1
2
3
environment:
XDEBUG_CONFIG: remote_host=172.17.0.1
PHP_IDE_CONFIG: "serverName=xdebug-docker"

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# ./docker-compose.yml

version: "3.1"
services:

webserver:
image: nginx:alpine
container_name: xdebug-one-webserver
working_dir: /application
volumes:
- .:/application
- ./phpdocker/nginx/nginx.conf:/etc/nginx/conf.d/default.conf
ports:
- "9122:80"

php-fpm:
build: phpdocker/php-fpm
container_name: xdebug-one-php-fpm
working_dir: /application
volumes:
- .:/application
- ./phpdocker/php-fpm/php-ini-overrides.ini:/etc/php/7.2/fpm/conf.d/99-overrides.ini
- ./phpdocker/php-fpm/xdebug.ini:/etc/php/7.2/mods-available/xdebug.ini #файл настроек XDebug
environment:
XDEBUG_CONFIG: remote_host=172.17.0.1 #docker network ip
PHP_IDE_CONFIG: "serverName=xdebug-docker" #имя сервера в PhpStorm; должно совпадать с тем, что в указываем в следующем шаге

Настройка PhpStorm

Теперь придётся с картинками.

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

Заходим в настройки File > Settings, ищем Server и добавляем новый сервер с тем же именем, которое только что указали в docker-compose. Адрес соответственно тоже ваш, порт тот же, что указан в docker-compose.
Указать mappings для папки public: абсолютный путь внутри контейнера /application/public

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

Если вы указали другой (не 9000) порт в файле xdebug.ini, зайдите сразу в раздел настроек Debug и измените номер порта там.
Закрываем окно настроек.

Debug configuration

Открываем Run > Edit Configurations и добавляем новую конфигурацию для PHP Remote Debug. Имя любое, сервер выбрать из списка, а ключ тот же, что мы указывали в xdebug.ini.

Настройка дебага

Запуск

Запустим приложение. Выполнить (в корневой папке проекта)

1
2
docker-compose build
docker-compose up -d

Предполагается, что точки для дебага в PhpStorm мы поставили. Запустить дебаг в PhpStorm можно в том же меню Run > Debug или на панели инструментов. Дебаг не заработает, пока PhpStorm не будет прислушиваться к соединениям!
После этого можно обращаться любым образом к localhost:9122. Открыть этот адрес в браузере или выполнить

1
curl localhost:9122

Переход к следующей точке по F8. И это всё, что я знаю о собственно процессе дебага в PhpStorm: пока я убивалась об попытки установить то же самое для дебага на удалённом сервере, я ничего не узнала о собственно работе с этим.
Я надеюсь, я решу задачу с удалённым хостом и напишу о ней. А на сегодня всё.

Ссылки

Кроме указанной документации мне очень помогли инструкции от esilvajr, который показал, как это настроить с файлами от phpdocker.io, и rfay, который подробно расписал процесс удалённого подключения (на реально удалённом сервере пока не сработало, но docker-контейнер с отдельным веб-сервером как бы удалённый с точки зрения системы).
Если мой пост недостаточно внятный, вы можете обратиться к их статьям.