Что такое $arParams и $arResult в компонентах 1С-Битрикс и как с ними работать

При создании собственных компонентов в 1С-Битрикс важно понимать, как правильно использовать две основные переменные: $arParams и $arResult. Именно они позволяют передавать параметры при вызове компонента и возвращать результат выполнения в шаблон. В данной статье мы подробно разберём назначение этих переменных, их особенности, а также рассмотрим различные способы изменения $arResult, в том числе через файл result_modifier.php.

1. Основная роль $arParams

Переменная $arParams содержит входные параметры вашего компонента. Когда вы подключаете компонент, в его вызове указываются настройки, которые и попадают в $arParams. Например, вы можете передать заголовок, идентификатор элемента, количество выводимых записей и т.д.

Основные особенности:

1. Автоматическое экранирование
   Перед тем как значения попадут в $arParams, к ним применяется функция htmlspecialcharsEx(). Это важно для безопасности и предотвращения XSS-атак. К примеру, если посетитель попытается передать HTML-теги или вредоносный скрипт, они будут экранированы.
2. Сохранение исходных значений
   Параллельно с экранированной версией сохраняется и исходная (необработанная) версия параметра. И если $arParams["NAME"] — экранированное значение, то $arParams["~NAME"] — исходное. Это особенно полезно, если вам нужно работать с «сырым» HTML.
3. Приведение к нужному типу
   В начале кода компонента рекомендуется делать валидацию и приведение типов параметров. Например, если параметр должен быть целым числом, используйте intval(). Такая проверка гарантирует корректность данных при их дальнейшем использовании.
4. Отражение изменений
   $arParams — это псевдоним (ссылка) на член класса компонента. Следовательно, все изменения, которые вы производите в $arParams, станут доступны и в шаблоне, и во всех других частях компонента.

Пример настройки $arParams в начале компонента:

// Убеждаемся, что TITLE определён, и приводим к строке
if (!isset($arParams["TITLE"]) || $arParams["TITLE"] === '') {
    $arParams["TITLE"] = "Заголовок по умолчанию";
} else {
    // Экранируем потенциально опасные символы
    $arParams["TITLE"] = htmlspecialcharsEx($arParams["TITLE"]);
}

// Приводим числовой параметр к целому числу
$arParams["ITEMS_COUNT"] = intval($arParams["ITEMS_COUNT"]);

// При необходимости используем исходное значение
$arResult["RAW_TITLE"] = $arParams["~TITLE"];
        

2. Основная роль $arResult

Если $arParams отвечает за «вход», то $arResult — за «выход». Это массив, в который компонент складывает результаты своей работы перед тем, как передать их в шаблон. Например, в $arResult могут лежать данные, полученные из БД, вычисленные значения или что угодно ещё, что нужно отобразить.

Основные особенности:

1. Инициализация
   По умолчанию переменная $arResult инициализируется как пустой массив:

   $arResult = array();

   Обычно это делается в самом начале компонента, чтобы затем «наполнять» $arResult данными по мере выполнения бизнес-логики.
2. Передача данных в шаблон
   Подключение шаблона происходит через $this->IncludeComponentTemplate(). При этом движок 1С-Битрикс автоматически передаёт $arResult в файл template.php. Вам не нужно вручную что-то «пробрасывать» — главное, чтобы данные уже находились в $arResult.
3. Привязка к члену класса
   Как и $arParams, $arResult связан с внутренней логикой класса компонента. Если вы меняете $arResult в коде компонента, эти изменения немедленно становятся доступны в шаблоне и в других вспомогательных файлах, например в result_modifier.php.

Пример формирования $arResult:

$arResult["ITEMS"] = array(); // Подготовим массив
// Допустим, у нас есть результат выборки из БД
$dbRes = CIBlockElement::GetList(
    array(),
    array("IBLOCK_ID" => $arParams["IBLOCK_ID"]),
    false,
    array("nTopCount" => $arParams["ITEMS_COUNT"]),
    array("ID", "NAME", "DETAIL_PAGE_URL")
);

while ($arItem = $dbRes->Fetch()) {
    $arResult["ITEMS"][] = $arItem;
}

// Внесём какую-то дополнительную информацию
$arResult["TITLE"] = $arParams["TITLE"];

// Подключаем шаблон
$this->IncludeComponentTemplate();
        

В файле template.php вы можете вывести эти данные, используя $arResult["ITEMS"] и $arResult["TITLE"].

3. Роль result_modifier.php и примеры изменения $arResult

Для более тонкой настройки результата компонента 1С-Битрикс предлагает файл result_modifier.php. Он находится в папке шаблона компонента, рядом с template.php, и загружается после выполнения основного кода компонента (где формируется $arResult), но до подключения template.php.

