Как внедрить Kint в Bitrix безопасно и не уронить прод

В Bitrix отладка часто превращается в русскую рулетку: вставил var_dump($arResult); die;, забыл убрать — и на прод уехала «простыня» в середине страницы или сломанный JSON в AJAX. Kint — это читаемый дамп переменных без хаоса в выводе, но только если его правильно подключить и ограничить. Ниже — пошаговый практический гайд: установка (с Composer и без), безопасное включение через init.php, ограничение по IP, отключение на проде, как не сломать composite и что делать с AJAX. Плюс реальные кейсы: отладка ORM DataManager, разбор $arResult и почему var_dump в Bitrix — плохая идея.

---

Почему var_dump в Bitrix — плохая идея

Перед тем как переходить на Kint, стоит чётко понимать, чем опасен привычный «дебаг» через var_dump и print_r.

1. Забыл убрать — утекло на прод. В шаблоне компонента или в обработчике один раз оставил var_dump(); die; — на проде пользователь видит сырой вывод типов и структур или пустую страницу. Поисковики индексируют мусор, клиент видит «сломанный сайт».

2. Вывод нечитаемый. В Bitrix типичны огромные $arResult, объекты ORM, вложенные массивы из D7. var_dump() даёт многостраничный текст без свёрток, без поиска — найти нужное поле тяжело.

3. Ломает HTML и JSON. Всё, что выводится до die, попадает в ответ. Если дамп идёт в середине страницы — ломается вёрстка, скрипты, данные в data-*. Если дамп в AJAX/API — ответ перестаёт быть валидным JSON, фронт падает с ошибкой парсинга.

4. Нет контроля «кто видит». На проде любой запрос (в том числе от поискового робота или постороннего) получит тот же вывод, если код с дампом выполнился.

Kint решает читаемость (свёртки, подсветка, поиск по структуре) и позволяет централизованно включать отладку только для своих IP и отключать на проде — об этом дальше.

---

Установка Kint: через Composer и без Composer

Ставим в /local, чтобы не трогать ядро Bitrix.

Вариант 1: установка через Composer (рекомендуется)

Если на сервере или локально есть Composer:

cd /path/to/site/local
composer require kint-php/kint --dev

Пакет появится в local/vendor/kint-php/kint. Autoload подключаем из local/vendor/autoload.php (см. раздел про init.php).

Плюсы: обновления через composer update, зависимостей минимум. На проде можно не ставить dev-зависимости (composer install --no-dev), тогда Kint вообще не попадёт в деплой — но тогда нужно подключать его условно, чтобы не было фатала при отсутствии класса.

Вариант 2: установка без Composer (ручная)

Подходит, когда Composer на хостинге недоступен или проект без Composer.

1. Скачай архив с GitHub Releases (актуальная версия, например kint-5.x.zip).
2. Распакуй в каталог, например: /local/vendor/kint-php/kint/ (структура должна быть такой, чтобы внутри лежал src/Kint.php и автозагрузка Kint).
3. В init.php подключи Kint вручную, до любых вызовов d() или dd():

<?php
// Подключение Kint без Composer
$kintPath = $_SERVER['DOCUMENT_ROOT'] . '/local/vendor/kint-php/kint/src/';
if (is_dir($kintPath)) {
    require_once $kintPath . 'Kint.php';
    require_once $kintPath . 'Renderer/RichRenderer.php';
    require_once $kintPath . 'Parser.php';
    // При необходимости подключи остальные файлы из src/ по мере использования
}

У современных версий Kint (5.x) структура может отличаться — проверь наличие Kint.php и при необходимости подключай через один главный файл, если он подтягивает остальное. Цель — чтобы класс Kint и функции d(), dd() были доступны.

---

Подключение через init.php и «рубильник»

Вся логика включения/выключения Kint имеет смысл в одном месте — в /local/php_interface/init.php. Так не будет разбросанных проверок по шаблонам и компонентам.

1) Подключаем autoload (Composer) или Kint вручную

Если ставили через Composer:

<?php
require_once $_SERVER['DOCUMENT_ROOT'] . '/local/vendor/autoload.php';

Если без Composer — используй блок из предыдущего раздела (подключение папки kint-php/kint/src/).

2) Включаем Kint только когда безопасно

Сразу после подключения задаём условие: когда Kint реально работает (пишет в вывод).

• Не в продакшене (по окружению или по флагу Bitrix).
• Или только для своих IP (офис, дом, VPN).

Пример «рубильника» в init.php:

<?php
require_once $_SERVER['DOCUMENT_ROOT'] . '/local/vendor/autoload.php';

use Bitrix\Main\Config\Option;

