Новое в контроллерах Bitrix Framework: фильтры и валидация

Привет! Сегодня мы расскажем, какие нововведения появились в контроллерах ядра за последнее время.

Для начала вспомним, что контроллеры — это часть MVC архитектуры, которая отвечает за обработку запроса и генерирование ответа.

Про MVC много чего написано, поэтому не будем акцентировать на этом внимание. Лучше вспомним, что контроллеры состоят из одного или нескольких действий.
А еще для действий контроллеров доступно автоматическое связывание. Мы уже рассказывали об этом тут. Если не читали, то рекомендую посмотреть. Так будет легче понимать то, о чем мы сегодня вам расскажем.

Часто возникает ситуация, когда нужно выполнить какой-либо код до или после выполнения действия контроллера. К примеру, если мы пишем действие создания задачи, то может быть уместно перед вызовом самого действия проверить, передан ли правильный заголовок Content-Type.
Такой код (выполняемый перед действием контроллера) мы разбиваем по классам и называем префильтрами. Код, который выполняется после действия контроллера — постфильтрами

Фильтры

Есть 2 способа конфигурировать (управлять префильтрами и постфильтрами) действия контроллера. Первый — переопределить метод configureActions:

<?php  use Bitrix\Main\Engine\ActionFilter\Authentication; use Bitrix\Main\Engine\Controller;  final class Entity extends Controller { public function configureActions() { return [ 'get' => [ 'prefilters' => [ new Authentication(), ], ], ]; }  public function getAction(string $id) { // ... } } 

Скоро будет доступен второй способ — конфигурация через атрибуты методов. Этот подход более современный и читаемый, но в то же время поддерживает всё, что можно сконфигурировать через configureActions:

<?php  use Bitrix\Main\Engine\ActionFilter\Attribute\Rule\Prefilters; use Bitrix\Main\Engine\ActionFilter\Authentication; use Bitrix\Main\Engine\Controller;  final class Entity extends Controller { #[Prefilters([ new Authentication() ])] public function getAction(string $id) { // ... } } 

Одновременное использование старого и нового вариантов недопустимо и будет встречено исключением Bitrix\Main\Engine\Exception\ActionConfigurationException.

Также поддерживаются дополняющие и вычитающие конструкции. Старый вариант через configureActions:

<?php  use Bitrix\Main\Engine\ActionFilter\Authentication; use Bitrix\Main\Engine\ActionFilter\Csrf; use Bitrix\Main\Engine\Controller;  final class Entity extends Controller { public function configureActions() { return [ 'get' => [ '+prefilters' => [ new Authentication(), ], '-prefilters' => [ new Csrf(), ], ], ]; }  public function getAction(string $id) { // ... } } 

Новый вариант через атрибуты:

<?php  use Bitrix\Main\Engine\ActionFilter\Attribute\Rule\DisablePrefilters; use Bitrix\Main\Engine\ActionFilter\Attribute\Rule\EnablePrefilters; use Bitrix\Main\Engine\ActionFilter\Authentication; use Bitrix\Main\Engine\ActionFilter\Csrf; use Bitrix\Main\Engine\Controller;  final class Entity extends Controller { #[EnablePrefilters([ new Authentication() ])] #[DisablePrefilters([ new Csrf() ])] public function getAction(string $id) { // ... } } 

И полностью аналогично для постфильтров:

<?php  use Bitrix\Main\Engine\ActionFilter\Attribute\Rule\DisablePostfilters; use Bitrix\Main\Engine\ActionFilter\Attribute\Rule\EnablePostfilters; use Bitrix\Main\Engine\ActionFilter\Attribute\Rule\Postfilters; use Bitrix\Main\Engine\ActionFilter\ClosureWrapper; use Bitrix\Main\Engine\ActionFilter\Cors; use Bitrix\Main\Engine\Controller;  final class Entity extends Controller { #[Postfilters([ new Cors(), ])] #[EnablePostfilters([ new Cors(), ])] #[DisablePostfilters([ new ClosureWrapper(), ])] public function getAction(string $id) { // ... } } 

Для удобства использования, чтобы не перечислять нужные пре- и постфильтры в массиве, можно использовать сразу же нужные атрибуты:

<?php  use Bitrix\Main\Engine\ActionFilter\Attribute\Rule\Authentication; use Bitrix\Main\Engine\Controller;  final class Entity extends Controller { #[Authentication()] public function getAction(string $id) { // ... } } 

Аргументы атрибутов идентичны аргументам самих экшн фильтров, за исключением последнего аргумента filterType. Он используется для дополнения или вычитания экшн фильтров.

На приведенном далее примере методы get и list будут иметь одинаковые префильтры:

<?php  use Bitrix\Main\Engine\ActionFilter\Attribute\Rule; use Bitrix\Main\Engine\ActionFilter\Attribute\Rule\DisablePrefilters; use Bitrix\Main\Engine\ActionFilter\Attribute\Rule\EnablePrefilters; use Bitrix\Main\Engine\ActionFilter\Authentication; use Bitrix\Main\Engine\ActionFilter\Csrf; use Bitrix\Main\Engine\ActionFilter\FilterType; use Bitrix\Main\Engine\Controller;  final class Entity extends Controller { #[EnablePrefilters([ new Authentication() ])] #[DisablePrefilters([ new Csrf() ])] public function getAction(string $id) { // ... }  #[Rule\Authentication(type: FilterType::EnablePrefilter)] #[Rule\Csrf(type: FilterType::DisablePrefilter)] public function listAction() { // ... } } 

Из коробки для всех имеющихся экшн фильтров, продублированы соответствующие атрибуты:

• Bitrix\Main\Engine\ActionFilter\Attribute\Rule\Authentication

• Bitrix\Main\Engine\ActionFilter\Attribute\Rule\CloseSession

• Bitrix\Main\Engine\ActionFilter\Attribute\Rule\ContentType

• Bitrix\Main\Engine\ActionFilter\Attribute\Rule\Cors

• Bitrix\Main\Engine\ActionFilter\Attribute\Rule\Csrf

• Bitrix\Main\Engine\ActionFilter\Attribute\Rule\HttpMethod

• Bitrix\Main\Engine\ActionFilter\Attribute\Rule\Scope

• Bitrix\Main\Engine\ActionFilter\Attribute\Rule\Token

Как это работает под капотом

Прежде всего, все атрибуты используют внутри себя привычные фильтры. Вот пример, как выглядит атрибут Cors:

<?php  declare(strict_types=1);  namespace Bitrix\Main\Engine\ActionFilter\Attribute\Rule;  use Attribute; use Bitrix\Main\Engine\ActionFilter\Attribute\FilterAttributeInterface; use Bitrix\Main\Engine\ActionFilter\FilterType;  #[Attribute(Attribute::TARGET_METHOD)] final class Cors implements FilterAttributeInterface { public function __construct( private readonly ?string $origin = null, private readonly ?bool $credentials = null, private readonly FilterType $type = FilterType::EnablePrefilter, ) {  }  public function getFilters(): array { if ($this->type->isNegative()) { return [\Bitrix\Main\Engine\ActionFilter\Cors::class]; }  return [new \Bitrix\Main\Engine\ActionFilter\Cors($this->origin, $this->credentials)]; }  public function getType(): FilterType { return $this->type; } } 

Вначале он принимает те параметры, которые принимает сам \Bitrix\Main\Engine\ActionFilter\Cors.

Далее, в каждом атрибуте есть параметр FilterType — он и определяет тип фильтра. Вот так он выглядит:

enum FilterType: string { case Prefilter = 'prefilters'; case Postfilter = 'postfilters';  case EnablePrefilter = '+prefilters'; case DisablePrefilter = '-prefilters';  case EnablePostfilter = '+postfilters'; case DisablePostfilter = '-postfilters';  public function isNegative(): bool { return in_array($this, [self::DisablePrefilter, self::DisablePostfilter], true); } } 

Как можно заметить, ключи аналогичны методу configureActions.

Поэтому, если в нашем примере мы захотим сделать так, чтобы CloseSession был выключен, то мы сделаем так:

class Task extends \Bitrix\Main\Engine\Controller { #[\Bitrix\Main\Engine\ActionFilter\Attribute\Rule\CloseSession(type: FilterType::DisablePrefilter)] public function getAction(int $id): ?array { // ...  return $task; } } 

Аналогично для постфильтров.

Если необходимо не выключить или включать заданные постфильтры и префильтры, то можно воспользоваться атрибутами \Bitrix\Main\Engine\ActionFilter\Attribute\Rule\Prefilters, \Bitrix\Main\Engine\ActionFilter\Attribute\Rule\Postfilters

class Task extends \Bitrix\Main\Engine\Controller { #[Prefilters([new Csrf(), new ContentType([ContentType::JSON])])] public function getAction(int $id): ?array { // ...  return $task; } } 

Обратите внимание, что будут применены ТОЛЬКО перечисленные префильтры, а дефолтные — проигнорируются. Аналогично с постфильтрами

Создание своих атрибутов префильтров

Для этого необходимо:

• Реализовать сам фильтр (наследник Base)

• Написать класс атрибута, реализовав интерфейс:

interface FilterAttributeInterface { /**  * @return (Base|string)[]  */ public function getFilters(): array;  public function getType(): FilterType; } 

Пример:

#[Attribute(Attribute::TARGET_METHOD)] class MyCustomFilter implements \Bitrix\Main\Engine\ActionFilter\Attribute\FilterAttributeInterface { public function __construct( private readonly array $args, private readonly FilterType $type = FilterType::EnablePrefilter, ) {  } public function getFilters(): array { return [new MyCustomBaseFilter($this->args)] }  public function getType(): FilterType { return $this->type; } } 

Валидация

Мы также упростили валидацию параметров в контроллерах. Новой валидации мы посвятили целую статью.

Ознакомьтесь с ней, если раньше не видели — это поможет лучше понимать то, что будет дальше.

Теперь же мы улучшили связку между контроллерами и валидацией.

Напомню, что раньше для использования валидации в действиях контроллера было необходимо создавать объект, который необходимо прокинуть в специальную обертку — \Bitrix\Main\Validation\Engine\AutoWire\ValidationParameter:

class UserController extends Controller {     public function getAutoWiredParameters()     {         return [             new \Bitrix\Main\Validation\Engine\AutoWire\ValidationParameter(                 CreateUserDto::class,                 fn() => CreateUserDto::createFromRequest($this->getRequest()),             ),         ];     }          public function createAction(CreateUserDto $dto): Result     {         // create logic ...     } } 

Теперь провалидировать входные данные можно и без явного указания \Bitrix\Main\Validation\Engine\AutoWire\ValidationParameter. Достаточно указать в действии контроллера атрибуты валидации для аргументов, в том числе скалярных.

Например:

 class UserController extends \Bitrix\Main\Engine\Controller { public function createAction( #[\Bitrix\Main\Validation\Rule\PhoneOrEmail] string $login, #[\Bitrix\Main\Validation\Rule\NotEmpty] string $password, #[\Bitrix\Main\Validation\Rule\NotEmpty] string $passwordRepeat ): array { // logic here } } 

Более того, можно как и раньше передать объект, но вместо регистрации через getAutoWiredParameters достаточно будет добавить ему атрибут Validatable:

 class UserController extends \Bitrix\Main\Engine\Controller { public function createAction( #[\Bitrix\Main\Validation\Rule\Recursive\Validatable] CreateUserDto $dto) : Result { // create logic ... } } 

Этот пакет уже готовится к выпуску внутри модуля main и совсем скоро (в этом релизе) его можно будет использовать в ваших проектах на базе Bitrix Framework.