php xdebug php fpm
Дебажим PHP-контейнер с помощью Xdebug и PhpStorm
Перевод статьи подготовлен в преддверии старта курса «Backend-разработчик на PHP».
Инструкция Docker #9: xdebug
Я создам очень простую php-страницу и подебажу ее с помощью xdebug и PhpStorm.
Исходные файлы можно найти здесь:
github.com/ikknd/docker-study в папке recipe-09
1. Создайте файл «Dockerfile» в папке «docker»:
Выполните эту команду из папки docker для создания образа:
2. Создайте файл docker-compose.yml в папке «docker»:
Здесь я использую образ «php-xdebug-custom» вместо «php:7.2-fpm „
3. Внесите в файл php.ini следующие настройки:
4. Настройте сервер в PhpStorm:
5. Настройте удаленный дебагер PHP в PhpStorm:
Добавьте новую конфигурацию и присвойте ей значения, как на следующем скриншоте:
6. Выберите конфигурацию дебага на панели дебага PhpStorm
7. Перейдите в /var/www/docker-study.loc/recipe-09/docker/ и выполните:
Я могу установить точку останова, начать прослушивание соединений в панели дебага PhpStorm и перезагрузить страницу.
Отладка с помощью XDebug и PhpStorm (дополнение)
Доброго времени суток, %username%!
Прочитал сегодня статью «Отладка с помощью XDebug и PhpStorm на примере сайта 1С-Битрикс». В ней автор использует «зеленого жука» для запуска отладки. В комментариях предложены еще несколько методов запуска отладки, такие как специальные закладки, различные плагины и т.д. На мой взгляд, все это неудобно, к тому же есть наиболее простой и удобный вариант. Я мог бы предложить его в комментариях к статье, но, увы, в read-only это невозможно. Посему вынужден писать отдельную статью.
У xdebug есть возможность автостарта, без всяких премудростей. Достаточно просто расставить breakpoint’ы и открыть Ваше приложение в браузере, xdebug будет подхватывать старт сам.
1. Настройка XDebug
В php.ini подключаем расширение и устанавливаем параметры:
2. Настройка PhpStorm
Настраиваем интерпретатор, если у вас это еще не сделано.
Далее добавляете сервер, если вы сервер локальный, то пишете в поле Host — localhost, если удаленный то адрес удаленного хоста. Имя хоста здесь и в php.ini должно совпадать.
Настраиваем XDebug. Порт берем из php.ini (xdebug.remote_port). Если вам не нужно чтобы XDebug останавливался на первой строчке приложения, отключаем два нижних чекбокса.
На этом настройка завершена, можно пользоваться.
Использование
Для начала работы расставляете breakpoint’ы, включаете прослушку порта XDebug и открываете ваше приложение.
Breakpoint’ы будут ловиться автоматически, без необходимости тыкать в «зеленого жука». Надеюсь информация кому-нибудь пригодится.
Отладка PHP приложений на удаленном хосте при помощи XDebug и vim в Linux
Введение
В PHP приложениях отладка при помощи var_dump, debug_backtrace и прочих полезных функций не всегда удобна, и возникает потребность в полноценном отладчике. Эта статья — для тех, кто по каким-либо причинам не хочет использовать IDE, поддерживающие отладку PHP приложений из коробки, вроде NetBeans или PhpStorm, а хочет использовать для этих целей vim, и при этом отладка происходит на удаленном хосте.
Для vim существует плагин «DBGp client», но он позволяет нормально отлаживать только в случае, когда пути до всех файлов на удаленной и на локальной машинах одинаковые. Например, если локальной машине у вас есть:
/home/user/application/
/home/user/framework/
а на удаленной машине они расположены в:
/var/www/html/application/
/var/www/framework/
то отладить приложение при помощи «DBGp client» не получится, так как он ничего не знает о другом расположении исходников.
Установка
Настраиваем vim на локальном хосте
Внимание: vim должен быть собран с поддержкой python, проверить это можно при помощи «:version«, в выводе должна быть строка «+python».
Устанавливаем и настраиваем Xdebug на удаленном хосте
Установите расширение Xdebug любым удобным для вас способом. Например, на Debian Squeeze это делается просто:
# apt-get install php5-xdebug
А в общем случае, лучше почитать официальную инструкцию по установке.
Настройте подключение к локальному debug-клиенту — для этого в php.ini пропишите следующие строчки, заменив 192.168.1.110 на IP локальной машины (при необходимости порт тоже можно перенастроить):
xdebug.remote_enable = 1
xdebug.remote_port = 9000
xdebug.remote_host = 192.168.1.110
Настраиваем соответствие файлов
Идея простая — при отправке запроса дебагеру (например, на установку breakpoint), мы должны преобразовывать путь на локальном хосте в путь на удаленном хосте, и наоборот, при получении информации от дебагера (например, о том что сейчас он находится на какой-то строке какого-то файла), мы должны сделать обратное преобразование.
Дописываем в конец файла debugger.py следующий код:
А в файл mapping (/home/alexey/mapping — замените на свой путь) записываем соответствие локальный и удаленных директорий, например:
/home/alexey/framework /var/www/framework
/home/alexey/application /var/www/html
Просматриваем код плагина в поисках мест, где от Xdebug приходят имена файла. В итоге, все они сводятся к вызову одного метода — set_srcview, в начало которого мы и добавляем изменение имени файла:
Теперь ищем места, где наоборот от debug-клиента к Xdebug передаются имена файлов. Таких мест два:
1. Класс Debugger, метод run, заменяем строку
2. Класс Debugger, метод mark, заменяем строку:
Уже поправленный debugger.py можно взять тут.
Использование
Запускаем отладку
Настройка под себя
Таймаут можно задать в том же скрипте, найдя в debugger.py строку:
Навигация по коду
Просмотр текущего состояния
Установка breakpoints
Toggle breakpoint (:Bp) — установить breakpoint в текущей строке, или удалить, если он уже есть.
На скриншоте — зеленая строка — это строка с breakpoint, красная — это текущая строка:
Docker + php-fpm + PhpStorm + Xdebug
Не так давно тимлид нашей команды сказал: ребята я хочу, чтобы у всех была одинаковая среда разработки для наших боевых проектов + мы должны уметь дебажить всё — и web приложения, и api запросы, и консольные скрипты, чтобы экономить свои нервы и время. И поможет нам в этом docker.
Поэтому, давайте уточним условия задачи:
На боевых серверах используется стандартная связка nginx + php-fpm + mysql. И, в чем проблема?
Разворачиваем на локальной машине точно такое же окружение + Xdebug, настраиваем наши проекты в PhpStorm, работаем. Для дебага включаем «трубку» в PhpStorm, всё работает из коробки, всё замечательно.
Всё это действительно так — всё работает из коробки. Но, давайте попробуем заглянуть под капот нашего рабочего окружения.
Nginx + php-fpm общаются через сокет, xdebug слушает порт 9000, PhpStorm тоже, по умолчанию, слушает порт 9000 для дебага и всё вроде бы замечательно. А если у нас открыто несколько приложений в PhpStorm, и включена прослушка («трубка)» для нескольких приложений? Что сделает PhpStorm? Он начнет ругаться, что обнаружено новое подключение для Xdebug, вы хотите его игнорировать, или нет?
Т.е., при настройках по умолчанию в PhpStorm, в конкретный момент времени, я могу дебажить только одно приложение. У всех других открытых приложений дебаг должен быть выключен. Блин, но это же неудобно. Я хочу слушать для дебага все приложения, и если в каком-то из них стоит точка останова, то я хочу, чтобы PhpStorm остановился в этом приложении, на той строке, где мне нужно.
А что для этого нужно? А нужно, чтобы каждое приложение запускалось со своими настройками для Xdebug. Чтобы каждое приложение слушало свой порт, искало свой сервер, а не так, как у нас всё общее, всё в одной куче.
А для этого есть замечательный докер! Мы можем запустить каждое наше боевое приложение в отдельном контейнере, на основе одного общего образа, например, php:7.1-fpm. Благодаря технологии докера мы можем изолировать наши приложения, при минимальных накладных расходах.
Ок, давайте заведем наши боевые проекты под докер, запустим каждый проект в отдельном контейнере, настроим каждый проект в PhpStorm для дебага индивидуально, всё должно быть замечательно.
Костылим, вот пример образа php:7.1-fpm, который будет собираться.
Update
Как справедливо указало сообщество — совсем уж жестко костылить всё-таки не надо.
Например хаброюзер 1ntrovert в своем комментарии
Поправленный пример Dockerfile
При запуске контейнера из данного образа пользователь www-data получает uid=1000, gid=1000. Обычно такие права у первого созданного пользователя в операционной системе Линукс. И, именно с такими правами будут работать наши php-fpm контейнеры. Буду очень благодарен, если кто-то подскажет как можно работать без костылей с правами доступа в докер.
При запуске контейнера из данного образа пользователь www-data получает uid и gid, которые будут переданы извне.
Также в комментариях поднималась тема: зачем вообще менять права пользователю www-data, чем не устраивают стандартные права 33. Только одним: когда мы зайдем в контейнер, и создадим, например, файл миграции, то на машине хоста владельцем этого файла будем не мы. И каждый раз надо будет запускать что-то вроде
И вторая небольшая проблема: для корректной работы Xdebug необходимо прописать верный ip адрес для машины хоста. У каждого члена команды он разный. 127.0.0.1 не катит. И тут нам на помощь приходит сам докер. Например, мы можем явно сконфигурировать сеть — 192.168.220.0/28. И тогда наша машина всегда будет иметь адрес 192.168.220.1. Этот адрес мы будем использовать как для настройки PhpStorm, так и для настройки других приложений. Например, при работе с MySql.
Сам docker-compose.yml, после учета замечаний, выглядит так:
Мы видим, что в данном конфиге создаются два контейнера php71-first и php71-two, на основе одного образа php:7.1-fpm. У каждого контейнера свои настройки для Xdebug. Каждый отдельно взятый контейнер будет слушать, для дебага, свой порт и свой сервер.
Также, обращаю ваше внимание на директивы
Без этих переменных образ php-fpm не запустится. Вопрос: как их передать в docker-compose.yml? Ответ: так как удобнее вам. Можно при запуске:
Полный код для демо версии выложен на гитхабе.
Листинг демо проекта:
Пробежимся, кратко, по листингу проекта.
Каталог hosts — конфигурационные файлы для Nginx. В каждом конфиге прописан свой контейнер php-fpm. Пример:
Каталог images — инструкции для сборки образов php-fpm, каталог mysql — храним базы, каталог www — все наши web проекты, в нашем примере first.loc и two.loc.
Давайте подведем промежуточные итоги: используя возможности докера мы запустили все свои рабочие проекты в одном окружении. Все наши проекты видят друг друга, для каждого из проектов прописаны уникальные настройки для Xdebug.
Осталось корректно настроить PhpStorm для каждого из проектов. При настройке мы должны прописать порт для дебага и имя сервера в нескольких местах.
Создаем проект в PhpStorm
Настраивать будем разделы меню
— PHP (необходимо верно прописать CLI Interpreter),
— Debug (меняем порт на 9008, как в файле docker-compose.yml),
— DBGp proxy (IDE key, Host, Port),
update Спасибо хаброюзеру CrazyLazy за важное замечание. Пункт меню DBGp proxy настраивать не надо.
— Servers (необходимо верно указать имя сервера, как в файле docker-compose.yml, и use path mappings)
Все дальнейшие скрины буду прятать под спойлер.
Хитрого ничего нет — важно, при настройке выбрать нужный образ, и верно прописать имя сервера. По умолчанию имя сервера Docker, у нас оно своё.
Опять же всё прописываем из настроек docker-compose.yml для конкретного контейнера. На этом же шаге валидируем как работает наш дебаг.
Важно правильно прописать use path mappings, имя сервера опять же берем из настроек
Сервер выбираем наш, созданный на предыдущем шаге.
Ну, собственно и всё. Написано много букв, вроде бы всё непросто
На самом деле — главное понять очень простую вещь. Благодаря технологии докера мы можем запустить все наши рабочие приложения в едином пространстве, но с разными настройками для Xdebug. Каждое приложение работает в своем контейнере, и нам остаётся аккуратно прописать настройки для каждого приложения в PhpStorm.
И на выходе мы получаем чудесную картину.
2. Прописываем узлы first.loc и two.loc в файле /etc/hosts
4. Настраиваем оба проекта first.loc и two.loc в PhpStorm, так как описано выше, и запускаем оба проекта в PhpStorm. Т.е. у нас открыто два окна PhpStorm, с двумя проектами, каждый из них слушает входящие соединения (трубка включена).
5. В проекте two.loc ставим точку останова на второй, например, строке. В первом проекте first.loc запускаем http запрос из файла http.http
И о чудо! Нас перекидывает во второй проект, на нашу точку останова.
Для дебага консольных скриптов делаем всё ровно тоже самое. Включаем трубку для прослушки, ставим точку останова, заходим в нужный контейнер, запускаем нужный скрипт.
Где php71first — алиас на машине хоста:
cdf — алиас, который работает в контейнере. Выше я писал о том, что для общения с контейнерами предпочитаю использовать алиасы.
На этом всё, конструктивная критика, замечания приветствуются.
Узнать и полюбить Xdebug
Как мне использовать его?
Xdebug поставляется с подробной инструкцией по установке в которой учтены практически все возможные варианты использования, хотя, если вы хотите поэкспериментировать с представленным ниже функционалом, мы рекомендуем использовать Homestead Improved так как там Xdebug установлен и активирован по умолчанию.
Зачем вообще нужен Xdebug когда есть современные IDE и Blackfire?
Современные IDE предоставляют широкие возможности поиска по коду, так что полезность функционала форматирования ссылок кажется сомнительной. Существуют всевозможные системы логирования способные обрабатывать ошибки и исключения. Также, трассировка и профилирование функций прекрасно реализованы в Blackfire. Не смотря на все это, форматирование ссылок на файлы лишь одна из функций Xdebug, а использование Blackfire связано с собственными трудностями — установка расширения, настройка горячих клавиш, и оплата сохранения истории трассировок. А использование логгеров требует внимательности, так как добавить их в приложение на поздних этапах не самая простая задача.
Но область использования Xdebug не ограничивается лишь этим. Он всё ещё необходим для правильного модульного тестирования (тестируемые фреймворки зависимы от его отчетов о покрытии кода), далеко не так легко провести отладку через удаленные брейк-пойнты другими средствами, а этот инструмент настолько старый и стабильный, что был отшлифован почти до идеала.
Конечно, нет никакой необходимости использовать Xdebug, если ваш текущий инструментарий может обеспечить всё что он предоставляет, или если вам не нужны его возможности, однако у меня не было еще ни одного проекта который можно было бы завершить так же эффективно без его использования.
Давайте попробуем
Предполагается что на этом этапе у вас уже есть среда с работающим Xdebug. Если нет, попробуйте воспользоваться Homestead Improved.
Вот что мы получим:
Отключение Xdebug
Блоки уведомлений подобные этому настолько привычное явление в наше время, что большинство людей даже не понимает что они уже стилизованы с помощью Xdebug. Чтобы доказать это давайте посмотрим как бы это сообщение выглядело без Xdebug. Для отключения Xdebug отредактируем файл /etc/php/7.1/fpm/conf.d/20-xdebug.ini в Homestead Improved, и закомментируем первую строку:
После чего нужно перезапустить PHP-FRM:
Примечание: если вы используете среду разработки с другой версией PHP, файл настроек вашего Xdebug скорее всего будет в другом месте. Сверьтесь с документацией системы чтобы найти его или задайте вопрос в комментариях.
Выглядит довольно скудно, не так ли? Из вывода пропал весь стек вызовов. Конечно, пока эта информация не слишком полезна, так как мы работаем только с одной строкой в единственном файле, но позже мы будем использовать ее довольно часто.
Теперь вновь активируем Xdebug, раскомментировав строку в отредактированном ранее файле, и продолжим. Не забудьте перезапустить PHP!
Переходы по файлам
Если у вас есть любимая IDE (у меня, например, PhpStorm), возможность переходить к файлам в ней простым кликом в трассировке стека была бы определенно полезной и значительно увеличила бы скорость отладки. Я продемонстрирую как реализовать эту возможность для PhpStorm.
Давайте снова откроем файл 20-xdebug.ini и добавим в него следующее:
Заметьте, что не во всех браузерах это будет работать. Например, у Opera возникнут проблемы со ссылкой phpstorm:// и она радостно упадет, в то время как Firefox и Chrome прекрасно обрабатывают такие ссылки.
Если теперь обновить нашу PHP страницу с ошибкой, мы получим ссылки открывающие IDE сразу в точном местоположении ошибки:
Настройка для работы с другими IDE и редакторами происходит точно так же.
Xdebug, Vagrant и PhpStorm
Зачем останавливаться на этом? Многие сегодня используют для разработки виртуальные машины, позволяющие быть уверенным в том что никакая часть из среды исполнения PHP не затронет основную машину, при этом сохраняя всё быстрым и гладким. Как ведет себя Xdebug в таких случаях? Кроме того, возможно ли, в принципе, выполнять отладку с брейк-поинтами, когда вы проходите по своему коду и проверяете каждую строку отдельно?
К счастью, Xdebug отлично поддерживает использование брейк-пойнтов при удаленном соединении. Мы рассмотрели этот процесс выше, а полностью иллюстрированное руководство по настройке вы можете найти в этой статье.
Использование профайлера.
В конце давайте рассмотрим одну из часто игнорируемых функций: профайлер. Для этого нам понадобится какое-нибудь крупное приложение, например Laravel:
И снова нам нужно внести правки в файл 20-xdebug.ini, добавив следующее:
Заметьте — мы не используем xdebug.profiler_enable = 1, так как не хотим чтобы он оставался включенным всё время. Вместо этого мы используем триггерный параметр в запросе “XDEBUG_PROFILE” для выборочной активации. Также мы выводим профиль кэша в основную общую папку нашей виртуальной машины, получая возможность работать с ним в операционной системе хоста.
После перезапуска PHP мы можем проверить это выполнив homestead.app/?XDEBUG_PROFILE (замените homestead.app на имя выбранного вами виртуального хоста или IP-адрес виртуальной машины). Конечно же, файл там где и ожидалось:
В каждой операционной системе есть собственный инспектор кэширования, для OS X, например, можно использовать qcachegring, который легко устанавливается через Homebrew. После установки…
… и открытия файла, мы видим удобное разбиение потока выполнения:
Профайлер предоставляет детализированный доступ ко многим данным и возможность досконально изучить поведение вашего кода, также как и в Blackfire. Однако с локальным выводом профайлера намного легче автоматизировать непрерывное отслеживание производительности и сложности выполнения.
Принудительное отображение Xdebug в Laravel
По умолчанию, Laravel имеет собственные отчеты об ошибках и настройки рендеринга. Ошибка, вроде той что мы вызвали ранее с неопределенной переменной, в Laravel будет выглядеть так:
Хотя экран ошибок Symfony (который Laravel использует в этом случае) способен так же хорошо работать с переходами Xdebug (попробуйте! Вы можете кликнуть по этим файлам и их строкам!), мне очень не хватает вывода информации о памяти (Xdebug по умолчанию выводит отчет об использовании памяти в каждый момент времени в трассировке). Давайте вернемся к экрану Xdebug в режиме разработки, чтобы отследить этот параметр.
Как видите мы обновили наш роутинг по умолчанию таким образом, чтобы сначала он активировал отображение ошибок (экран который мы видели ранее не показывает ошибки сразу при появлении, а сохраняет в стек исключений который был позже извлечен и визуализирован), затем мы возвращаем обработчик ошибок в его значение по умолчанию переопределяя значение Laravel.
После обновления, конечно же, вернулся наш старый экран — просто взгляните на эту простыню трассировки стэка и потребления памяти.
Я советую вам продолжить дальнейшее изучение самостоятельно — просмотрите документацию, поиграйте с настройками, выясните сколько всего вы можете узнать о ваших приложениях.
Заключение
Xdebug — ценный инструмент в наборе любого разработчика. Это мощное расширение полностью соответствует своему названию, делая язык, с которым мы ежедневно работаем, более подробным, дружелюбным и менее загадочным при возникновении ошибок.
За 15 лет своего существования Xdebug установил высокие стандарты для отладочных средств. Я хотел бы поблагодарить Дерика за разработку и поддержку всё это время, и буду рад если вы решите написать одно-два руководства об углубленном использовании, подводных камнях или скрытых комбинациях функций о которых никто не задумывался прежде. Давайте поможем его распространению и развитию и в следующие 15 лет.