Отладка PHP-приложений в Docker с помощью PhpStorm и Xdebug

В предыдущей статье мы разобрали, как настроить локальную среду разработки с помощью Docker Compose.  Сегодня мы разберемся, как настроить отладку php-приложений в Docker c помощью Xdebug.

Xdebug является незаменимым инструментом при разработке приложений на php, т.к. позволяет пошагово отследить выполнение приложения, увидеть значения всех переменных во время выполнения. Помимо отладки, Xdebug имеет ряд других полезных функций: профайлинг, генерация отчета code coverage для PHPUnit и другие.

Настройка отладки в PhpStorm

Откроем настройки PhpStorm: Languages & Frameworks > PHP > Debug:

В настройках устанавливаем, что Xdebug будет ожидать соединений на порту 9000 (по умолчанию).

Далее в настройках выбираем пункт Servers и добавляем новый сервер «Docker server»:

Указываем хост и порт, на котором доступен ваш Docker сервер. Далее устанавливаем маппинг нашей локальной директории с проектом с директорией проекта внутри контейнера: в левой колонке указывается абсолютный путь проекта на локальной машине, в правой колонке — абсолютный путь к директории проекта в контейнере (/test_project в моем случае). После этого сохраняем изменения.

Далее в верхнем меню выбираем Run > Edit configurations..., нажимаем на + и выбираем пункт PHP Remote Debug:

В открывшемся окне в поле Servers выбираем созданный нами ранее сервер, а в поле ide key указываем PHP_STORM (эта переменная должна совпадать с переменной, которую мы укажем в настройках контейнера).

На этом настройка окончена и PhpStorm готов принимать соединения Xdebug для отладки.

Установка расширения xDebug

Xdebug не входит в исходники PHP, поэтому для его установки воспользуемся библиотекой PECL. Добавим следующую строку в Dockerfile проекта:

RUN pecl install xdebug-2.5.0 \
   && docker-php-ext-enable xdebug

В данном случае мы воспользовались специальным встроенным скриптом для активации расширения docker-php-ext-enable. Подробнее об установке и настройке расширений можно прочитать в документации официального docker-контейнера PHP.

Теперь настроим Xdebug в соответствии с нашими настройками PhpStorm. Для этого добавим следующий скрипт в Dockerfile:

RUN echo xdebug.remote_enable=1 >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo xdebug.remote_port=9000 >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo xdebug.remote_autostart=1 >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo xdebug.remote_connect_back=0 >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo xdebug.idekey=PHP_STORM >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo xdebug.remote_host=172.18.0.1 >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

Расшифруем настройки, указанные выше:

• xdebug.remote_enable=1 — активируем удаленную отладку
• xdebug.remote_port=9000 — указываем Xdebug отправлять запросы на порт 9000
• xdebug.idekey=PHP_STORM — указываем idekey, который мы ранее указали в настройках PhpStorm
• xdebug.remote_host=172.18.0.1 — указываем ip адрес host-машины, т.к. Xdebug должен установить соединение с нашим компьютером для отправки отладочной информации. Вы можете узнать его, выполнив команду /sbin/ip route|awk '/default/ { print $3 }' внутри контейнера. Другие варианты можно посмотреть здесь: https://stackoverflow.com/questions/22944631/how-to-get-the-ip-address-of-the-docker-host-from-inside-a-docker-container
• xdebug.remote_connect_back=0 — отключаем эту опцию, т.к. она перезапишет настройку remote_host

После этого нужно пересобрать контейнер, чтобы новое расширение было установлено. Если вы используете Docker Compose, то пересобрать и запустить контейнер можно с помощью команды: docker-compose up --build.

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

Для начала отладки нужно разрешить PhpStorm принимать соединения от Xdebug (иконка с телефонной трубкой в правом верхнем углу окна) и выбрать из списка созданную нами ранее конфигурацию (Docker):

После установим breakpoint в коде проекта — для этого нужно кликнуть слева от нужной строки кода:

Теперь откроем наш проект в браузере. В PhpStorm должно появиться окно с входящим соединением Xdebug, которое нужно принять:

Теперь вы можете пошагово выполнять ваш код и отслеживать значения всех переменных!