PHPStorm + XDebug + Docker / Habr

Таких статей уже тысяча, зачем?

Мне не подошла полностью ни одна. Я потратил около двух часов на весь процесс и за это время нашёл около десятка статей, в которых либо данные были неполные, либо просто устаревшие

Я ожидаю, что у вас уже есть проект с настроенным докером.

Шагов, на самом деле, немного, все очень простые.

1. Настраиваем интеграцию PHPStorm с Docker

Идём в Settings > Build, Execution, Deployment > Docker и создаём максимально простую интеграцию через локальное приложение Docker:

2. Настраиваем выполнение скриптов через удалённый (в контейнере) интерпретатор

Идём в Settings > PHP > CLI Interpreter > 3 точки справа от него и добавляем такую конфигурацию:

У меня не проходит валидация установленного пхп, потому что версия 5.6, но это ни на что не влияет

Name может быть любым

Server выбираем тот, который создали шагом ранее

Configuration files: путь до docker-compose.yml

Service: контейнер с PHP

Остальное на ваш вкус, но в графе Lifecycle лучше оставить connect to existing container

Теперь, в графе CLI Interpreter вы увидите выбранным только что созданный конфиг:

3. Даём PHPStorm знать о том, как мы обращаемся к серверу

Идём в Settings > PHP > Servers и добавляем новую конфигурацию сервера:

Порт берём из своего конфига nginx. В моём случае он поднят в отдельном контейнере и смотрит наружу через 8001

Тут важно запомнить Name, это пригодится чуть позже

4. Чуть-чуть донастроим интеграцию PHPStorm с XDebug

Идём в Settings > PHP > Debug > XDebug и добавляем порт 9001:

5. Настроим конфигурацию запуска дебаггера

Идём в Run > Edit configurations и создаём новую конфигурацию на основе PHP Remote Debug:

Здесь Server это как раз Name из пункта #3

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

IDE key может быть любым, НО! Если у вас XDebug 3, то обязательно запоминаем значение

6. Донастраиваем docker-compose.yml

В контейнере с PHP для правильной интеграции с XDebug мы должны иметь доступ к локальной машине, то есть хосту:

old.???.php:
  container_name: old.???.php
  build: ./docker/php
  volumes:
    - ./:/app
  restart: unless-stopped
  extra_hosts:
    - "host.docker.internal:host-gateway"

Здесь важна только директива extra_hosts, она обязательна

7. Донастраиваем Dockerfile контейнера с PHP

Добавляем кусок конфига куда-нибудь в конец перед WORKDIR /app:

XDebug 2

# xdebug
COPY --from=mlocati/php-extension-installer /usr/bin/install-php-extensions /usr/bin/
RUN install-php-extensions xdebug
ENV PHP_IDE_CONFIG 'serverName=old.???’
RUN echo "xdebug.remote_enable=1" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN echo "xdebug.remote_host=docker.for.mac.localhost" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN echo "xdebug.remote_port=9001" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN echo "xdebug.remote_log=/var/log/xdebug.log" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN echo "xdebug.remote_autostart=1" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

XDebug 3

# xdebug
COPY --from=mlocati/php-extension-installer /usr/bin/install-php-extensions /usr/bin/
RUN install-php-extensions xdebug
ENV PHP_IDE_CONFIG 'serverName=old.???'
RUN echo "xdebug.mode=debug" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN echo "xdebug.start_with_request = yes" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN echo "xdebug.client_host=docker.for.mac.localhost" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN echo "xdebug.client_port=9001" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN echo "xdebug.log=/var/log/xdebug.log" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN echo "xdebug.idekey = PHPSTORM" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

В последней строке указываем IDE key из шага #5

Этот кусок ставит XDebug через через pecl и закидывает нужные параметры XDebug в конфиг

Из самого важного здесь:

ENV PHP_IDE_CONFIG - в serverName надо прописать Name из пункта #5
xdebug.*_port - порт из пункта #4
xdebug.*_host - в моём случае указан хост для мака, если у вас линукс или винда, то поищите альтернативы, они точно есть

8. Ставим брейкпоинты, заходим на сайт и радуемся жизни

Больше тут сказать нечего :)

Буду рад, если это кому-то поможет!

UPD @ 25.01.2023: добавил конфиг для XDebug 3