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

Отладка PHP-кода может превратиться из мучительного процесса поиска ошибок через var_dump в элегантный и контролируемый диалог с вашим приложением. Связка Xdebug и PHPStorm — это профессиональный стандарт для разработчиков, который позволяет буквально «шагать» по коду, наблюдая за каждым изменением переменных. В этом руководстве мы разберем настройку от начала до конца, включая все подводные камни.

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

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

Важно: Xdebug работает по принципу клиент-сервер. Ваш PHP-скрипт (сервер) общается с PHPStorm (клиент) через определенный порт. Для этого нужно правильно настроить обе стороны.

Пошаговая настройка Xdebug

Шаг 1: Установка расширения Xdebug

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

pecl install xdebug

Или установите через пакетный менеджер вашей ОС (apt, yum, brew). После установки добавьте в php.ini конфигурацию. Лучше создать отдельный файл, например, /etc/php/8.x/mods-available/xdebug.ini со следующим содержимым:

zend_extension=xdebug.so
xdebug.mode=debug
xdebug.client_host=localhost
xdebug.client_port=9003
xdebug.start_with_request=yes
xdebug.idekey=PHPSTORM

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

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

Создайте php-файл с содержимым <?php phpinfo(); ?> и откройте его через веб-сервер или CLI. Найдите блок «xdebug». Должны быть видны активный режим (debug) и версия расширения.

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

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

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

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

Перейдите в Settings/Preferences → PHP → Debug.
Убедитесь, что порт (Debug port) установлен в 9003.
Поставьте галочку Can accept external connections.
В разделе «Pre-configuration» проверьте, что IDE key установлен как PHPSTORM.

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

Нажмите на значок «телефонной трубки» в правом верхнем углу PHPStorm (Start Listening for PHP Debug Connections). Теперь IDE слушает порт 9003, ожидая соединения от Xdebug.

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

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

Через браузер: Установите расширение для браузера (например, Xdebug Helper для Chrome) и активируйте отладку, выбрав IDE «PHPStorm». Или просто добавьте параметр ?XDEBUG_SESSION_START=PHPSTORM к URL.
Из CLI: Запустите скрипт с переменной окружения: XDEBUG_SESSION=1 php your_script.php. Предварительно в PHPStorm создайте конфигурацию «PHP Script».

Профи-совет: Используйте «Zero-Configuration Debugging» в PHPStorm для некоторых фреймворков. А также настройте условия (conditions) и логгирующие точки останова (logging breakpoints) для сложных сценариев.

Решение частых проблем

Отладчик не останавливается на точках останова: Проверьте path mappings, перезагрузите конфигурацию PHP (service php-fpm restart) и убедитесь, что слушатель в PHPStorm активен.
Ошибка «Connection was not established»: Проверьте, не блокирует ли брандмауэр порт 9003. Убедитесь, что xdebug.client_host ведет на IP машины с PHPStorm (для Docker-окружения используйте host.docker.internal или IP хоста).
Медленная работа: В продакшн-среде отключайте Xdebug (xdebug.mode=off). Для отладки используйте режим xdebug.start_with_request=trigger, чтобы он активировался только по вашему запросу.

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

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

Создайте скрипт с phpinfo() или выполните в терминале: php -r "echo phpversion('xdebug') ? 'Xdebug активен' : 'Xdebug не найден';".

Нужно ли перезагружать веб-сервер после настройки?

Да, для веб-сервера (Apache/Nginx) и PHP-FPM требуется перезагрузка или reload конфигурации.

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

Чаще всего проблема в неправильном client_host в настройках Xdebug. Для локальной разработки на одной машине используйте localhost. Для Docker или виртуальной машины укажите IP-адрес хоста.

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

Да, это распространенная практика. В контейнере с PHP настройте xdebug.client_host на host.docker.internal (Mac/Windows) или IP-адрес хоста в сети Docker (Linux). Пробросьте порт 9003 из контейнера на хост.

В чем разница между Xdebug 2 и Xdebug 3?

Xdebug 3 имеет улучшенную производительность, измененные названия параметров (например, xdebug.remote_port стал xdebug.client_port) и режимы работы (debug, develop, profile и др.), которые включаются через xdebug.mode.