Таким образом, result_modifier.php позволяет модифицировать содержимое $arResult перед тем, как оно окончательно попадёт в шаблон.

Как это работает

1. Компонент выполняется и формирует $arResult.
2. Подключается result_modifier.php. Здесь можно внести изменения в $arResult.
3. После этого загружается шаблон template.php, который уже получает финальный вариант $arResult.

Пример result_modifier.php

Допустим, в процессе работы компонента мы записали в $arResult["ITEMS"] массив элементов из инфоблока. В result_modifier.php мы можем добавить к каждому элементу новую информацию, либо изменить уже существующие данные.

<?php
if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED !== true) {
    die();
}

// Добавим к каждому элементу кастомное поле
if (!empty($arResult["ITEMS"]) && is_array($arResult["ITEMS"])) {
    foreach ($arResult["ITEMS"] as &$item) {
        // Добавим поле для дополнительной информации
        $item["CUSTOM_FIELD"] = "Дополнительные данные";
    }
    unset($item); // разрываем ссылку, чтобы не было проблем в будущем
}

// Можно создать новое поле вне цикла
$arResult["MODIFIER_INFO"] = "Информация, добавленная в result_modifier.php";
        

Таким образом, когда шаблон template.php будет подключаться, в $arResult["ITEMS"] уже появится новое поле CUSTOM_FIELD, а также будет доступно поле MODIFIER_INFO.

Зачем это нужно

• Разделение логики: часть общей бизнес-логики мы оставляем в самом компоненте (например, выборку данных из БД), а все «тонкие» или косметические изменения выносим в result_modifier.php.
• Удобство переиспользования шаблонов: вы можете иметь несколько шаблонов для одного компонента, и в каждом своя логика постобработки результатов.
• Расширяемость: можно гибко подстраивать массив $arResult под разные задачи, не переписывая логику самого компонента.

4. Использование ссылок (references) в PHP

В PHP ссылка (reference) даёт возможность обращаться к одним и тем же данным под разными именами переменных. В контексте 1С-Битрикс это означает, что $arParams и $arResult «привязаны» к объекту компонента. Однако если вы явно переопределите одну из переменных ссылкой на другой массив, связь с компонентом будет потеряна:

// Пример неправильного использования:
// полностью переназначаем $arParams, теперь он ссылается на $newArray,
// и изменения не попадут в шаблон компонента
$arParams = &$newArray;
        

Также, если вы удалите переменную через unset($arParams), то связь между $arParams и компонентом будет разорвана:

// Разрыв связи
unset($arParams);
        

Будьте осторожны с подобными приёмами, чтобы не нарушить работу компонента.

5. Обобщённый пример структуры компонента

Ниже приведён упрощённый пример, показывающий, в какой момент мы работаем с $arParams и $arResult, а также как взаимодействует result_modifier.php.

/local/components/namespace/my_component/
|-- .parameters.php
|-- .description.php
|-- class.php (или component.php)
|-- templates
    |-- .default
        |-- result_modifier.php
        |-- template.php
        

1. .parameters.php
   Описывает настройки (параметры) компонента, которые будут доступны при его вызове.
2. class.php (или component.php)
   Содержит основную логику:
   • Проверка и приведение входных параметров ($arParams).
   • Формирование массива $arResult (результат работы).
   • Вызов $this->IncludeComponentTemplate() для подключения шаблона.
3. templates/.default/result_modifier.php
   
   • Дополнительная обработка результата перед его выводом.
   • Изменение $arResult, добавление новых полей, фильтрация данных и т.д.
4. templates/.default/template.php
   
   • Финальный вывод (HTML + PHP), где вы используете $arResult для отображения информации.

6. Заключение

• $arParams отвечает за входные параметры и безопасность: экранирование значений, приведение типов, проверку корректности.
• $arResult формируется в процессе работы компонента и передаётся в шаблон, где отображается пользователю.
• result_modifier.php — мощный инструмент для «допиливания» и преобразования $arResult уже после выполнения основной логики компонента, но до отображения шаблона.
• Система ссылок (references) в PHP делает $arParams и $arResult «живыми»: их изменение в одном месте отражается в другом. При этом нужно аккуратно подходить к переназначению или удалению этих переменных, чтобы не потерять связь с объектом компонента.

Понимание и грамотное использование $arParams, $arResult и механизма result_modifier.php помогают выстраивать более гибкую, понятную и поддерживаемую архитектуру компонентов 1С-Битрикс. Берегите разделение логики, следите за безопасностью входных данных и используйте все возможности фреймворка по максимуму!