// Признак «установка для разработки» в Bitrix
$isDevInstall = (Option::get('main', 'update_devsrv', 'N') === 'Y');

// Разрешённые IP (добавь свои)
$allowedIps = ['127.0.0.1', '::1', '192.168.1.100', '10.0.0.1'];
$currentIp = $_SERVER['REMOTE_ADDR'] ?? '';
$isAllowedIp = in_array($currentIp, $allowedIps, true);

// Включаем Kint только на dev или с разрешённого IP
$kintEnabled = $isDevInstall || $isAllowedIp;

if (class_exists('Kint', false)) {
    \Kint::$enabled_mode = $kintEnabled;
}

Так Kint будет что-то выводить только при dev-установке или при запросе с твоего IP. На проде при $kintEnabled = false вызовы d()/dd() не выводят данные (режим отключён).

---

Ограничение по IP: зачем и как

Зачем: даже на тестовом стенде не всегда хочется, чтобы любой человек по ссылке видел дампы. Ограничение по IP уменьшает риск утечки отладочной информации.

Как: список разрешённых IP задаётся в одном месте (как в примере выше — массив $allowedIps). Можно вынести в константу или конфиг:

// В init.php или в подключаемом config
define('KINT_ALLOWED_IPS', '127.0.0.1,::1,192.168.1.100');
$allowedIps = array_map('trim', explode(',', KINT_ALLOWED_IPS));
$isAllowedIp = in_array($currentIp, $allowedIps, true);

Важно: проверка по $_SERVER['REMOTE_ADDR'] имеет смысл только для обычных HTTP-запросов. Для cron, агентов и CLI IP нет — там лучше вообще не включать Kint или включать только по флагу окружения (например, переменная окружения BITRIX_DEBUG=1).

---

Отключение в продакшене

На проде Kint должен быть либо выключен, либо физически отсутствовать.

Вариант A: оставить код, выключить режим.
Уже сделано в примере выше: на проде $isDevInstall обычно false, и если твой IP не в списке — $kintEnabled = false. Тогда d() и dd() не выводят ничего. Вызовы в коде можно не удалять — они станут no-op.

Вариант B: не подключать Kint на проде.
В init.php оборачиваем подключение и рубильник в проверку окружения:

$isProduction = (getenv('APP_ENV') === 'production' || !$isDevInstall);
if (!$isProduction) {
    require_once $_SERVER['DOCUMENT_ROOT'] . '/local/vendor/autoload.php';
    // ... рубильник по IP и Kint::$enabled_mode
}

Тогда на проде класс Kint может быть не объявлен — все вызовы d() дадут фатал. Поэтому либо не вызывать d() на проде вообще (удалять перед коммитом/деплоем), либо определить заглушки:

if (!function_exists('d')) {
    function d() {}
}
if (!function_exists('dd')) {
    function dd() { exit; }
}

Лучшая практика: рубильник по флагу + IP, оставить подключение Kint на проде, но Kint::$enabled_mode = false — так код с d() не падает и ничего не выводит.

---

Как не сломать composite (композитный режим)

В Bitrix композитный режим (composite) кэширует полную HTML-страницу. Если в момент генерации страницы Kint выводит свой HTML (панель, дамп) в тело ответа, произойдёт одно из двух:

• В кэш попадёт страница с отладочным выводом — и все пользователи (в том числе с продовых IP) увидят дампы до сброса кэша.
• Разметка страницы сломается (лишние блоки, незакрытые теги) — некорректный HTML, падение скриптов.

Что делать:

1. Не дампить в шаблонах и компонентах, которые участвуют в составной странице, без проверки «сейчас не composite». Или вообще не оставлять d() в шаблонах на постоянной основе — только локально, с последующим удалением.
2. Включать Kint только для своих IP (как выше). Тогда даже если кэш однажды соберётся с дампом, обычные пользователи с других IP не попадут в этот сценарий при правильной настройке (но кэш лучше не засорять).
3. При отладке страницы с composite временно отключать композит для себя (например, через куку или параметр) или смотреть дамп в отдельном скрипте/странице, а не в общем потоке вывода.

Итог: Kint и composite совместимы только если Kint не выводит ничего на проде и для обычных пользователей (рубильник по IP + отключение на проде), и ты не кэшируешь страницы с вызовом d() в цепочке.

---

Ошибки при использовании в AJAX

Kint по умолчанию пишет в stdout (в ответ). В AJAX-обработчике ответ обычно ожидается как JSON. Если в середине выполнения вызвать d($data);, в ответ попадёт HTML/текст от Kint, и JSON станет невалидным — на фронте получишь ошибку парсинга или пустые данные.

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

• Вызвать d() или dd() в ajax_action и забыть — клиент получает не JSON.
• Вызвать dd() — выполнение прервётся, до echo json_encode(...) дело не дойдёт.

