События в Битрикс: обработчики

События (events) — штатный механизм 1С-Битрикс, который позволяет вклиниться в работу ядра и модулей, не правя их исходный код. Обработчик события — это ваша функция или метод, который платформа вызывает в определённой точке: перед сохранением заказа, после регистрации пользователя, при отправке письма.

Что такое событие и обработчик

Событие в Битрикс — это именованная точка в коде ядра, в которой платформа даёт возможность стороннему коду выполнить свою логику. Модуль iblock перед добавлением элемента вызывает событие OnBeforeIBlockElementAdd, модуль sale после сохранения заказа — OnSaleOrderSaved, и так далее. Каждое событие имеет три составляющие: идентификатор модуля-источника (например, main, iblock, sale), имя события и набор параметров, которые ядро передаёт обработчику.

Обработчик (handler) — функция, статический метод класса или замыкание, которое вы регистрируете на событие. Когда ядро доходит до точки события, оно последовательно вызывает все зарегистрированные обработчики. Это позволяет держать доработки отдельно от ядра и переживать обновления платформы без конфликтов.

Две системы событий: старая и D7

Исторически в Битрикс сосуществуют два API событий, и оба рабочие.

• Старое ядро — процедурные функции AddEventHandler() и RegisterModuleDependencies(). Обработчику передаётся набор позиционных аргументов, менять данные можно по ссылке (&$arFields).
• Ядро D7 — класс \Bitrix\Main\EventManager и объект \Bitrix\Main\Event. Обработчик получает единый объект события, а результат возвращает через \Bitrix\Main\EventResult.

Какой использовать? Зависит от того, какое событие вы ловите. Многие модули (в частности iblock, старые части sale) до сих пор рассылают события в старом формате, и ловить их нужно старым API. Новые компоненты ядра работают через D7. На практике разработчик держит в голове обе схемы.

Типы событий: OnBefore, OnAfter и уведомления

По назначению события делят на три группы.

Событие OnBeforeIBlockElementUpdate позволяет отменить обновление, вернув false и установив ошибку. OnAfterIBlockElementAdd уже ничего не отменяет — элемент создан, вы лишь реагируете. Понимание этой разницы критично: тяжёлую интеграцию с внешней системой вешают на OnAfter*, а валидацию — на OnBefore*.

Где регистрировать обработчики

Точка регистрации определяет, когда обработчик станет активным.

1. Файл /bitrix/php_interface/init.php (или /local/php_interface/init.php) — подключается на каждом хите. Здесь регистрируют обработчики через AddEventHandler / addEventHandler. Регистрация живёт один запрос.
2. Собственный модуль — регистрация в методе DoInstall() через RegisterModuleDependencies. Запись попадает в таблицу b_module_to_module и действует постоянно, пока модуль установлен.

Пример обработчика

Обработчик на старом API — валидация символьного кода перед сохранением элемента инфоблока. Код кладём в init.php:

AddEventHandler('iblock', 'OnBeforeIBlockElementUpdate', ['MyHandlers', 'checkCode']);

class MyHandlers {
  public static function checkCode(&$arFields) {
    if (empty($arFields['CODE'])) {
      global $APPLICATION;
      $APPLICATION->throwException('Не заполнен символьный код');
      return false;
    }
  }
}

Тот же смысл в D7-стиле на событии главного модуля:

use Bitrix\Main\EventManager;
EventManager::getInstance()->addEventHandler('main', 'OnAfterUserLogin', ['MyHandlers', 'onLogin']);

Порядок вызова и отладка

Если на одно событие висит несколько обработчиков, порядок задаётся параметром сортировки. У AddEventHandler(..., $sort = 100) и у RegisterModuleDependencies(..., $sort = 100) меньшее значение вызывается раньше. Это важно, когда один обработчик подготавливает данные для другого.

• Чтобы увидеть все обработчики события, посмотрите таблицу b_module_to_module (постоянные) и содержимое init.php (временные).
• Для отладки удобно логировать вход в обработчик через AddMessage2Log() или \Bitrix\Main\Diag\Debug::writeToFile().
• Если обработчик «не срабатывает», проверьте точное написание модуля и имени события — они регистрозависимы.

Итог

События — это фундамент расширяемости 1С-Битрикс. Они дают возможность встроить бизнес-логику, валидацию, интеграции и уведомления, не касаясь ядра, и потому переживать обновления. Разработчику важно различать старое и D7-API, понимать разницу OnBefore* и OnAfter* и выбирать правильную точку регистрации.

Мы проектируем доработки Битрикс так, чтобы они были устойчивы к обновлениям и понятны следующему разработчику: обработчики выносим в собственные модули, покрываем логированием и документируем. Если нужна интеграционная разработка или автоматизация бизнес-процессов на событиях — поможем спроектировать архитектуру и написать код.