Как подключить
Обработчик регистрируется штатным механизмом Битрикса в init.php сайта (/local/php_interface/init.php), модуль — bik.rest:
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnAfterSaleGetBasket',
function (\BIK\Rest\Events\ApiEvent $event) {
$response = $event->getResponse();
$response['note'] = 'Доставка от 3 дней';
$event->setResponse($response);
}
); Обработчики одного события выполняются по порядку регистрации (параметр SORT) и получают один и тот же объект: каждый следующий видит изменения предыдущего. После добавления метода или переименования контроллера сбросьте кеш API («Сбросить кеш API» в настройках модуля): имена событий хранятся в таблице маршрутов.
Какие бывают события
- События метода. У каждого метода API два события:
OnBefore<Роутер><Метод>(«до») иOnAfter<Роутер><Метод>(«после»). Имя берётся из имени метода контроллера без path-параметров, сегмент перед параметром — в единственном числе:GET /api/sale/basket—OnBeforeSaleGetBasket/OnAfterSaleGetBasket,POST /api/sale/basket—OnBeforeSalePostBasket,GET /api/iblock/{код}/elements—OnAfterIblockGetElements,GET /api/iblock/{код}/elements/{id}—OnAfterIblockGetElement. - Общая пара
OnBeforeApiRequest/OnAfterApiRequest: вызывается для любого метода. - События сборки ответа: вызываются внутри метода, там, где собирается элемент, SEO, заказ (
OnAfterIblockElementBuildи другие).
Порядок для одного запроса: OnBeforeApiRequest, OnBefore<Метод>, сам метод, OnAfter<Метод>, OnAfterApiRequest. Ошибки маршрутизации (404, 405) и приведения параметров (400) события не вызывают.
Что делает «до» и что делает «после»
- «До» — запрос ещё не выполнен. Можно изменить параметры (
setParam()), остановить запрос с ошибкой (stop()) или сразу отдать свой ответ (respond()). - «После» — метод отработал. Можно изменить ответ (
setResponse()) и код ответа (setStatus()). Ответ — итоговый JSON, такой же, как видит витрина (ключи camelCase).
Вызов метода не из своей фазы (например, stop() в «после») — ошибка обработчика: клиент получит «Внутренняя ошибка», подробности попадут в журнал.
Объект ApiEvent
Событие метода передаёт \BIK\Rest\Events\ApiEvent:
| Метод | Что делает | Фаза |
|---|---|---|
getName() | имя метода, например SaleGetBasket | обе |
getRoute() | маршрут, например GET /api/sale/basket | обе |
getHttpMethod() | GET, POST, PUT, DELETE | обе |
getIblock() | инфоблок (ID, API_CODE, NAME, IBLOCK_TYPE_ID) для методов /api/iblock/*, иначе null | обе |
getParams() / getParam($name, $default) | аргументы метода: поля тела у POST и PUT, query у GET и DELETE, сегменты пути | обе |
setParam($name, $value) | изменить аргумент; неизвестное имя — ошибка | «до» |
stop($text, $status = 400) | остановить метод: клиент получит ошибку с этим текстом, следующие обработчики не вызываются | «до» |
respond($data, $status = 200) | отдать свой ответ вместо ответа метода; обработчики «после» вызываются | «до» |
getResponse() / setResponse($array) | прочитать и заменить ответ | «после» |
getStatus() / setStatus($code) | прочитать и изменить код ответа | «после» |
stop() с кодом 4xx клиент получает как есть: {"success": false, "error": "текст"}. Любое другое исключение или ошибка PHP в обработчике — «Внутренняя ошибка» и запись в журнал.
Объект ApiBuildEvent
События сборки ответа передают \BIK\Rest\Events\ApiBuildEvent:
| Метод | Что делает |
|---|---|
getItem() / setItem($item) | главное значение события: элемент, SEO, ответ заказа, режим предложений или сумма; результат возвращается через setItem() |
getContext() | набор ответа (list, detail, nested, basket) или место вызова |
getIblockId() | ID инфоблока, 0, если событие к инфоблоку не относится |
getArg($name, $default) / getArgs() | дополнительные данные только для чтения (заказ, ID товара и т. п.) |
stop($text, $status = 400) | остановить операцию с ошибкой, там, где это допустимо (OnBefore…) |
Примеры: общая пара
OnBeforeApiRequest видит имя метода, маршрут и параметры любого запроса. Пример: закрыть запись на время обслуживания.
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnBeforeApiRequest',
function (\BIK\Rest\Events\ApiEvent $event) {
if ($event->getHttpMethod() === 'POST' && file_exists($_SERVER['DOCUMENT_ROOT'] . '/upload/maintenance.flag')) {
$event->stop('Идут технические работы, попробуйте позже', 503);
}
}
); OnAfterApiRequest видит готовый ответ любого метода. Пример: добавить в каждый ответ имя метода (удобно при отладке витрины).
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnAfterApiRequest',
function (\BIK\Rest\Events\ApiEvent $event) {
$response = (array)$event->getResponse();
$response['apiMethod'] = $event->getName();
$event->setResponse($response);
}
); Примеры: по одному «до» и «после» на группу методов
Данные и ответы в примерах взяты из соответствующих тем руководства. Остальные события группы устроены так же: меняется только имя события и состав параметров и ответа.
Корзина (sale)
«После получения корзины»: OnAfterSaleGetBasket. Ответ метода GET /api/sale/basket:
{
"numProducts": 1,
"totalPrice": 4000,
"quantity": 2,
"data": [
{ "id": 15, "productId": 105, "name": "Футболка базовая", "quantity": 2, "price": 2000, "sumValue": 4000, "currency": "RUB" }
],
"coupons": []
} Обработчик пишет в журнал товары, цены и итог, а в ответ добавляет поле freeDelivery:
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnAfterSaleGetBasket',
function (\BIK\Rest\Events\ApiEvent $event) {
$response = $event->getResponse();
$lines = [];
foreach ((array)($response['data'] ?? []) as $row) {
$lines[] = $row['name'] . ': ' . $row['quantity'] . ' x ' . $row['price'] . ' = ' . $row['sumValue'] . ' ' . $row['currency'];
}
AddMessage2Log(implode('; ', $lines) . '; итого ' . ($response['totalPrice'] ?? 0), 'bik.rest');
$response['freeDelivery'] = (float)($response['totalPrice'] ?? 0) >= 5000;
$event->setResponse($response);
}
); «До добавления в корзину»: OnBeforeSalePostBasket. Параметры метода POST /api/sale/basket — productId, quantity, delay, fastBuy, productPropsVar, basketId; для запроса {"productId": 105, "quantity": 2} getParams() вернёт productId = 105, quantity = 2. Обработчик ограничивает количество и останавливает запрос с текстом:
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnBeforeSalePostBasket',
function (\BIK\Rest\Events\ApiEvent $event) {
if ((int)$event->getParam('productId') === 5) {
$event->stop('Товар недоступен для заказа', 400);
return;
}
if ((int)$event->getParam('quantity') > 10) {
$event->stop('Не больше 10 штук в одни руки', 400);
}
}
); Клиент получит статус 400 и {"success": false, "error": "Товар недоступен для заказа"}, корзина не изменится.
Вход и регистрация (auth)
OnBeforeAuthPostLogin: параметры username, password. Приведём логин к нижнему регистру без пробелов:
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnBeforeAuthPostLogin',
function (\BIK\Rest\Events\ApiEvent $event) {
$event->setParam('username', mb_strtolower(trim((string)$event->getParam('username'))));
}
); OnAfterAuthPostLogin: ответ успешного входа — {"success": true}. Добавим флаг для витрины:
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnAfterAuthPostLogin',
function (\BIK\Rest\Events\ApiEvent $event) {
$response = (array)$event->getResponse();
if (!empty($response['success'])) {
$response['welcome'] = true;
$event->setResponse($response);
}
}
); Пользователь (user)
OnAfterUserGet: ответ GET /api/user — {"data": {"id": 12, "name": "Иван", "lastName": "Иванов", ...}}. Добавим готовое имя для шапки:
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnAfterUserGet',
function (\BIK\Rest\Events\ApiEvent $event) {
$response = (array)$event->getResponse();
if (isset($response['data']) && is_array($response['data'])) {
$response['data']['fullName'] = trim(($response['data']['name'] ?? '') . ' ' . ($response['data']['lastName'] ?? ''));
$event->setResponse($response);
}
}
); OnBeforeUserPost: тело POST /api/user приходит одним параметром requestBody. Запретим менять логин:
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnBeforeUserPost',
function (\BIK\Rest\Events\ApiEvent $event) {
$body = (array)$event->getParam('requestBody', []);
if (array_key_exists('login', $body)) {
$event->stop('Логин изменить нельзя', 400);
}
}
); Профили и счёт (profile)
OnBeforeProfileGetAccountHistory: параметры limit, offset. Ограничим размер страницы:
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnBeforeProfileGetAccountHistory',
function (\BIK\Rest\Events\ApiEvent $event) {
if ((int)$event->getParam('limit') > 50) {
$event->setParam('limit', 50);
}
}
); OnAfterProfileGetAccount: ответ GET /api/profile/account содержит id, userId, currentBudget, currency, locked. Добавим подпись:
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnAfterProfileGetAccount',
function (\BIK\Rest\Events\ApiEvent $event) {
$response = (array)$event->getResponse();
if (isset($response['data']['currentBudget'])) {
$response['data']['title'] = 'На счёте ' . $response['data']['currentBudget'] . ' ' . ($response['data']['currency'] ?? '');
$event->setResponse($response);
}
}
); Списки (list)
OnBeforeListPost: параметры list_name, element_id, name, data. Разрешим писать только в известные списки:
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnBeforeListPost',
function (\BIK\Rest\Events\ApiEvent $event) {
if (!in_array($event->getParam('list_name'), ['favorites', 'comparison', 'visited'], true)) {
$event->stop('Неизвестный список', 400);
}
}
); OnAfterListGet: ответ GET /api/list — {"data": [...], "pagen": {...}}. Добавим счётчик записей на странице:
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnAfterListGet',
function (\BIK\Rest\Events\ApiEvent $event) {
$response = (array)$event->getResponse();
if (isset($response['data']) && is_array($response['data'])) {
$response['onPage'] = count($response['data']);
$event->setResponse($response);
}
}
); Картинки (image)
У методов два события с именами ImageGetById и ImageGetByPath. OnBeforeImageGetById: параметры resizeType, width, height, imageId. Ограничим размер копии:
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnBeforeImageGetById',
function (\BIK\Rest\Events\ApiEvent $event) {
foreach (['width', 'height'] as $name) {
if ((int)$event->getParam($name) > 2000) {
$event->setParam($name, 2000);
}
}
}
); Ответ методов картинок — не JSON, а файл: его отдаёт сам метод, поэтому «после» не меняет картинку, а годится для учёта (код ответа и параметры). Пример OnAfterImageGetById:
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnAfterImageGetById',
function (\BIK\Rest\Events\ApiEvent $event) {
AddMessage2Log($event->getRoute() . ' -> ' . $event->getStatus() . ', файл ' . $event->getParam('imageId'), 'bik.rest');
}
); Сервисные методы (service)
OnBeforeServiceGetSearch: параметры iblock_codes, searchable_content. Уберём пробелы и не пустим слишком короткий запрос:
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnBeforeServiceGetSearch',
function (\BIK\Rest\Events\ApiEvent $event) {
$query = trim((string)$event->getParam('searchable_content'));
if (mb_strlen($query) < 3) {
$event->stop('Введите не меньше трёх символов', 400);
return;
}
$event->setParam('searchable_content', $query);
}
); OnAfterServiceGetSearch: ответ сгруппирован по коду инфоблока ({"catalog": {"sections": [...], "elements": [...]}}). Добавим общее число найденных элементов:
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnAfterServiceGetSearch',
function (\BIK\Rest\Events\ApiEvent $event) {
$response = (array)$event->getResponse();
$found = 0;
foreach ($response as $group) {
if (is_array($group) && isset($group['elements']) && is_array($group['elements'])) {
$found += count($group['elements']);
}
}
$response['found'] = $found;
$event->setResponse($response);
}
); Инфоблоки (iblock)
Инфоблок события виден через getIblock(). OnBeforeIblockGetElements: параметры limit, offset и остальные параметры списка. Ограничим размер страницы каталога:
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnBeforeIblockGetElements',
function (\BIK\Rest\Events\ApiEvent $event) {
if ((int)$event->getParam('limit') > 100) {
$event->setParam('limit', 100);
}
}
); OnAfterIblockGetElements: ответ — {"data": [{"id": 4, "name": "Штаны Полосатый Рейс", ...}], "pagen": {"total": 10038, "limit": 1, "offset": 0}}. Добавим в ответ код инфоблока:
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnAfterIblockGetElements',
function (\BIK\Rest\Events\ApiEvent $event) {
$iblock = $event->getIblock();
$response = (array)$event->getResponse();
$response['iblock'] = $iblock ? $iblock['API_CODE'] : null;
$event->setResponse($response);
}
); Примеры: события сборки ответа
OnAfterIblockElementBuild вызывается для каждого элемента ответа (список, карточка, вложенный элемент, позиция корзины); результат возвращается через setItem(). Пример: добавить поле только в списке каталога.
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnAfterIblockElementBuild',
function (\BIK\Rest\Events\ApiBuildEvent $event) {
if ($event->getContext() !== 'list') {
return;
}
$item = $event->getItem();
$item['isNew'] = !empty($item['id']) && (int)$item['id'] > 1000;
$event->setItem($item);
}
); OnBeforeSaleBonusWithdraw (до списания бонусов): сумма в getItem(), заказ — getArg('order'). Пример: не списывать больше 30 процентов заказа и отказать в списании с ошибкой:
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnBeforeSaleBonusWithdraw',
function (\BIK\Rest\Events\ApiBuildEvent $event) {
$order = $event->getArg('order');
$withdraw = (float)$event->getItem();
$limit = $order->getPrice() * 0.3;
if ($withdraw > $limit) {
$event->stop('Бонусами можно оплатить не больше 30% заказа', 400);
}
}
); OnAfterSaleOrderBuild: при getContext() === 'order' в getItem() — ответ order/refresh и order/save целиком (данные заказа в data):
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnAfterSaleOrderBuild',
function (\BIK\Rest\Events\ApiBuildEvent $event) {
if ($event->getContext() === 'order') {
$item = $event->getItem();
$item['data']['managerComment'] = 'Комментарий менеджера';
$event->setItem($item);
}
}
); OnAfterIblockElementSeo получает SEO (h1, title, keywords, description) и ID, IBLOCK_ID, NAME, CODE в getArg(). Работа: getItem(), изменение, setItem(). Пример для SEO элемента:
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnAfterIblockElementSeo',
function (\BIK\Rest\Events\ApiBuildEvent $event) {
$seo = (array)$event->getItem();
$seo['title'] = ($event->getArg('NAME') ?: ($seo['title'] ?? '')) . ' - купить в магазине';
$event->setItem($seo);
}
); OnAfterIblockSectionSeo — то же для раздела: SEO (h1, title, keywords, description) в getItem(), ID, IBLOCK_ID, NAME, CODE раздела в getArg(). Пример: дописать к заголовку страницы название раздела, если шаблон его не дал:
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnAfterIblockSectionSeo',
function (\BIK\Rest\Events\ApiBuildEvent $event) {
$seo = (array)$event->getItem();
$seo['title'] = ($seo['title'] ?? '') ?: ($event->getArg('NAME') . ' - каталог');
$event->setItem($seo);
}
); OnBeforeIblockOffersBuild вызывается до сборки предложений товара: в getItem() — режим (full, lite, min, selected, none), в getContext() — где строятся предложения (list, detail, basket, reference), в getArg('productId') — ID товара. Пример: в списке отдавать только выбранное предложение, чтобы ответ был легче; значение вне списка режимов игнорируется (будет full):
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnBeforeIblockOffersBuild',
function (\BIK\Rest\Events\ApiBuildEvent $event) {
if ($event->getContext() === 'list') {
$event->setItem('selected');
}
}
); OnAfterSaleBonusWithdraw вызывается после сохранения заказа с бонусной оплатой (программа лояльности): в getItem() — сумма списания (число), в getArg('order') — заказ \Bitrix\Sale\Order. Вернуть через setItem() итоговую сумму; 0 — списание не подтверждено, внутренний платёж не будет отмечен оплаченным. Пример: подтвердить не больше 30 процентов заказа:
<?php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
'bik.rest',
'OnAfterSaleBonusWithdraw',
function (\BIK\Rest\Events\ApiBuildEvent $event) {
$order = $event->getArg('order');
$withdraw = (float)$event->getItem();
$event->setItem(min($withdraw, $order->getPrice() * 0.3));
}
); Остальные события
Остальные события методов устроены так же, как примеры выше: имя события — OnBefore или OnAfter плюс роутер и метод; параметры и ответ — как у метода в документации API (Swagger). Список всех событий этой установки, с тем, что получает обработчик и что он может изменить:
<!-- events -->
Было и стало
Прежние названия событий (OnApiRun, OnAfterApiRun, OnElementResourceReduce, OnGetElementMeta, OnGetSectionMeta, OnBeforeBuildOffers, OnGetBasket, OnPrepareOrderResponse, OnSaleResourceReduce, OnBeforeSaveOrder, OnAfterSaveOrder) больше не вызываются: обработчики переносятся на новые.
| Было | Стало |
|---|---|
OnApiRun | OnBeforeApiRequest |
OnAfterApiRun | OnAfterApiRequest |
OnElementResourceReduce | OnAfterIblockElementBuild |
OnGetElementMeta | OnAfterIblockElementSeo |
OnGetSectionMeta | OnAfterIblockSectionSeo |
OnBeforeBuildOffers | OnBeforeIblockOffersBuild |
OnGetBasket | OnAfterSaleGetBasket |
OnPrepareOrderResponse | OnAfterSaleOrderBuild, getContext() === 'order' |
OnSaleResourceReduce | OnAfterSaleOrderBuild, getContext() === 'sale' |
OnBeforeSaveOrder | OnBeforeSaleBonusWithdraw |
OnAfterSaveOrder | OnAfterSaleBonusWithdraw |
Подробности переноса — в release notes модуля. События штатного компонента sale.order.ajax и catalog:OnGetOptimalPriceResult не менялись.