Без рубрики

Отладка PHP в Битрикс с помощью Xdebug и PhpStorm: настройка за 10 минут

07.03.2026

Отладка через var_dump и логи — это медленно. Xdebug + PhpStorm позволяют ставить точки останова, смотреть стек вызовов и значения переменных в реальном времени. Настраивается за 10 минут на BitrixVM или Open Server.

Установка Xdebug на BitrixVM (CentOS/AlmaLinux)

# Узнаём версию PHP
php -v

# Для PHP 8.x
yum install -y php-xdebug

# Или через PECL
pecl install xdebug

Конфигурация xdebug.ini

# /etc/php.d/15-xdebug.ini  (или добавить в php.ini)

[xdebug]
zend_extension=xdebug.so

; Xdebug 3.x (актуальный синтаксис)
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=192.168.1.100  ; IP вашего рабочего компьютера
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.log
xdebug.idekey=PHPSTORM
# Перезапускаем PHP-FPM
systemctl restart php-fpm

Настройка PhpStorm

  1. Откройте Settings → PHP → Debug
  2. Убедитесь, что порт 9003 (Xdebug 3) совпадает с настройкой на сервере
  3. Перейдите в Settings → PHP → Servers
  4. Добавьте сервер: укажите хост (например, mysite.local), порт 80
  5. Включите Path Mappings: /home/bitrix/www → ваша локальная папка проекта

Запуск отладки

  1. Нажмите иконку телефона в PhpStorm — Start Listening for PHP Debug Connections
  2. Поставьте точку останова (кликните на номер строки)
  3. Откройте страницу в браузере с параметром ?XDEBUG_SESSION_START=PHPSTORM
  4. PhpStorm остановит выполнение на точке останова

Расширение для браузера

Установите Xdebug Helper для Chrome или Firefox. Оно автоматически добавляет cookie XDEBUG_SESSION и избавляет от необходимости каждый раз добавлять параметр в URL.

Отладка CLI-скриптов (агенты, cron)

export XDEBUG_SESSION=PHPSTORM
php -f /home/bitrix/www/local/tools/my_script.php

Профилирование производительности

; Включить профилировщик
xdebug.mode=profile
xdebug.output_dir=/tmp/xdebug_profiles
xdebug.profiler_output_name=cachegrind.out.%p

Файл профиля открывается в PhpStorm → Tools → Analyze Xdebug Profiler Snapshot или в QCacheGrind/KCacheGrind.

Отладка AJAX-запросов в Битрикс

AJAX-запросы обычно идут на /bitrix/services/main/ajax.php. Чтобы перехватить их:

  1. Убедитесь, что расширение Xdebug Helper активно в браузере
  2. Откройте DevTools → Network
  3. Выполните действие, которое вызывает AJAX
  4. PhpStorm автоматически перехватит запрос, если точка останова стоит в обработчике

Отключение Xdebug на production

Xdebug значительно замедляет PHP. На боевом сервере отключайте его:

# Переименовываем конфиг, чтобы не загружался
mv /etc/php.d/15-xdebug.ini /etc/php.d/15-xdebug.ini.disabled
systemctl restart php-fpm

Итог

После настройки отладка в PhpStorm полностью заменяет var_dump и логи: видны все переменные, стек вызовов, можно выполнять код построчно. Особенно полезно для отладки сложных компонентов Битрикс и AJAX-обработчиков.

Вам также может понравиться...