Настройка XDebug в PHPStorm. Подробный гайд для настройки XDebug за 10 минут.

Я совсем не удивлен что многие даже опытные программисты до сих пор используют для отладки и трассировки скрипта запись в файл. Забудьте про этот “древний” способ отладки кода. Уже более 15 лет существует расширение XDebug для движка Zend PHP.  

XDebug – расширенный отладчик для PHP, предлагает разработчикам глубокий анализ и понимание работы их кода. Это мощный инструмент для отладки и профилирования, который помогает выявлять ошибки и узкие места в приложении. В этой статье мы рассмотрим, как настроить XDebug для работы в IDE PHPStorm. Мы разберем установку и конфигурацию XDebug, создание и управление отладочными сессиями, а также рассмотрим решение часто встречающихся проблем.

PHPStorm – de facto является самой популярной IDE для PHP. И интеграция XDebug с PHPStorm открывает перед разработчиками следующие возможности:

1. Точки остановки (Breakpoints): Установка точек остановки позволяет приостанавливать выполнение кода в определенных местах, что упрощает анализ работы приложения.
2. Шаг за шагом: Вы можете пошагово просматривать выполнение кода, понимая логику работы и взаимодействие различных компонентов.
3. Просмотр переменных: Во время остановки выполнения кода в точке останова PHPStorm позволяет легко просматривать и изменять значения переменных.
4. Профилирование: XDebug предоставляет возможности профилирования, что помогает определить наиболее ресурсоемкие части кода.
5. Удаленная отладка: Это особенно полезно при работе с распределенными или сложными средами.

Установка XDebug

Шаг 1: Проверка версии PHP

Перед установкой XDebug убедитесь, что у вас установлена поддерживаемая версия PHP. Откройте терминал и введите:

php -v

Эта команда отобразит текущую версию PHP. XDebug совместим с PHP 7.0 и выше.

Шаг 2: Получение правильной версии XDebug

Версия PHP	7.0	7.1	7.2	7.3	7.4	8.0	8.1	8.2	8.3
Версия XDebug	2.8.1	2.9.8	3.1.6	3.1.6	3.1.6	3.3.1	3.3.1	3.3.1	3.3.1

Скачивание и установка:

• Перейдите на официальный сайт XDebug и скачайте рекомендованную версию.
• Распакуйте скачанный файл и скопируйте его в директорию расширений PHP (обычно php/ext).

Шаг 3: Настройка php.ini для использования XDebug

1. Откройте файл php.ini. Путь к этому файлу зависит от вашей операционной системы и настроек PHP.
2. Добавьте следующие строки в конец файла php.ini:

[XDebug]
zend_extension="путь/к/расширению/xdebug.so" # для Linux/Mac
zend_extension="путь\к\расширению\php_xdebug.dll" # для Windows
xdebug.remote_enable=true # разрешение использования отладчика xdebug
xdebug.remote_host=127.0.0.1 # IP адрес для подключения xdebug
xdebug.remote_port=9003 # порт для поключения xdebug
xdebug.remote_handler=dbgp
xdebug.profiler_enable=1
xdebug.profiler_output_dir=/tmp
xdebug.remote_autostart=on # для начала отладки, необходимо отправить специальный GET/POST запрос. Чтобы отладчик всегда был готов к работе, необходимо включить данную настройку.
;xdebug.trace_format = 0
;xdebug.auto_trace = On
;xdebug.trace_output_dir = /tmp/traces
;xdebug.trace_output_name = trace.%c.%p
xdebug.max_nesting_level = 512

Замените "путь/к/расширению/xdebug.so" на фактический путь к файлу расширения XDebug.

Шаг 4: Перезапуск сервера

Перезапустите ваш веб-сервер или PHP-FPM, чтобы применить изменения. Если вы используете встроенный в PHP сервер, просто остановите и запустите его снова.

Шаг 5: Проверка установки

После перезапуска сервера проверьте, что XDebug установлен и настроен корректно:

1. Создайте файл info.php с содержимым <?php phpinfo(); ?>.
2. Откройте его в браузере.
3. Найдите раздел XDebug в выводе phpinfo(), что подтвердит успешную установку.

Настройка Xdebug на стороне PHPStorm

После успешной установки XDebug следующим шагом является его конфигурация в PHPStorm

Шаг 1: Настройка интерпретатора PHP

1. Откройте настройки PHPStorm. Перейдите в File > Settings (или PHPStorm > Preferences на macOS).
2. Перейдите в раздел “Languages & Frameworks > PHP”. Здесь вы увидите настройки для PHP.
3. Выберите вашу версию PHP в выпадающем списке “CLI Interpreter”. Убедитесь, что выбранный интерпретатор соответствует той версии PHP, для которой вы установили XDebug.
4. Проверьте, что XDebug активен. Нажмите на кнопку “Show” рядом с выбранным интерпретатором. В открывшемся окне должен быть указан XDebug в списке загруженных расширений.

Шаг 2: Настройка сервера

1. Настройте сервер в PHPStorm. В настройках (Settings/Preferences) перейдите в Languages & Frameworks > PHP > Servers.
2. Добавьте новый сервер. Укажите имя, хост (localhost) и порт вашего локального сервера. Если вы используете маршрутизацию через index.php, укажите это в настройках.
   В качестве Debug port , выберете порт 9003, либо любой свободный. Но в этом случае не забудьте поправить порт и php.ini. И выбрать пункт Can accept external connections
