Инклюд файлов в 1С‑Битрикс: компонент main.include, параметры и подключение модулей

Зачем отдельный include в Битрикс

Чтобы не смешивать огромную простыню в одном шаблоне страницы, удобно вынести повторяющийся блок в файл и подключать его компонентом bitrix:main.include. Ядро само следит за кодировкой, кешированием включаемых областей (в режиме «редактируемый блок») и единым стилем вызова из шаблонов и композитных страниц.

Подключение файла по пути от корня сайта

Вызов выполняют через глобальный объект приложения $APPLICATION. Путь к PHP‑файлу задаётся от корня документа — например файл лежит в активном шаблоне сайта под /local/templates/catalog_theme/includes/promo_strip.php (название шаблона замените на своё).

global $APPLICATION;

$APPLICATION->IncludeComponent(
    'bitrix:main.include',
    '',
    [
        'AREA_FILE_SHOW' => 'file',
        'PATH' => '/local/templates/catalog_theme/includes/promo_strip.php',
        'EDIT_TEMPLATE' => '',
    ],
    false,
    ['HIDE_ICONS' => 'Y']
);

Ключ AREA_FILE_SHOW со значением file означает: не искать сохранённые в БД включаемые области, а просто выполнить указанный файл. Режимы с текстом из инфоблока или «общей» областью включаются другими значениями — их выбирают, когда нужна правка содержимого из административной части без деплоя кода.

Как передать переменные во включаемый файл

Во включаемом скрипте доступен массив параметров компонента — его обычно называют $arParams в документации шаблонов. Дополнительные элементы второго массива настроек пробрасываются внутрь этого контекста. Например, из родительского компонента можно передать слайдеру подготовленный массив кадров:

$APPLICATION->IncludeComponent(
    'bitrix:main.include',
    '',
    [
        'AREA_FILE_SHOW' => 'file',
        'PATH' => '/local/templates/catalog_theme/includes/hero_slider.php',
        'EDIT_TEMPLATE' => '',
        'SLIDE_LIST' => $arResult['BANNER_SLIDES'],
    ]
);

// hero_slider.php:
// var_dump($arParams['SLIDE_LIST']);

Практический совет: имена параметров держите в одном стиле (верхний регистр для «внешних» ключей или наоборот — как принято в вашем шаблоне), чтобы не путаться при рефакторинге. Если нужно передать несколько крупных структур и не хочется раздувать $arParams, иногда оставляют явное заполнение $GLOBALS['myCtx'] перед include — подход рабочий, но хуже читается; предпочтительнее осмысленные ключи в параметрах компонента.

Подключение модулей перед вызовами API

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

use Bitrix\Main\Loader;

if (!Loader::includeModule('iblock')) {
    return;
}

// дальше — CIBlockElement, ORM и т.д.

На старых проектах встречают CModule::IncludeModule('iblock'); для нового кода ядро рекомендует Loader::includeModule с явной проверкой результата. Без успешного подключения последующие вызовы API модуля приведут к ошибкам времени выполнения.

На что смотреть в продакшене

• Путь PATH проверяйте на существование файла в CI и на стендах; опечатка в сегменте шаблона даёт пустой вывод без явной ошибки в веб‑режиме.
• Не кладите во включаемые файлы тяжёлые запросы без кеша, если блок отображается на каждой странице витрины.
• Для редактируемых из админки областей выбирайте соответствующий AREA_FILE_SHOW, а не «голый» файл — иначе контент‑менеджеры потеряют привычный интерфейс правок.

Такой набор приёмов закрывает типичный сценарий: вынести вёрстку и логику в отдельные файлы, аккуратно передать данные и не забыть о модулях ядра перед работой с сущностями Битрикс.