Настройка Xdebug на виртуальной машине, удаленном сервере и в Docker контейнере

Привет, товарищи разработчики! Сегодняшний пост будет полезен всем PHP-разработчикам, так как речь пойдет о настройке такого инструмента отладки, как Xdebug. В рамках данного поста я расскажу как запустить Xdebug на виртуалке, на удаленном сервере через SSH-туннель и даже внутри Docker контейнера.

Тот кто внимательно следит за блогом скажет, что мол была уже запись про отладку кода в PhpStorm с использованием Xdebug и сколько можно об этом писать. Да, об этом писал и по-прежнему рекомендую пост к прочтению, если хотите разобраться в самом процессе отладки кода. Этот же пост нацелен на более нетривиальные задачи по настройке Xdebug.

В отличие от предыдущего поста сегодняшнюю настройку Xdebug мы будем производить уже без использования OpenServer, от которого я кстати рекомендую отказаться, если вы считаете себя более ли менее продвинутым разработчиком. Для продвинутых разработчиков нынче в тренде Linux. Что касается меня, то я так и не решился перейти полностью на Linux — использую по-старинке Windows 7 и серверную Ubuntu 14.04, запущенную на виртуалке средствами VirtualBox. Не могу сказать, что проще: перейти полностью на Linux или остаться на Windows, но с виртуальным Linux и кучей головняка по синхронизации файлов. По своему опыту могу сказать, что за полгода-год удается, как правило, решить все проблемы связки Windows + Linux и работать без особых проблем.

Собственно, к чем был предыдущий абзац — к тому, что сегодняшняя лекция по настройке Xdebug будет полезна прежде всего тем, кто, как и я, использует Windows в качестве основной системы и Linux в качестве оси на виртуалке. Хотя закоренелые пользователи Linux может тоже найдут, что-нибудь полезное.

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

• Ubuntu 14.04
• PHP 5.5.9
• Apache 2.4.7

Установка Xdebug на сервер

Надеюсь, у вас уже есть сервер, на котором установлен как минимум PHP. Для установки Xdebug на Ubuntu или Debian вам понадобится всего несколько команд:

sudo apt-get update
sudo apt-get install php5-xdebug

Ну вот, Xdebug должен быть успешно установлен. Осталось только его настроить — для этого необходимо создать .ini-файл с нужными параметрами и положить в директорию, с которой PHP зачитывает конфиги. В моем случае — это /etc/php5/mods-available/.

Создаем файл xdebug.ini:

sudoedit /etc/php5/mods-available/xdebug.ini

Пишем следующее:

zend_extension = xdebug.so

Сохраняем файл (CTRL + X) и перезапускаем веб-сервер, чтобы применить настройки:

sudo php5enmod xdebug
sudo service apache2 restart

Это еще не конечная настройка Xdebug, но на данном этапе мы уже сможем проверить подхватывает ли PHP наши настройки. Для этого воспользуйтесь либо консольной командой php -i | grep "xdebug", либо php-файлом с функцией phpinfo(); на одном из сайтов, расположенных на вашем сервере.

Если у вас все получилось — переходим к более тонкой настройке Xdebug, которая позволит осуществлять отладку кода.

Настройка Xdebug на виртуалке (VirtualBox)

Следующим шагом будет настройка как Xdebug, так и PhpStorm для отладки web-приложения, которое запускается с вашего виртуального сервера. Другими словами: у вас есть сайт на Drupal и вы хотите заняться отладкой кода, запуская сайт через любимый браузер.

Конфиг для xdebug.ini:

zend_extension=xdebug.so
[xdebug]
xdebug.remote_enable = 1
xdebug.remote_connect_back = 1
xdebug.idekey = "PHPSTORM"
xdebug.remote_port = 9000
xdebug.var_display_max_data = 2048
xdebug.var_display_max_depth = 128
xdebug.max_nesting_level = 500

И не забывайте делать рестарт вашего web-сервера после каждого изменения xdebug.ini.

sudo service apache2 restart

Из важных настроек:

• xdebug.remote_connect_back — если данный параметр активен, то Xdebug пытается подключиться к клиенту, которым был совершен HTTP запрос. Данная настройка удобная если вы не хотите указывать фиксированный IP-адрес.

Теперь необходимо настроить наш IDE — PhpStorm. По умолчанию PhpStorm слушает 9000 порт, однако это можно изменить где-то глубоко в настройках. В настройках Run/Debug Configurations добавляем PHP Web Application и конфигурируем, как показано на скриншотах.

В качестве Host указываем локальное доменное имя вашего приложения. Сразу хочу оговориться про "8080" порт — это специфика моей виртуалки, у вас все может быть по-другому. Не забудьте настроить маппинг — крайне важно! Собственно, через маппинг вы указываете соответствие между файлами, которые лежат на вашей основной системе (Windows), и файлами, которые лежат на виртуальном сервере (Linux).

