Без рубрики

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

07.03.2026

Отладка через var_dump и логи на проекте Битрикс быстро упирается в агенты, события и чужой код ядра. Xdebug 3 + PhpStorm дают точки останова, стек и значения переменных. Ниже — рабочий минимум для BitrixVM/Linux и типичные грабли с портами, path mapping и CLI.

Установка Xdebug 3

# версия PHP должна совпасть с той, что крутит сайт (php-fpm)
php -v

# BitrixVM / RHEL-подобные
yum install -y php-xdebug
# либо
pecl install xdebug

php -m | grep -i xdebug

Если php -m в CLI показывает xdebug, а сайт — нет, смотрите отдельный ini у php-fpm. На BitrixVM часто разные пулы/конфиги.

Конфиг xdebug.ini (Xdebug 3)

; /etc/php.d/15-xdebug.ini  (путь зависит от ОС)
[xdebug]
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.client_host=192.168.1.100
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.log
xdebug.idekey=PHPSTORM
  • client_host — IP машины с PhpStorm (не IP сервера).
  • Порт 9003 — дефолт Xdebug 3 (не 9000 от php-fpm/old Xdebug 2).
  • start_with_request=trigger безопаснее, чем yes: отладка только с cookie/флагом, меньше сюрпризов на общей VM.
systemctl restart php-fpm
# или на BitrixVM: restart apache/php через их скрипты

PhpStorm

  1. Settings → PHP → Debug: порт 9003, idekey PHPSTORM.
  2. Settings → PHP → Servers: имя хоста как в браузере (mysite.local), включить path mappings.
  3. Пример mapping: /home/bitrix/www → локальная копия проекта. Без mapping точки останова «серые» и не срабатывают.
  4. Включите Start Listening for PHP Debug Connections (иконка трубки).

Запуск из браузера

Поставьте breakpoint, откройте страницу с ?XDEBUG_SESSION_START=PHPSTORM или включите расширение Xdebug Helper (cookie XDEBUG_SESSION). PhpStorm должен поймать соединение и остановиться.

CLI: агенты, cron, php -f

export XDEBUG_SESSION=PHPSTORM
# если trigger-режим:
export XDEBUG_TRIGGER=1
php -f /home/bitrix/www/local/tools/my_script.php

Для отладки агентов Битрикс удобнее вызывать тот же PHP-код отдельным CLI-скриптом или ставить breakpoint в обработчике и инициировать событие точечно — полный прогон всех агентов шумный.

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

xdebug.mode=profile
xdebug.output_dir=/tmp/xdebug_profiles
xdebug.profiler_output_name=cachegrind.out.%p

Файлы CacheGrind открываются в PhpStorm или QCacheGrind. На бою профилировщик не оставляйте включённым постоянно: он пишет много на диск и замедляет FPM.

Типичные ошибки

  • Слушаете 9003 в IDE, а в ini остался 9000.
  • client_host=127.0.0.1 на удалённом сервере — callback идёт в себя, не на ваш ноутбук (нужен SSH tunnel или реальный IP/VPN).
  • Неверный path mapping → breakpoint не биндится.
  • Xdebug только в CLI php.ini, сайт на php-fpm без расширения.
  • start_with_request=yes на shared-стенде тормозит всех соседей.

SSH-туннель (удалённый сервер)

# на локальной машине с PhpStorm
ssh -R 9003:127.0.0.1:9003 user@bitrix-server

# в xdebug.ini на сервере
xdebug.client_host=127.0.0.1
xdebug.client_port=9003

Так сервер стучится на свой localhost:9003, а SSH пробрасывает соединение в IDE. Удобно, когда прямого IP ноутбука нет.

Вывод

Рабочая связка: Xdebug 3 на том же PHP, что php-fpm, порт 9003, trigger-режим, корректный client_host/туннель и path mapping в PhpStorm. После этого точки останова в модулях, событиях и CLI-скриптах Битрикс становятся обычным инструментом, а не лотереей с логами.

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