\Bitrix\Main\Diag\Debug — класс для проведения отладки ajax-запросов, крон-файлов и решения других подобных задач (с версии 12.0.7)

В современной версии фреймворка 1С-Битрикс (D7) для отладки существует специальный класс \Bitrix\Main\Diag\Debug. Он помогает выводить данные в удобном формате, сохранять их в файлы журнала, а также проводить замеры времени выполнения функций и методов. Подобный функционал особенно полезен при отладке AJAX-запросов, крон-файлов и других технических задач, где стандартные средства вывода могут быть недоступны или неудобны.

В этой статье рассмотрим:

1. Коротко об аналогах в старом ядре (AddMessage2Log и mydump).
2. Расположение и основные методы класса Debug.
3. Примеры использования для вывода, сохранения данных и измерения времени выполнения.

1. Аналоги в старом ядре

AddMessage2Log

Это классический метод в «старом» ядре Битрикс для записи отладочной информации в лог-файл. Его вызов выглядит так:

AddMessage2Log("Сообщение", "Модуль");

• Принимает строку, которую необходимо записать, и название модуля для идентификации источника.
• Автоматически пишет данные в /bitrix/php_interface/dbconn.php или в файл, указанный в настройках, обычно bitrix/logs/.

mydump

Другой популярный среди разработчиков «метод» (или функция) для вывода массива или объекта в читаемом виде (используя print_r или var_dump), обёрнутом в удобный формат HTML. Преимущество — наглядный вывод структуры данных. Недостаток — при работе с AJAX или cron вывод в браузер может быть невидим, если нет прямого вывода в веб-интерфейс.

2. Класс Debug в D7

В новом ядре на базе D7 для подобных задач рекомендуется использовать класс \Bitrix\Main\Diag\Debug. Физически он находится в файле:

bitrix/modules/main/lib/diag/debug.php

Основные возможности:

1. Методы для вывода на экран (dump) с использованием var_dump.
2. Методы для записи в файл (writeToFile, dumpToFile) с использованием print_r или var_dump.
3. Методы для замера времени (startTimeLabel, endTimeLabel, getTimeLabels).

Таким образом, Debug объединяет и улучшает функциональность старых аналогов.

2.1 dump($var, $varName = "", $return = false)

• Использует PHP-функцию var_dump для отображения структуры переменной.
• Если передать третий параметр $return = true, то метод вернёт результат в виде строки, а не выведет напрямую.
• Параметр $varName можно использовать для именования переменной при выводе.

Пример использования:

use Bitrix\Main\Diag\Debug;

// Вывод содержимого глобального массива $_SERVER
Debug::dump($_SERVER);

// С указанием названия переменной
Debug::dump($_SERVER, "Global Server Array");

Если хочется получить вывод в виде строки (например, чтобы дополнительно обработать или сохранить), достаточно:

$stringDump = Debug::dump($_SERVER, "Server Dump", true);
// Теперь $stringDump содержит форматированный результат

2.2 dumpToFile($var, $varName = "", $fileName = "")

• Делает то же, что и dump, но записывает результат в файл.
• По умолчанию имя файла — __bx_log.log, который сохраняется в корне сайта ($_SERVER["DOCUMENT_ROOT"]).

Пример использования:

use Bitrix\Main\Diag\Debug;

// Запишет структуру $_SERVER в файл /__bx_log.log
Debug::dumpToFile($_SERVER, "Server Dump");

Можно передать собственное имя файла:

Debug::dumpToFile($_SERVER, "Server Dump", "custom_log.txt");

В результате будет записан форматированный вывод var_dump в файл custom_log.txt.

2.3 writeToFile($var, $varName = "", $fileName = "")

• В отличие от dumpToFile, метод writeToFile использует print_r.
• Подходит для случаев, когда нужно записать «читаемый» вид массива, строки или объекта в лог без HTML-разметки или «сложного» формата от var_dump.

Пример использования:

use Bitrix\Main\Diag\Debug;

// Запишет массив $_SERVER, используя print_r
Debug::writeToFile($_SERVER, "Server Array");

2.4 Измерение времени выполнения: startTimeLabel, endTimeLabel, getTimeLabels

Эти методы помогают отследить, сколько времени заняла конкретная операция или участок кода. В корне схоже с «таймерами»:

1. startTimeLabel($name) — ставит метку начала с уникальным именем.
2. endTimeLabel($name) — закрывает метку и подсчитывает разницу во времени от соответствующего startTimeLabel.
3. getTimeLabels() — возвращает массив всех временных меток и накопленную информацию о длительности.

Пример использования:

use Bitrix\Main\Diag\Debug;

// Замеряем время выполнения функции foo()
Debug::startTimeLabel("foo");
foo();
Debug::endTimeLabel("foo");

// Замеряем время выполнения функции bar()
Debug::startTimeLabel("bar");
bar();
Debug::endTimeLabel("bar");

// Вывод результатов
print_r(Debug::getTimeLabels());

В результате мы получим массив, где для каждой метки (foo, bar) будет записано, сколько времени занял соответствующий участок кода.

3. Примеры и рекомендации

1. Отладка AJAX-запросов

   В AJAX-обработчике (PHP-скрипте), где вывод напрямую в браузер может быть неудобным, логичнее писать в файл. Пример:

   use Bitrix\Main\Diag\Debug;
   
   // Код внутри ajax_handler.php
   Debug::writeToFile($_REQUEST, "AJAX Request");
   // ...

   После выполнения AJAX-запроса данные окажутся в файле __bx_log.log.

2. Отладка в cron

   Аналогично, при запуске задач по cron не отображается стандартный вывод PHP в консоли или браузере (зависит от настроек), поэтому для анализа состояния проще вести лог:

   use Bitrix\Main\Diag\Debug;
   
   // Пример кода в cron-файле
   Debug::dumpToFile($_ENV, "Environment in cron", "cron_log.txt");

   Далее можно посмотреть файл cron_log.txt для анализа.

3. Вывод во время разработки

   При локальной разработке иногда бывает удобнее сразу видеть результат на экране. Тогда используем Debug::dump($myArray);.

Заключение

Класс \Bitrix\Main\Diag\Debug — полноценное решение для отладки в ядре D7. Он объединяет функциональность старых методов (AddMessage2Log, mydump) и добавляет новые возможности — замеры времени, запись через var_dump или print_r. Особенно полезен в ситуациях, когда важно не нарушать логику веб-страниц и не выводить отладочную информацию «вслепую». Настройки и записи в файлы обеспечивают удобство и безопасность: можно быстро проверить логи после выполнения нужных действий, не показывая внутренние данные конечному пользователю.