Xdebug + PhpStorm: Полное руководство по настройке отладки PHP без стресса

Отладка PHP-кода часто превращается в утомительный процесс с бесконечными var_dump и error_log. Но с тандемом Xdebug и PhpStorm вы можете отлаживать код профессионально: ставить точки останова, инспектировать переменные в реальном времени и шаг за шагом проходить выполнение скрипта. Это руководство проведёт вас через все этапы настройки этой мощной связки.

Что такое Xdebug и зачем он нужен?

Xdebug — это расширение для PHP, которое превращает язык из простого инструмента для веб-разработки в полноценную среду с профессиональными возможностями отладки. Вместо того чтобы гадать, где скрывается ошибка, вы можете наблюдать за выполнением программы, как в замедленной съёмке.

Важно: Xdebug влияет на производительность. Не используйте его на продакшн-серверах. Включайте только в локальной или тестовой среде.

Шаг 1: Установка Xdebug

Самый простой способ — использовать PECL. Откройте терминал и выполните:

pecl install xdebug

Или установите через пакетный менеджер вашей ОС (apt, yum, brew). После установки добавьте строку в php.ini:

zend_extension=xdebug.so  # или xdebug.dll на Windows

Проверка установки

Создайте файл info.php с содержимым <?php phpinfo(); ?> и откройте его в браузере. Найдите блок "xdebug". Если он есть — расширение активно.

Шаг 2: Базовая конфигурация Xdebug

Добавьте в php.ini или в отдельный файл конфигурации (например, /etc/php/8.x/mods-available/xdebug.ini) следующие настройки:

xdebug.mode = debug
xdebug.client_host = localhost
xdebug.client_port = 9003
xdebug.start_with_request = yes  # или trigger для отладки по запросу

Порт 9003 стал стандартом для Xdebug 3.x. Ранние версии использовали порт 9000, который мог конфликтовать с PHP-FPM.

Шаг 3: Настройка PhpStorm

3.1. Настройка сервера

Откройте Settings/Preferences → PHP → Servers.
Добавьте новый сервер: укажите имя (например, "Local"), хост (localhost) и порт.
Важно: отметьте галочку Use path mappings и сопоставьте путь к файлам на сервере с путём в вашем проекте.

3.2. Конфигурация отладки

Перейдите в Run → Edit Configurations.
Нажмите "+" и выберите PHP Remote Debug.
Дайте имя конфигурации (например, "Xdebug Local").
Выберите ранее созданный сервер.
В поле "IDE key" укажите PHPSTORM (значение по умолчанию).

3.3. Активация слушателя отладки

На панели инструментов найдите иконку с телефонной трубкой (Start Listening for PHP Debug Connections) и нажмите её. Она должна стать активной (обычно меняет цвет).

Шаг 4: Запуск отладки

Теперь вы можете отлаживать:

Через браузер: Установите расширение (например, Xdebug Helper для Chrome) или добавьте параметр ?XDEBUG_SESSION_START=PHPSTORM к URL.
Из CLI: Установите переменную окружения export XDEBUG_SESSION=PHPSTORM перед запуском скрипта.
Из PhpStorm: Просто поставьте точку останова (щелчок слева от номера строки) и запустите скрипт.

Шаг 5: Продвинутые возможности

Кондиционные точки останова

Щёлкните правой кнопкой по точке останова → установите условие (например, $user->id == 42).

Отладка в Docker-контейнере

Вместо localhost укажите IP вашего хоста (например, host.docker.internal на Windows/Mac или IP-адрес сети Docker).

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

Измените xdebug.mode на debug,profile для анализа производительности.

Типичные проблемы и их решение

«Connection was not established»: Проверьте, что брандмауэр не блокирует порт 9003, и что слушатель в PhpStorm активен.
Точки останова не срабатывают: Проверьте маппинг путей в настройках сервера.
Медленная работа: Убедитесь, что xdebug.mode установлен только в debug, а не в develop,debug для обычной отладки.

Используйте плагин Xdebug Control для PhpStorm, чтобы быстро включать/выключать отладку и переключать режимы Xdebug.

FAQ: Часто задаваемые вопросы

Как проверить, что Xdebug работает?

Запустите в терминале: php -v. В выводе должна быть строка "with Xdebug v...". Также можно создать скрипт с var_dump(extension_loaded('xdebug'));.

Почему отладка такая медленная?

Xdebug передаёт много данных в IDE. Для ускорения можно использовать режим Step Debugging и отключить ненужные функции (например, вывод стека вызовов при каждом исключении).

Как отлаживать AJAX-запросы или API?

Добавьте заголовок XDEBUG_SESSION: PHPSTORM к вашему запросу. Это можно сделать через настройки расширения для браузера или в клиенте API (например, Postman).

Нужно ли перезагружать сервер после изменения настроек Xdebug?

Да, для PHP-FPM или Apache обычно требуется перезагрузка. Для CLI-скриптов — достаточно перезапуска скрипта.

Можно ли использовать Xdebug с OPcache?

Да, они совместимы. Однако в некоторых случаях может потребоваться отключить OPcache для отладки, если возникают проблемы с обновлением кода.

Настройка Xdebug и PhpStorm требует внимательности, но результат стоит усилий. Вы получаете мощный инструмент, который сэкономит вам сотни часов на поиске ошибок и понимании чужого кода. Удачной отладки!