← Назад к справке

Ядро

События EventManager

Рабочая справка по событиям Bitrix Framework: EventManager, addEventHandler, registerEventHandler, совместимые обработчики и свои события.

События позволяют подключать свою логику к ядру и модулям без правки их файлов. В локальных модулях постоянные обработчики обычно регистрируют при установке и удаляют при удалении.

Основы

EventManager управляет обработчиками событий в новом ядре.

Что такое EventManager

EventManager используется для краткосрочной и долгосрочной регистрации обработчиков событий. 

<?php

use Bitrix\Main\EventManager;

/**
 * Возвращает EventManager.
 */
function fetchEventManager(): EventManager
{
    return EventManager::getInstance();
}

$event_manager = fetchEventManager();

Временные и постоянные обработчики

Метод Когда использовать
addEventHandler() Временный обработчик на текущий хит.
registerEventHandler() Постоянный обработчик, который хранится в системе.
unRegisterEventHandler() Удаление постоянного обработчика.

Совместимые обработчики

Для старых событий, где обработчик ожидает старый набор аргументов, часто используют методы с суффиксом Compatible. 

$event_manager->registerEventHandlerCompatible(
    'crm',
    'OnAfterCrmDealUpdate',
    'test.example',
    \test\Example\EventHandler\DealHandler::class,
    'onAfterDealUpdate'
);

Регистрация

Примеры регистрации обработчиков в коде и в установщике модуля.

addEventHandler

<?php

use Bitrix\Main\Event;
use Bitrix\Main\EventManager;

/**
 * Добавляет временный обработчик события.
 */
function addTemporaryHandler(): void
{
    EventManager::getInstance()->addEventHandler(
        'main',
        'OnProlog',
        function (Event $event): void {
            AddMessage2Log('OnProlog выполнен', 'event_debug');
        }
    );
}

addTemporaryHandler();

registerEventHandler

<?php

use Bitrix\Main\EventManager;

const MODULE_ID = 'test.example';

/**
 * Регистрирует обработчик события при установке модуля.
 */
function registerModuleEventHandler(): void
{
    EventManager::getInstance()->registerEventHandler(
        'main',
        'OnProlog',
        MODULE_ID,
        \test\Example\EventHandler\PrologHandler::class,
        'onProlog'
    );
}

registerModuleEventHandler();

unRegisterEventHandler

<?php

use Bitrix\Main\EventManager;

const MODULE_ID = 'test.example';

/**
 * Удаляет обработчик события при удалении модуля.
 */
function unregisterModuleEventHandler(): void
{
    EventManager::getInstance()->unRegisterEventHandler(
        'main',
        'OnProlog',
        MODULE_ID,
        \test\Example\EventHandler\PrologHandler::class,
        'onProlog'
    );
}

unregisterModuleEventHandler();

Свои события

Модуль может не только слушать чужие события, но и отправлять свои.

Отправить событие

<?php

use Bitrix\Main\Event;

const MODULE_ID = 'test.example';

/**
 * Отправляет своё событие модуля.
 */
function sendExampleEvent(int $item_id): void
{
    $event = new Event(
        MODULE_ID,
        'OnAfterExampleItemProcessed',
        [
            'item_id' => $item_id,
        ]
    );

    $event->send();
}

sendExampleEvent($item_id);

Обработать событие

<?php

namespace test\Example\EventHandler;

use Bitrix\Main\Event;

class ExampleHandler
{
    /**
     * Обрабатывает своё событие модуля.
     */
    public static function onAfterExampleItemProcessed(Event $event): void
    {
        $parameters = $event->getParameters();
        $item_id = (int) ($parameters['item_id'] ?? 0);

        AddMessage2Log(
            [
                'message' => 'Элемент обработан',
                'item_id' => $item_id,
            ],
            'example_event'
        );
    }
}

Источники