Что делать:

1. Не вызывать Kint в AJAX-обработчиках в проде и на общих стендах. Либо вызывать только когда это не AJAX:

use Bitrix\Main\Application;

$request = Application::getInstance()->getContext()->getRequest();
if (!$request->isAjaxRequest()) {
    d($data);
}

2. Для отладки AJAX логировать в файл или смотреть вывод в отдельном тестовом endpoint’е (без JSON). Либо временно отключать отправку JSON и смотреть «сырой» ответ в браузере только со своей машины.

Так ты не сломаешь ответ и не заставишь фронт падать из-за битого JSON.

---

Реальные кейсы использования

Кейс 1: отладка ORM DataManager (getList, фильтр, выборка)

Часто нужно понять: что реально вернул getList(), правильный ли фильтр и какие поля пришли.

use Bitrix\Main\UserTable;

$rows = UserTable::getList([
    'select' => ['ID', 'LOGIN', 'EMAIL', 'ACTIVE'],
    'filter' => ['=ACTIVE' => 'Y'],
    'limit'  => 5,
    'order'  => ['ID' => 'DESC'],
])->fetchAll();

d($rows);

В Kint сразу видно структуру каждой записи. Если «ничего не находит» — проверь имена полей и операторы в filter, смотри результат getList() через d() в том же запросе.

Для сложных сущностей (Sale, CRM) дамп объекта после getById/load помогает увидеть поля и вложенные коллекции:

use Bitrix\Sale\Order;

$order = Order::load($orderId);
d([
    'STATUS_ID' => $order->getField('STATUS_ID'),
    'getFieldValues' => $order->getFieldValues(),
]);

Кейс 2: отладка массива $arResult (компоненты каталога, списки, фильтры)

Типичная боль: «почему не выводится список/фильтр/пагинация». Часто причина — не та структура $arResult (другие ключи, вложенность, пустой массив).

В шаблоне компонента:

// template.php
d([
    'PARAMS'   => $arParams,
    'RESULT_KEYS' => array_keys($arResult),
    'ITEMS'    => $arResult['ITEMS'] ?? 'no ITEMS',
    'NAV'      => $arResult['NAV_STRING'] ?? 'no NAV',
]);

Сразу видно: какие ключи есть, что в ITEMS, есть ли пагинация. Без Kint пришлось бы десятки раз делать print_r($arResult) и скроллить огромный вывод.

Кейс 3: Request (GET/POST, AJAX)

Чтобы не гадать, что пришло в запросе и не перепутать GET с POST:

use Bitrix\Main\Application;

$request = Application::getInstance()->getContext()->getRequest();
d([
    'method' => $request->getRequestMethod(),
    'isAjax' => $request->isAjaxRequest(),
    'get'    => $request->getQueryList()->toArray(),
    'post'   => $request->getPostList()->toArray(),
]);

Удобно при отладке форм, фильтров и AJAX-действий.

Кейс 4: события — кто вызвал и что передал

В обработчиках событий бывает непонятно, откуда вызов и что в $event:

AddEventHandler('sale', 'OnSaleOrderSaved', function($event) {
    d([
        'eventClass' => is_object($event) ? get_class($event) : gettype($event),
        'backtrace'  => debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 10),
    ]);
});

По стеку видно цепочку вызовов — удобно, когда обработчик срабатывает «не там» или дважды.

---

Краткий чеклист перед продом

• Kint включается только по флагу dev и/или по списку IP.
• На проде Kint::$enabled_mode = false или Kint не подключается.
• В AJAX-обработчиках нет вызовов d()/dd() без проверки !$request->isAjaxRequest().
• В шаблонах и компонентах, участвующих в composite, не оставляешь постоянных дампов; после отладки вызовы убраны.
• В коде нет «забытых» var_dump/print_r/die — заменены на Kint с рубильником или удалены.

---

Итог

Kint в Bitrix даёт нормальную отладку без «простыней» var_dump и без риска случайно уронить прод, если:

• ставишь его в /local (Composer или вручную);
• подключаешь в init.php и включаешь только при dev-установке и/или по IP;
• на проде не выводишь ничего (рубильник);
• не дампишь в AJAX-ответ и не кэшируешь страницы с дампом в composite.

Плюс реальные кейсы — ORM DataManager, $arResult, Request и события — закрывают большую часть ежедневных отладочных задач Bitrix-разработчика без боли и без утечек на прод.

---

Ссылки

• Kint на GitHub — репозиторий и релизы
• Официальный сайт Kint — документация
• Kint на Packagist — установка через Composer
• Bitrix D7: Option::get() — проверка опции «установка для разработки»