| Что | Класс | Задача |
|---|---|---|
| Обработчик поля | AbstractElementField | добавить в ответ своё поле, которого нет среди полей и свойств (например, images) |
| Форматер свойства | AbstractPropertyFormatter | изменить вид значения конкретного свойства (например, привязка - в {id, name, code}) |
| Событие | bik.rest:OnAfterIblockElementBuild | лёгкая правка собранного элемента перед отдачей |
Куда класть файлы
Классы - в каталог /local/bik.rest/fields/ сайта.
- namespace -
BIK\Rest\Fields; - имя файла совпадает с именем класса (
DocumentImagesField.php-class DocumentImagesField); - класс не абстрактный и наследует
AbstractElementFieldилиAbstractPropertyFormatter.
Реестр (FieldRegistry) находит классы сам и хранит их список в кеше «Справочники». После добавления или удаления файла
сохраните любой набор инфоблока или нажмите «Сбросить кеш API» (Настройки модуля -> Кеширование), иначе класс появится по истечении срока кеша.
Код, которого нет в реестре (класс удалён, опечатка), в профиле пропускается без ошибки: поле или форматер просто не работает.
Обработчик поля
Обработчик появляется чипом в группе «Обработчики» набора («Список», «Детальная», «Вложенный», «Корзина и заказ»).
Выбранный чип добавляет в ответ ключ code().
abstract class AbstractElementField
{
abstract public static function code(): string; // ключ в ответе, camelCase
abstract public static function title(): string; // подпись чипа
public static function supports(array $iblock): bool; // для каких инфоблоков доступен (по умолчанию для всех)
public static function requires(): array; // что подгрузить, даже если не выведено в ответ
abstract public function batch(array $elements, ResponseProfile $p): array;
public static function schema(): array; // схема значения для Swagger
} batch() - пакетно
batch() вызывается один раз на страницу элементов, а не на каждый элемент. Получает [ID элемента => данные], возвращает [ID элемента => значение].
Запросы к БД внутри делайте по всем элементам сразу ('ID' => array_keys($elements)), а не в цикле: иначе вернётся N+1, от которого ушёл сборщик.
В данных элемента:
- штатные поля набора и поля из
requires()['fields']по кодам (NAME,DETAIL_PICTURE- путь или ссылка на ресайз по размерам набора); PROPERTIES- свойства набора и изrequires()['properties']в формате набора. Формат «Полный»: значение лежит вVALUE; «Компактный»: само значение. Привязки к элементам раскрыты по набору «Вложенный» связанного инфоблока (или это id, если у свойства выбран вид «Только ID»);SECTION,PATH,SEO- если они есть в наборе.
Если значения нет, не возвращайте ключ (или верните null): поле у элемента не выводится.
Результат batch() хранится в кеше «Данные элементов» вместе с остальными данными элемента и сбрасывается теми же тегами: изменение элемента
или элемента, выведенного в нём (документ, бренд), обновляет и значение поля. Поэтому batch() не должен зависеть от пользователя,
сессии и времени. Пользовательские данные (избранное, цены со скидкой по группам) отдавайте через событие (ниже), а не через обработчик.
Если batch() бросит исключение, ошибка пишется в журнал, поле у этой страницы не выводится, остальной ответ не ломается.
requires() - подгрузить, но не выводить
public static function requires(): array
{
return ['fields' => ['DETAIL_PICTURE'], 'properties' => ['DOCUMENTS']];
} Сборщик загружает перечисленные поля и свойства (и раскрывает привязки по набору «Вложенный»), но в ответ они не идут, если не выбраны в наборе.
Так images выводится без вывода самих документов. Свойства указываются кодом.
supports() и schema()
supports(array $iblock) ограничивает чип инфоблоками, где обработчик имеет смысл: $iblock['code'], ['apiCode'], ['type'], ['id'].
schema() возвращает схему значения (OpenAPI 3), её использует Swagger при описании ответа:
['type' => 'array', 'items' => ['type' => 'string']].
Пример в модуле: Fields\GalleryField
Поле images - детальная картинка и файлы свойства MORE_PHOTO. Размеры берутся из «Размеров картинок» набора для DETAIL_PICTURE и MORE_PHOTO.
Пример: DocumentImagesField - картинки из привязанных документов
Задача: у товара привязаны документы (инфоблок «Документы»), в них файлы-картинки и тип документа. Витрине нужен список images: первая - главная
картинка из документа с типом main, остальные - файлы документов с типом gallery; самих документов в ответе быть не должно.
Подготовка в настройках:
- В инфоблоке «Документы» у свойств
TYPE(список) иFILE(файл, множественное) включить флаг «Показывать во вложенном виде (BIK.REST)». - В наборе «Вложенный» инфоблока «Документы» выбрать формат свойств «Компактный» (тогда файл - это путь, список -
{xmlId, value}). - В наборе «Детальная» (и «Список») товара выбрать чип «Картинки из документов». Свойство
DOCUMENTSне выбирайте.
<?php
namespace BIK\Rest\Fields;
use BIK\Rest\Services\Element\ResponseProfile;
class DocumentImagesField extends AbstractElementField
{
const LIMIT = 5;
public static function code(): string
{
return 'images';
}
public static function title(): string
{
return 'Картинки из документов';
}
public static function supports(array $iblock): bool
{
return $iblock['apiCode'] === 'catalog';
}
public static function requires(): array
{
return ['fields' => [], 'properties' => ['DOCUMENTS']];
}
public function batch(array $elements, ResponseProfile $p): array
{
$result = [];
foreach ($elements as $id => $element) {
$documents = $element['PROPERTIES']['DOCUMENTS'] ?? [];
if (isset($documents['VALUE'])) { // формат «Полный»: значения - в VALUE
$documents = $documents['VALUE'];
}
$main = null;
$gallery = [];
foreach ((array)$documents as $document) {
if (!is_array($document)) { // привязка «только ID»: документа нет
continue;
}
$properties = $document['PROPERTIES'] ?? [];
$type = $properties['TYPE']['xmlId'] ?? ($properties['TYPE']['XML_ID'] ?? '');
$files = (array)($properties['FILE'] ?? []);
if ($type === 'main' && $main === null && $files) {
$main = reset($files);
} elseif ($type === 'gallery') {
$gallery = array_merge($gallery, $files);
}
}
$images = array_values(array_unique(array_filter(array_merge([$main], $gallery))));
if ($images) {
$result[$id] = array_slice($images, 0, static::LIMIT);
}
}
return $result;
}
public static function schema(): array
{
return ['type' => 'array', 'items' => ['type' => 'string'], 'maxItems' => static::LIMIT];
}
} Ключ xmlId и вид значений зависят от формата набора «Вложенный»: сверяйтесь с реальным ответом.
Форматер свойства
Форматер выбирается для конкретного свойства на его чипе в наборе инфоблока: стрелка ▾ у чипа открывает меню «Вид значения» - там базовый вид,
у привязок «Только ID» и форматеры, подходящие свойству (supports($property)). Стрелка есть только у свойств, для которых есть выбор.
Выбранный форматер виден в чипе короткой подписью shortTitle(): «Производитель · кратко».
abstract class AbstractPropertyFormatter
{
abstract public static function code(): string;
abstract public static function title(): string;
public static function shortTitle(): string; // подпись в чипе, по умолчанию title()
abstract public static function supports(array $property): bool; // $property - строка b_iblock_property
abstract public function format(array $values, array $property, ResponseProfile $p): mixed;
public static function schema(array $property): array;
} format() получает значения свойства списком (и у одиночного свойства - список из одного) уже в базовом виде набора и возвращает то, что окажется в ответе
как значение: у «Полного» формата - в VALUE, у «Компактного» - вместо значения. У множественного свойства верните обычно массив, у одиночного - одно значение.
Пустой результат - свойство не выводится. Форматер применяется после базового формата, его результат кешируется вместе с данными элемента.
Пример в модуле: Fields\LinkBriefFormatter - привязка к элементу превращается в {id, name, code} вместо собранного элемента.
Вид «Только ID» и форматер у одного свойства в одном наборе не сочетаются: выбирается один вид значения.
Событие OnAfterIblockElementBuild
Для разовой правки без своего класса. Вызывается после сборки, перед отдачей, на каждый ответ, вне кеша данных элемента: можно использовать
пользователя и текущее время. Платите за это сами: код выполняется для каждого элемента ответа, тяжёлые запросы в нём не делайте
(для них - обработчик поля с batch()).
\Bitrix\Main\EventManager::getInstance()->addEventHandler('bik.rest', 'OnAfterIblockElementBuild', function (\BIK\Rest\Events\ApiBuildEvent $event) {
$item = $event->getItem();
if ($event->getContext() === 'list' && isset($item['NAME'])) {
$item['NAME'] = trim($item['NAME']);
$event->setItem($item);
}
}); Обработчик получает объект ApiBuildEvent: getItem() - собранный элемент (ключи полей, PROPERTIES, PRODUCT и т.д., как в ответе; изменённый возвращается через setItem()),
getContext() - list, detail, nested, basket, getIblockId() - ID инфоблока. Регистрируется в /local/php_interface/init.php.
Событие вызывается для элементов, которые отдаются самостоятельно: элементы списка и карточки, позиции корзины, предложения. Привязки, раскрытые
внутри PROPERTIES (документы, бренд), собираются внутри кеша родителя и событие для них не вызывается: для них используйте набор «Вложенный» и форматеры.
Проверка
- Положить файл в
/local/bik.rest/fields/, нажать «Сбросить кеш API». - В Настройки -> BIK.REST -> Инфоблоки открыть инфоблок, в нужном наборе появится чип в группе «Обработчики» (или список форматеров у свойства). Сохранить набор.
- Запросить элементы: в ответе появится ключ
code()обработчика.