Обработчики событий

Обработчики событий

Система «1С-Битрикс: Управление сайтом» не замкнутая и допускает несколько способов расширения и изменения своей логики. В процессе работы сайта внутри фреймворка возникает множество т.н. «событий»: событие «сразу после добавления элемента инфоблока», событие «непосредственно перед началом страницы», событие «сразу после удаления пользователя».

У разработчиков есть возможность создавать свои php-функции и методы, которые будет вызывать фреймворк в момент срабатывания определенного события. Такие методы называются «обработчиками событий».

Название методов обычно выбирают по 2-ум схемам: либо по названию обрабатываемого события, либо по выполняемому действию.

// Пример: Обработчик события завершения страницы
public static function OnEndBufferContent(&$content)
{
	$content = str_replace('#DATE#', date('d.m.Y'), $content);
}

После объявления метода фреймворку нужно сообщить, какое событие он должен обрабатывать. Это можно сделать при установке модуля с помощью Bitrix\Main\EventManager::registerEventHandler или «на хитах» с помощью itrix\Main\EventManager::addEventHandler.

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

При регистрации обработчика нужно указать, модуль и событие, которое «прослушивается», а также класс и метод-обработчик. В каждом модуле есть свой список событий, он приведен в документации по продукту.

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

В аргументах для обработчика может быть объект вида \Bitrix\Main\Event (для современных событий), внутри которого переданы все нужные параметры события, либо непосредственно параметры события (для устаревших событий).

Возвращать обработчик должен либо объект класса \Bitrix\Main\EventResult (для современных событий), либо другие типы данных (разные для разных устаревших событий).

OnBefore и OnAfter

События можно разделить на OnBefore - событие перед фактическим выполнением действия, и OnAfter - событие после фактического выполнения действия. В большинстве случаев это отражено прямо в названии события: OnBeforeProlog, OnAfterEpilog, OnBeforeUserAdd, OnAfterUserLogin.

К примеру, метод CIBlockElement::Update($id, $fields) в ходе своего выполнения:

1. Обрабатывает свои аргументы и готовится выполнить изменения в БД (обновить элемент Инфоблока)
2. Вызывает обработчики события OnBeforeIBlockElementUpdate(&$fields)
3. Вносит изменения в БД
4. Вызывает обработчики события OnAfterIBlockElementUpdate($fields)

Событие «до обновления» (OnBeforeIBlockElementUpdate) находится в старом ядре и обработчик принимает аргументы по ссылке. Обработчик может изменить данные или отменить сам вызываемый метод Update. В таком случае метод CIBlockElement::Update завершится с ошибкой. Устаревшие обработчики чтобы прервать исполнение события должны вернуть false.

Каждое событие может «слушать» несколько обработчиков. То есть для корректного обновления элемента инфоблока в нашем примере нужно, чтобы все обработчики не стали отменять событие.

К моменту вызова обработчика события «после обновления» (OnAfterIBlockElementUpdate) обновление уже завершено, изменить данные или отменить действие невозможно, в БД записаны новые данные элемента ИБ.

К «третьей» группе событий можно отнести события OnLocalRedirect, OnIBlockDelete и пр., в названии которых нет подсказки и которые в документации описаны словами «вызывается в момент». Обычно такие события испускаются до фактического выполнения, но от обычных событий OnBefore они отличаются тем, что не могут повлиять на данные или отменить срабатывание события. Это не строгое правило, всегда в таких сложных случаях сверяйтесь с документацией или даже исходным кодом фреймворка.

Когда нужно обрабатывать сразу два события, и OnBefore и OnAfter

Рассмотрим еще один пример (задание из видеокурса): отправка уведомления о добавлении пользователя в группу «Администраторы».

Можно ли это сделать только через событие «до» обновления пользователя?

Нет, так как E-mail должен отправляться только по факту добавления пользователя в соответствующую группу.

А через событие «после» обновления?

Снова нет, так как фреймворк не хранит историю изменений пользователей, и после обновления уже неизвестно, был ли он добавлен в «Администраторы» только что, или месяц назад.

Это как раз тот случай, когда нужны оба обработчика. В обработчике «до» нужно получить текущий список групп пользователя, а в обработчике «после» проверить: если сейчас пользователь присутствует в группе, а раньше его там не было, то можно отправить E-mail.

Эту ошибку можно избежать, если взять за правило не вносить изменения БД в событиях OnBefore, тем более в ту же сущность.

Если изменения все же необходимо внести, то рекомендуем ознакомиться со способом избежания зацикливания обработчиков событий Зацикливание обработчиков событий.

Примеры

Рассмотрим несколько примеров обработчиков событий.

OnBeforeAdd ORM-сущности

Подробнее ORM-сущности и их события будут рассмотрены в следующих уроках

class BookTable extends \Bitrix\Main\Entity\DataManager
{
	// ...
}

$ormEventManager = \Bitrix\Main\ORM\EventManager::getInstance();

$ormEventManager->addEventHandler(
	BookTable::class,
	\Bitrix\Main\Entity\DataManager::EVENT_ON_BEFORE_ADD,
	[
		OrmEventHandlers::class,
		'bookOnBeforeAdd'
	]
);

class OrmEventHandlers
{
	public static function bookOnBeforeAdd(\Bitrix\Main\Entity\Event $event)
	{
		$result = new \Bitrix\Main\Entity\EventResult;
		$data = $event->getParameter('fields');

		if (isset($data['ISBN']))
		{
			$result->addError(new \Bitrix\Main\Entity\FieldError(
				$event->getEntity()->getField('ISBN'),
				'Запрещено менять ISBN код у существующих книг'
			));
		}

		return $result;
	}
}