Подписка на события

Регистрируйте обработчики через Bitrix\Main\EventManager для модуля native.api в local/php_interface/init.php.

Схема событий

Обработка запроса

Этапы идут сверху вниз; у каждого указаны события до и после его выполнения.

native.api
│
├──── onBeforeStart
├─ Запуск API
├──── onAfterStart
│
├──── onBeforeIpAccessGlobal
├─ Глобальный доступ по IP
├──── onAfterIpAccessGlobal
│
├──── onBeforeCors
├─ Проверка CORS
├──── onAfterCors
│  // OPTIONS переходит к формированию ответа
│
├──── onBeforeRouting
├─ Поиск роута
├──── onAfterRouting
│
├──── onBeforeIpAccess
├─ Доступ по IP выбранного роута
├──── onAfterIpAccess
│
├──── onBeforeAuthorization
├─ Авторизация
├──── onAfterAuthorization
│
├──── onBeforeGroupAccess
├─ Доступ по группам
├──── onAfterGroupAccess
│
├──── onBeforeSchedule
├─ Расписание
├──── onAfterSchedule
│
├──── onBeforeRequestLimit
├─ Лимиты запросов
├──── onAfterRequestLimit
│
├──── onBeforeParameters
├─ Проверка параметров
├──── onAfterParameters
│
├─ Проверка кеша
│  // Если результат есть в кеше, пропускаем контроллер и его события
│  // и сразу переходим к формированию ответа
│
├──── onBeforeController
├─ Контроллер
├──── onAfterController
│
├─ Формирование ответа
│
├──── onBeforeResponse
├─ Отправка ответа
│
├─ Фоновая задача
└──── onAfterResponse

При отказе CORS onAfterCors и последующие этапы не вызываются.

Операции с токенами

События токенов вызываются при соответствующей операции, независимо от основной цепочки запроса.

├──── onBeforeTokenAdd
├─ Добавление токена
└──── onAfterTokenAdd

├──── onBeforeTokenUpdate
├─ Изменение токена
└──── onAfterTokenUpdate

├──── onBeforeTokenDelete
├─ Удаление токена
└──── onAfterTokenDelete

Регистрация

Обработчики подключаются через EventManager::addEventHandler() после Loader::includeModule('native.api'). Используйте константы ModuleEventConfig для имён событий и параметров.

В разделе «Примеры работы → События» приведены регистрации Before/After: изменение IP-списков роута, передача проверенного IP, подготовка параметров, изменение результата контроллера и добавление HTTP-заголовка.

Контекст и результат

Bitrix\Main\Event передаёт apiContext — текущий контекст API. Доступны getParams(), setParams(), getRoute() и getAuth(). Сам объект контекста заменять нельзя.

Результат обработчика события запроса
├─ null / return; / false → продолжить выполнение
├─ EventResult::SUCCESS → заменить указанные параметры события
├─ EventResult::ERROR
│  ├─ exception → остановить сценарий исключением
│  └─ response → завершить сценарий готовым ответом
├─ Массив, включая [] → немедленно отправить JSON/XML
└─ HttpResponse → немедленно отправить готовый HTTP-ответ

При повторной записи ключа применяется значение последнего обработчика. Неверный тип результата вызывает EVENT_HANDLER_RESULT_INVALID.

EventResult разбирается после вызова обработчиков события. Массив и HttpResponse обрабатываются немедленно: следующие обработчики, дальнейшие этапы и события onBeforeResponse / onAfterResponse не вызываются. Уже выполненные действия и запланированные фоновые задачи автоматически не отменяются. Досрочный ответ из события контроллера не записывается в кеш роута. При попадании в уже готовый кеш события контроллера не вызываются. Проверки, обязательные на каждом запросе, размещайте на более раннем этапе, например в onBeforeParameters.

Для событий токенов действует отдельный контракт: false отменяет Before-операцию; результат After-обработчика игнорируется.

Досрочный ответ

Массив данных

В теле обработчика верните массив:

return ['test' => 123];

Модуль вернёт HTTP 200. Формат и технический конверт берутся из выбранного роута; до выбора роута используются JSON и глобальная настройка конверта. Параметр запроса format сохраняет приоритет. При включённом конверте данные окажутся в result, при выключенном — непосредственно в теле ответа.

HTTP-статус и данные

Статус задаётся существующим ключом ResponseConfig::STATUS. Например, обработчик перед контроллером может завершить запрос с HTTP 403:

use Bitrix\Main\Event;
use Bitrix\Main\EventManager;
use Native\Api\Config\Internals\BaseConfig;
use Native\Api\Config\Internals\ModuleEventConfig;
use Native\Api\Config\Internals\ResponseConfig;

EventManager::getInstance()->addEventHandler(
    BaseConfig::MODULE_ID,
    ModuleEventConfig::BEFORE_CONTROLLER,
    static function (Event $event): array {
        return [
            ResponseConfig::STATUS => 403,
            ResponseConfig::HEADERS => ['X-Reason' => 'access-denied'],
            'test' => 123,
        ];
    },
);

Регистрируйте обработчик после подключения модуля — см. общий блок подключения. status задаёт HTTP-код и не попадает в пользовательские данные. Ключ headers позволяет передать заголовки ответа. Для HEAD и статусов без тела, например 204 и 304, данные не отправляются.

Готовый HTTP-ответ

Для ответа обычным текстом или HTML можно вернуть Bitrix\Main\HttpResponse: модуль отправит готовый объект без преобразования в JSON/XML. Для JSON/XML, включая собственный HTTP-статус и заголовки, достаточно массива из примера выше.

Для onAfterResponse ответ уже отправлен: массив или HttpResponse прекращает только следующих обработчиков этого события. Новое тело и статус клиенту не отправляются.

Список событий

Параметры и поведение событий по этапам:

• Запуск и роутинг
• Проверки доступа
• Обработка запроса
• Токены

Имена и ключи параметров — в справочнике ModuleEventConfig.