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

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

Подготовка: Установка Xdebug

Прежде чем настраивать интеграцию с PhpStorm, необходимо убедиться, что Xdebug установлен и активен в вашей среде PHP. Самый надежный способ — использовать PECL:

Откройте терминал и выполните: pecl install xdebug
Добавьте строку zend_extension=xdebug.so (или xdebug.dll для Windows) в файл php.ini
Перезапустите веб-сервер (Apache, Nginx) или PHP-FPM.

Проверить успешность установки можно командой php -v — в выводе должна появиться строка с упоминанием Xdebug. Также поможет php --info | grep xdebug.

Базовая конфигурация Xdebug в php.ini

После установки добавьте в php.ini следующие настройки для режима отладки:

xdebug.mode = debug — основной режим работы.
xdebug.client_host = localhost — хост, где запущен PhpStorm.
xdebug.client_port = 9003 — порт для прослушивания (по умолчанию с версии Xdebug 3).
xdebug.start_with_request = yes — автоматически запускать отладку при каждом запросе. Для экономии ресурсов можно использовать значение trigger и активировать отладку через GET/POST параметр или cookie.

Настройка PhpStorm для приема соединений

Шаг 1: Конфигурация сервера

Перейдите в Settings/Preferences → PHP → Servers и добавьте новый сервер:

Name: Имя вашего проекта (например, MyProject)
Host: Локальный адрес проекта (например, localhost или myproject.test)
Port: 80 или 443 (в зависимости от протокола)
Debugger: Xdebug
Обязательно отметьте галочку Use path mappings и настройте соответствие путей между локальной файловой системой и сервером.

Шаг 2: Настройка отладчика

В разделе Settings/Preferences → PHP → Debug убедитесь, что порт (Xdebug) установлен в 9003. Также рекомендуется активировать опции Can accept external connections и Ignore external connections through unregistered server configurations для безопасности.

PhpStorm должен «слушать» входящие соединения отладки. Включите этот режим, нажав на иконку телефона в правом верхнем углу (Start Listening for PHP Debug Connections) или используя горячие клавиши Ctrl+Alt+F5 (Win/Linux) / ⌘+⌥+F5 (Mac).

Шаг 3: Создание конфигурации запуска

Создайте новую конфигурацию запуска (Run → Edit Configurations...). Добавьте конфигурацию типа PHP Remote Debug. Выберите созданный ранее сервер и установите IDE ключ (если используется Xdebug 2) — обычно это значение PHPSTORM.

Инициирование сеанса отладки

Есть несколько способов запустить отладку:

Закладка браузера: Установите расширение Xdebug Helper для Chrome/Firefox.
Параметр URL: Добавьте ?XDEBUG_SESSION_START=PHPSTORM к адресу вашей страницы.
Отладка из CLI: Запустите скрипт через конфигурацию PHP Script в PhpStorm с активированным отладчиком.

Как только запрос достигнет PhpStorm, появится всплывающее окно с предложением принять входящее соединение. После принятия выполнение кода остановится на первой точке останова.

Продвинутые возможности

Освоив базовую настройку, исследуйте мощные инструменты:

Evaluate Expression: Выполняйте произвольный PHP-код в контексте отладки.
Watches: Отслеживайте значения конкретных переменных или выражений.
Conditional Breakpoints: Точки останова, срабатывающие только при выполнении заданного условия.

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

Почему PhpStorm не ловит входящее соединение от Xdebug?

Проверьте: 1) Режим "прослушивания" активирован в PhpStorm, 2) Порт в настройках IDE (9003) совпадает с xdebug.client_port, 3) Брандмауэр не блокирует порт, 4) Настройки пути (path mappings) корректны.

Как отлаживать скрипты, запущенные из командной строки?

Создайте конфигурацию запуска типа PHP Script, укажите файл скрипта и аргументы. Запускайте отладку через эту конфигурацию — PhpStorm автоматически передаст необходимые параметры Xdebug.

Отладка работает очень медленно. Что делать?

Не используйте xdebug.start_with_request = yes для продакшена. Включите режим trigger и активируйте отладку только когда это необходимо через расширение браузера. Также можно поэкспериментировать с настройкой xdebug.log_level.

Нужно ли платить за Xdebug?

Нет, Xdebug — это свободное программное обеспечение с открытым исходным кодом, распространяемое под лицензией PHP License.