AddMessage2Log и Xdebug — отладка в Битрикс

Отладка на боевом сервере, где нельзя просто остановить выполнение в точке останова, требует своих инструментов. Разберём AddMessage2Log — штатный способ логирования Битрикса — и настройку Xdebug для полноценной пошаговой отладки на локальном окружении.

Базовое использование AddMessage2Log

<?php

AddMessage2Log('Начало обработки заказа #' . $orderId, 'my.module');
AddMessage2Log(['ORDER_ID' => $orderId, 'SUM' => $sum], 'my.module');

Второй параметр — модуль или произвольная метка, по которой удобно фильтровать записи при просмотре. Функция принимает не только строку, но и массив — он будет сериализован автоматически, что удобно для логирования структурированных данных без ручного print_r.

Просмотр журнала событий

Записанные сообщения видны в разделе Настройки → Инструменты разработчика → Журнал событий, но только если в настройках главного модуля включён соответствующий уровень логирования (LOG_FILTER и минимальный уровень серьёзности). Частая причина, почему «AddMessage2Log ничего не пишет», — логирование выключено или установлен уровень серьёзности, отсекающий обычные сообщения.

Указание уровня серьёзности

<?php

AddMessage2Log('Некритичная информация', 'my.module', 1);   // информация
AddMessage2Log('Подозрительная ситуация', 'my.module', 2);  // предупреждение
AddMessage2Log('Ошибка обработки', 'my.module', 3);         // ошибка

Быстрая отладка через временный вывод в файл

<?php

file_put_contents(
    $_SERVER['DOCUMENT_ROOT'] . '/upload/debug.log',
    date('Y-m-d H:i:s') . ' ' . print_r($data, true) . "\n",
    FILE_APPEND
);

Для разовой отладки прямой файл проще журнала событий — но такие файлы обязательно удалять после отладки, а не оставлять в upload/, где они и накапливаются, и потенциально доступны по прямой ссылке при неверных правах доступа.

Настройка Xdebug для пошаговой отладки

Для полноценной отладки с точками останова на локальном окружении (Docker, локальный сервер, но не боевой продакшн) используется Xdebug — расширение PHP, подключаемое к IDE. Минимальная конфигурация в php.ini:

zend_extension=xdebug.so
xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.start_with_request=yes

В IDE (PhpStorm, VS Code с расширением PHP Debug) настраивается прослушивание на том же порту (по умолчанию 9003 для Xdebug 3), после чего можно ставить точки останова прямо в компонентах и обработчиках событий Битрикса — включая штатные классы ядра, если нужно понять, что происходит внутри самого CIBlockElement или D7 ORM.

Почему Xdebug нельзя оставлять включённым на проде

Xdebug в режиме отладки заметно замедляет выполнение PHP-скриптов и создаёт сетевое подключение к отладчику при каждом запросе — на боевом сервере под реальной нагрузкой это ощутимо снижает производительность и может создать риск безопасности, если порт отладки доступен извне. Расширение либо не устанавливается на прод вовсе, либо отключается через xdebug.mode=off.

Отладка AJAX и фоновых обработчиков

Точки останова в обработчиках, вызываемых через AJAX или из агентов, требуют явной передачи отладочной сессии — либо через cookie XDEBUG_SESSION, либо через принудительный запуск xdebug.start_with_request=yes, иначе IDE не получит сигнал о начале отладочной сессии для запроса, инициированного не напрямую из браузера с активным расширением.

Частые ошибки

• AddMessage2Log не пишет из-за выключенного логирования. Проверка настроек главного модуля перед поиском проблемы в коде.
• Забытые файлы отладки в upload/. Остаются доступными по прямой ссылке после завершения отладки.
• Xdebug включён на боевом сервере. Заметное падение производительности под реальной нагрузкой.
• Точка останова не срабатывает в AJAX-обработчике. Не передана отладочная сессия для запроса не из браузера напрямую.

Итог

Для быстрой диагностики на любом окружении, включая прод, подходит AddMessage2Log с проверкой, что логирование включено в настройках главного модуля. Для глубокой отладки логики — Xdebug на локальном окружении, который ни при каких условиях не должен оставаться включённым на боевом сервере.