Если все настроили верно, то после запуска отладки (клик по зеленому "жуку" или Shift + F9) вас должно перебросить в браузер, где будет открываться сайт по URL вида: http://www.nvidia.loc:8080/?XDEBUG_SESSION_START=10261. На этом настройка закончена, можете смело переходить к отладке, которая уже описана в другой заметке.

Кстати, если вам необходимо остановить работу Xdebug, то добавьте параметр ?XDEBUG_SESSION_STOP к запрашиваемой странице. Многие ошибочно полагают, что можно остановить отладчик через PhpStorm, но это не всегда срабатывает. Поэтому, если у вас есть подозрение, что сайт завис и не открывается из-за Xdebug — попробуйте воспользоваться этим советом.

Настройка Xdebug для отладки PHP-CLI скриптов

Представьте, что вам необходимо заняться отладкой скриптов, которые хоть и написаны на PHP, но запускаются через консоль — через так называемый PHP-CLI. Мне приходилось с этим сталкиваться при работе с RabbitMQ и CodeCeption. Для настройки я рекомендую создать какой-нибудь тестовый php-скрипт (например, test.php с парой математических выражений и ответом, который выводится через "echo") и положить его в проект (на сервере и на Windows). Убедитесь, что скрипт работает запустив его:

php test.php

Конфиг для xdebug.ini:

zend_extension = xdebug.so
[xdebug]
xdebug.remote_enable = 1
xdebug.remote_autostart = 1
xdebug.remote_host = 192.168.56.1
xdebug.idekey = "PHPSTORM"
xdebug.remote_port = 9000
xdebug.var_display_max_data = 2048
xdebug.var_display_max_depth = 128
xdebug.max_nesting_level = 500

Главное отличие от выше предложенных настроек — это то, что xdebug.remote_connect_back отсутствует по причине того, что при запуске скрипта через консоль отсутствует переменная $_SERVER['REMOTE_ADDR'], которая содержит IP-адрес клиента, по которому Xdebug пытается подключиться. Поэтому мы должны использовать фиксированный IP-адрес. Если вы используете VirtualBox, то этот IP-адрес будет, как правило, "192.168.56.1".

Настройки для PhpStorm можно оставить прежними. Однако потребуется сделать еще один финт ушами на стороне сервера, чтобы отладка кода проходила как по маслу. Дело в том, что с текущими настройками Xdebug ломится на 9000 порт, но не понимает какую схему для маппинга использовать. Поэтому в командной строке сервера пишем следующую команду:

export PHP_IDE_CONFIG="serverName=MyServ"

Обратите внимание, что "MyServ" — это имя Server'a, которое мы указали при настройке отладчика в PhpStorm. Кстати, чтобы каждый раз не прописывать эту команду при подключении к вашему серверу, можете поместить ее в ~/.bashrc файл.

Далее в PhpStorm активируйте режим "Start Listening for PHP Debug Connections", установите Breakpoint и запустите php-скрипт в консольном окне.

Если вам необходимо отключить отладчик — просто отключите режим прослушивания PHP Debug подключений, кликнув по той же самой кнопке.

На самом деле вы можете использовать предложенный в этой главе конфиг xdebug.ini и для отладки тех же Web-приложений. Я просто хотел объяснить суть параметра xdebug.remote_connect_back на примерах, поэтому привел разные конфиги для двух глав.

Настройка Xdebug для удаленного сервера

Представьте ситуацию, что у вас есть удаленный сервер, на котором крутится сайт и вы хотите подлезть к нему с отладчиком. Основная проблема заключается в том, что скорее всего вы используете общий IP-адрес для выхода в интернет, что не позволит вам работать с Xdebug напрямую. Да, ситуация нестандартная, но не стоит отчаиваться: решение есть и имя ему SSH-туннель. Если не знаете, что это такое, то рекомендую задать следующие вопросы Google: "ssh туннель", "проброс портов" или же "ssh port forwarding". Если в двух словах, то мы создадим подключение, которое пробросит 9000 порт от сервера на 9000 порт хостовой системы, через который уже работает PhpStorm.

Если ваша хостовая система Windows, как и у меня, то скорее всего придется использовать тулзу PuTTy, которую вы уже должны были установить, если читали мой пост про настройку среды для разработчика Drupal проектов. Опять же, я не буду вдаваться в подробности, как настроить стандартное подключение через PuTTy — я думаю, что люди, которые хоть раз работали с удаленным сервером, знают как это делается. Проброс 9000 порта описан в следующем скрине:

Т.е. вы берете сохраненное подключение и всего лишь модифицируете указанным образом. Теперь при каждом подключении к серверу через PuTTy у вас будет осуществляться проброс 9000 порта, что позволит вам решить проблему общего IP-адреса.

Конфиг для xdebug.ini для удаленного сервера:

zend_extension = xdebug.so
[xdebug]
xdebug.remote_enable = 1
xdebug.remote_host = 127.0.0.1
xdebug.idekey = "PHPSTORM"
xdebug.remote_port = 9000
xdebug.var_display_max_data = 2048
xdebug.var_display_max_depth = 128
xdebug.max_nesting_level = 500

