Base — базовый класс фильтров действий
Пространство имен: Bitrix\Main\Engine\ActionFilter
Модуль: main — подключать отдельно не нужно
Когда использовать
Класс Base — родитель всех фильтров действий контроллера, например Authentication, HttpMethod и Csrf. Наследуйте от него свой фильтр, если стандартных фильтров не хватает. Класс реализует интерфейс Bitrix\Main\Errorable.
Фильтр подключают к действию в методе configureActions контроллера или компонента в ключах prefilters и postfilters. Элемент этих списков — объект наследника Base или замыкание. Для другого значения контроллер выбрасывает Bitrix\Main\Engine\Exception\ActionConfigurationException при создании объекта контроллера.
Подробнее о фильтрах — в статье Префильтры и постфильтры.
Методы класса
| Метод | Описание | С версии |
|---|---|---|
| className | Возвращает полное имя класса фильтра | |
| listAllowedScopes | Возвращает области, в которых фильтр работает | |
| bindAction | Привязывает фильтр к действию | |
| getAction | Возвращает действие, к которому привязан фильтр | |
| getErrors | Возвращает ошибки фильтра | |
| getErrorByCode | Возвращает первую ошибку фильтра с заданным кодом |
Как написать свой фильтр
Переопределите в наследнике методы-обработчики:
onBeforeAction(Event $event)— выполняется до действия, если фильтр подключен как префильтр,onAfterAction(Event $event)— выполняется после действия, если фильтр подключен как постфильтр.
В базовом классе оба метода-обработчика пустые. Параметры события содержат действие action и контроллер controller, у onAfterAction также результат действия result.
Если наследник объявляет свой конструктор, вызовите в нем parent::__construct(). Конструктор Base создает коллекцию ошибок, без нее методы getErrors и addErrors не работают.
Остановить действие
Чтобы остановить действие, добавьте ошибку защищенным методом addError или addErrors и верните из onBeforeAction объект EventResult с типом EventResult::ERROR. В параметре handler передайте сам фильтр, например new EventResult(EventResult::ERROR, null, null, $this).
Контроллер не выполняет действие, если тип хотя бы одного результата не EventResult::SUCCESS. Обработчик, который вернул не EventResult, а другое непустое значение, например true или массив, тоже останавливает действие. EventManager превращает такое значение в результат с типом EventResult::UNDEFINED. Чтобы пропустить действие, верните null.
Контроллер забирает ошибки фильтра методом getErrors, только если фильтр передан в параметре handler.
Постфильтры
Постфильтры выполняются и тогда, когда префильтр остановил действие. Результаты onAfterAction и ошибки постфильтров контроллер не собирает. Изменить результат действия постфильтр может через параметр события result.