Расширение модуля тема 24 из 27

События

События позволяют изменить поведение API в проекте, не правя модуль: проверить или поправить параметры запроса, остановить его с ошибкой, подменить или дополнить ответ. Код обработчиков живёт в проекте, обновление модуля его не затрагивает.

в этой теме 10
  1. Как подключить
  2. Какие бывают события
  3. Что делает «до» и что делает «после»
  4. Объект ApiEvent
  5. Объект ApiBuildEvent
  6. Примеры: общая пара
  7. Примеры: по одному «до» и «после» на группу методов
  8. Примеры: события сборки ответа
  9. Остальные события
  10. Было и стало

Как подключить

Обработчик регистрируется штатным механизмом Битрикса в init.php сайта (/local/php_interface/init.php), модуль — bik.rest:

php
<?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» в настройках модуля): имена событий хранятся в таблице маршрутов.

Какие бывают события

  1. События метода. У каждого метода 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.
  2. Общая пара OnBeforeApiRequest / OnAfterApiRequest: вызывается для любого метода.
  3. События сборки ответа: вызываются внутри метода, там, где собирается элемент, 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
<?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
<?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:

json
{
    "numProducts": 1,
    "totalPrice": 4000,
    "quantity": 2,
    "data": [
        { "id": 15, "productId": 105, "name": "Футболка базовая", "quantity": 2, "price": 2000, "sumValue": 4000, "currency": "RUB" }
    ],
    "coupons": []
}

Обработчик пишет в журнал товары, цены и итог, а в ответ добавляет поле freeDelivery:

php
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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
<?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) больше не вызываются: обработчики переносятся на новые.

БылоСтало
OnApiRunOnBeforeApiRequest
OnAfterApiRunOnAfterApiRequest
OnElementResourceReduceOnAfterIblockElementBuild
OnGetElementMetaOnAfterIblockElementSeo
OnGetSectionMetaOnAfterIblockSectionSeo
OnBeforeBuildOffersOnBeforeIblockOffersBuild
OnGetBasketOnAfterSaleGetBasket
OnPrepareOrderResponseOnAfterSaleOrderBuild, getContext() === 'order'
OnSaleResourceReduceOnAfterSaleOrderBuild, getContext() === 'sale'
OnBeforeSaveOrderOnBeforeSaleBonusWithdraw
OnAfterSaveOrderOnAfterSaleBonusWithdraw

Подробности переноса — в release notes модуля. События штатного компонента sale.order.ajax и catalog:OnGetOptimalPriceResult не менялись.

Подключим BIK.REST-API к вашему сайту

Оставьте заявку — установим и настроим модуль, ответим на вопросы по API.

c заботой о вас, мы используем cookie на своем сайте, чтобы интернет был чистым и прекрасным