Что касается настроек PhpStorm, то вам придется создать новый PHP Web Application и новый Server по аналогии с настройкой отладчика для виртуалки. Не забудьте настроить верный маппинг для файлов!

Настройка Xdebug в Docker контейнере

Пожалуй, это была самая интересная задача, связанная с настройкой Xdebug, на моей памяти. Что такое Docker я опять же в рамках этой статьи рассказывать не буду, но скажу, что Docker — это клевая штука, и думаю, что в ближайшие годы многие с ней столкнуться. Пусть эта глава будет бонусом для тех, кто более ли менее уже щупал в руках Docker и хочет настроить собственный Docker Image для разработки.

Настраивать Xdebug придется в том же контейнере, где крутится PHP и Web-сервер. Для примера я набросаю более ли менее рабочий вариант Dockerfile, в основу которого положен PHP Official образ.

Первым подводным камнем является тот момент, что придется тянуть OpenSSH в контейнер — без этого вы просто не сможете настроить удаленное подключение для проброса 9000 порта. Вторым камнем будет проблема с запуском нескольких бэкграунд процессов в контейнере: первый процесс — это Apache, второй — притянутый нами OpenSSH. Дело в том, что Docker запускает только один процесс, указанный через CMD в Dockerfile — с этим я в своем время провозился больше всего. Решением проблемы запуска нескольких бэкграунд процессов в контейнере является Supervisor.

В общем, представляю вашему вниманию пример Dockerfile, который позволит вам использовать Xdebug в Docker контейнере на удаленном сервере:

FROM php:5.6-apache
 
# supervisor installation
RUN apt-get update && apt-get -y install supervisor && \
  mkdir -p /var/log/supervisor && \
  mkdir -p /etc/supervisor/conf.d
 
# openssh installation
RUN apt-get update && apt-get install -y openssh-server
RUN mkdir /var/run/sshd
COPY docker/sshd_config /etc/ssh/sshd_config
 
# создаем пользователя dev, которого будем использовать 
# для удаленного ssh-подключения к контейнеру
RUN adduser dev --disabled-password --gecos ""
RUN usermod -aG www-data dev
 
# копируем authorized_keys из хостовой системы
# для авторизации по ssh-ключу
RUN mkdir /home/dev/.ssh
COPY docker/authorized_keys /home/dev/.ssh/authorized_keys
RUN chmod 700 /home/dev/.ssh
RUN chmod 600 /home/dev/.ssh/authorized_keys
RUN chown -R dev:dev /home/dev/.ssh
 
EXPOSE 22
 
# xdebug installation
RUN pecl install xdebug
COPY docker/ext-xdebug.ini /usr/local/etc/php/conf.d/
 
COPY docker/supervisor.conf /etc/supervisor/conf.d/supervisord.conf
 
WORKDIR /var/www/html
 
CMD ["/usr/bin/supervisord"]

Содержимое для supervisor.conf:

[supervisord]
nodaemon=true
 
[program:apache2]
command=/bin/bash -c "source /etc/apache2/envvars && exec /usr/sbin/apache2 -DFOREGROUND"
 
[program:sshd]
command=/usr/sbin/sshd -D

Ну и собственно bash-скрипт, который соберет вам контейнер:

#!/bin/bash
 
# копируем файлы, которые помогут поднять OpenSSH в конетейнере с настройками,
# аналогичными настройкам хостовой системы
cp ~/.ssh/authorized_keys ./docker
cp /etc/ssh/sshd_config ./docker
docker build -t angarsky-dev .
docker run -it --name angarsky-dev -v PATH_TO_SITE_FILES:/var/www/html -p 80:80 -p PORT_FOR_EXAMPLE_32777:22 -d angarsky-dev
rm  ./docker/authorized_keys ./docker/sshd_config

Я не обещаю, что контейнер с предложенным мною конфигом сразу же у вас заведется. Скорее всего вам придется потратить какое-то время, чтобы разобраться и допилить его под свои нужды. После того, как контейнер заведется проверьте подхватился ли Xdebug и попробуйте настроить SSH подключение: в качестве пользователя используйте "dev", в качестве хоста — IP-адрес сервера, в качестве порта — выбранный порт при запуске контейнера (32777 из примера). Если у вас получилось подключиться — добавьте в подключение проброс порта и можете приступать к отладке!

На самом деле я думаю сделать отдельную статью о том, как с помощью Docker'a настроить среду для разработки. Поэтому сейчас, пожалуй, не буду вдаваться в подробности его использования. Надеюсь, предоставленных данных будет достаточно для настройки Xdebug тем, кто уже имеет опыт работы с Docker'ом.

Ну вот, вроде изложил все свои нынешние знания по настройке Xdebug. Можете добавлять страницу в закладки — будет отличной шпаргалкой на будущее! Если есть вопросы — задавайте. Если кому-то поможет моя статья можете оставить "Спасибо" в качестве фидбека.