3. Настройте маппинг путей. Убедитесь, что путь на сервере соответствует локальному пути к вашему проекту. Это необходимо для корректной работы точек останова.

Шаг 3: Настройка отладочных конфигураций

1. Создайте или настройте отладочные конфигурации. Перейдите в Run > Edit Configurations.
2. Добавьте новую PHP Web Page или PHP Script отладочную конфигурацию. Укажите сервер, который вы настроили ранее, и, при необходимости, параметры запуска.

Шаг 4: Прослушивание входящих подключений XDebug

1. Включите прослушивание XDebug в PHPStorm. Нажмите на иконку “Start Listening for PHP Debug Connections” в верхней панели инструментов.

Шаг 5: Проверка конфигурации

1. Установите точку останова. Кликните слева от номера строки в вашем PHP-скрипте, где хотите остановить выполнение.
2. Запустите ваш PHP-скрипт. Если все настроено правильно, выполнение остановится на установленной точке останова.
3. Используйте окно отладки. Теперь вы можете шаг за шагом проследить выполнение кода, просматривать значения переменных и многое другое.

Создание и запуск отладочной сессии

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

Точки останова (breakpoints) – ключевой элемент в процессе отладки. В PHPStorm их можно установить следующим образом:

• Установка точки останова: Откройте файл PHP в PHPStorm, который вы хотите отлаживать. Кликните на поле слева от номера строки, где вы хотите установить точку останова. Появится красный кружок, обозначающий точку останова.

• Условные точки останова: Вы можете сделать точку останова условной, щелкнув правой кнопкой мыши по кружку и введя условие. Отладка остановится на этой строке только тогда, когда условие будет истинно.

Запуск отладочной сессии

1. Включите прослушивание XDebug: Убедитесь, что функция прослушивания подключений XDebug в PHPStorm активирована.
2. Запустите ваше PHP-приложение: Обычно это делается через браузер или командную строку. PHPStorm перехватит сессию благодаря активированной функции прослушивания.
3. Навигация по программе: Используйте инструменты шага в PHPStorm (Step Over, Step Into, Step Out) для навигации по вашему коду.

Работа с отладочной информацией

Просмотр переменных

1. Панель переменных: Когда выполнение остановлено на точке останова, PHPStorm отображает локальные переменные и их значения в окне “Variables”.
2. Изменение значений переменных: Вы можете изменять значения переменных во время отладки, просто кликнув по ним и введя новое значение.

Использование консоли

PHPStorm предлагает отладочную консоль, где вы можете выполнять PHP-код в контексте остановленной программы:

Выполнение кода: В консоли отладки введите PHP-код, который вы хотите выполнить, и нажмите Enter. Это может быть полезно для проверки результата функций или выражений.

Просмотр стека вызовов

Стек вызовов показывает цепочку вызовов функций и методов, которая привела к текущей точке останова:

1. Анализ стека вызовов: Используйте вкладку “Call Stack” для просмотра и навигации по стеку вызовов.
2. Переход к коду: Кликните по любой функции или методу в стеке вызовов, чтобы быстро перейти к соответствующей строке кода.

Дополнительные возможности XDebug

Профилирование кода

XDebug предоставляет возможности профилирования, позволяющие анализировать производительность кода:

1. Включение профилирования: Для активации профилирования добавьте xdebug.profiler_enable=1 в php.ini. Профилировщик будет создавать файлы с отчетами в указанной директории.
2. Анализ отчетов: Используйте инструменты визуализации, такие как KCacheGrind (Linux) или QCacheGrind (Windows), для анализа отчетов профилировщика.

Удаленная отладка

XDebug позволяет выполнять удаленную отладку, что особенно полезно при работе с развернутыми серверами:

1. Настройка XDebug для удаленной отладки: Убедитесь, что xdebug.remote_enable=1 установлен в php.ini на удаленном сервере. Кроме того, укажите xdebug.remote_host как IP-адрес вашей машины, где запущен PHPStorm.
2. Прослушивание удаленных подключений в PHPStorm: Включите прослушивание подключений XDebug в PHPStorm и начните сессию отладки.

Частые проблемы и их решения

Проблема: XDebug не запускается

• Убедитесь, что XDebug правильно установлен и конфигурирован в php.ini.
• Проверьте, что PHPStorm настроен на прослушивание подключений XDebug.
• Убедитесь, что нет конфликтов портов и ваш фаервол/антивирус не блокирует соединения.

Проблема: Точки останова не работают

• Проверьте, что точки останова активны и их условия (если есть) корректны.
• Убедитесь, что маппинг путей в PHPStorm правильно настроен.

Проблема: Производительность снижается при использовании XDebug

Включайте XDebug только при необходимости, особенно профилирование, так как оно может значительно замедлить выполнение скриптов.

Проблема: Проблемы с удаленной отладкой

• Проверьте настройки xdebug.remote_* в php.ini на удаленном сервере.
• Убедитесь, что удаленный сервер имеет доступ к вашему компьютеру через локальную сеть или интернет, а так же что порт открыт на компьютере (и прокинут на роутере в случае подключения через интернет).