bitrix-controllers

name

bitrix-controllers

description

Покрывает контроллеры D7 на базе Bitrix\Main\Engine\Controller и JsonController — actions, автосвязывание параметров, фильтры ActionFilter (Authentication, Csrf, HttpMethod, Scope, CloseSession, ContentType), ошибки через addError/ErrorCollection, configureActions, рендер и JSON-ответы. Применяется при реализации AJAX/REST-эндпоинтов, внутренних API и ajax-экшенов компонентов через Controllerable. Ключевые термины — Controller, action, ActionFilter, Csrf, runAction, addError, configureActions, ajax endpoint, REST.

Контроллеры Bitrix

Где лежат и как называются

• Файлы: /local/modules/<vendor>.<module>/lib/Infrastructure/Controller/<Name>.php.
• Неймспейс (по умолчанию): \Vendor\Module\Infrastructure\Controller\<Name>.
• Публичный URL для AJAX: /bitrix/services/main/ajax.php?action=vendor:module.<name>.<action>.
• URL можно переписать маршрутом (см. bitrix-routing).

Настройка пространства имён — в /local/modules/vendor.module/.settings.php:

'controllers' => [
    'value' => [
        'defaultNamespace' => '\\Vendor\\Module\\Infrastructure\\Controller',
        'namespaces' => [
            '\\Vendor\\Module\\Infrastructure\\Controller\\Web' => 'web',
        ],
        'restIntegration' => ['enabled' => true], // для REST
    ],
    'readonly' => true,
],

Доступ к Web\PostController::getAction → ?action=vendor:module.web.post.get.

Минимальный контроллер

<?php declare(strict_types=1);

namespace Vendor\Module\Infrastructure\Controller;

use Bitrix\Main\Engine\Controller;
use Bitrix\Main\Engine\ActionFilter;
use Bitrix\Main\Error;
use Vendor\Module\Application\Service\PostService;

final class Post extends Controller
{
    public function __construct(
        private readonly PostService $postService,
    ) {
        parent::__construct();
    }

    public function configureActions(): array
    {
        return [
            'get' => [
                '+prefilters' => [new ActionFilter\HttpMethod([ActionFilter\HttpMethod::])],
                 => [::], 
            ],
             => [
                 => [
                     ([::]),
                     (),
                ],
            ],
        ];
    }

     {
         = ->postService->();
         ( === )
        {
            ->( (, ));
             [];
        }

         [ => ];
    }

     {
         = ->postService->(, );

         (!->())
        {
            ->(->());
             [];
        }

         [ => ->()];
    }
}

Автосвязывание параметров действий

Параметры действия собираются движком в следующем порядке:

1. Скалярные типы (int, string, bool, float, array) → из GET/POST/FILES.
2. Объекты-сервисы → из ServiceLocator по имени/типу.
3. HttpRequest, Session, CurrentUser → из контекста.
4. Request DTO с атрибутом #[Bitrix\Main\Validation\Engine\ValidationParameter] → маппинг из запроса + валидация (см. bitrix-validation).
5. ORM-объекты, если действие принимает EntityObject — загружаются по id.

Отсутствие обязательного параметра → автоматическая ошибка.

Фильтры действий

Предустановленные:

• ActionFilter\Authentication — требует авторизованного пользователя.
• ActionFilter\Csrf (по умолчанию включён на POST) — проверка sessid/X-Bitrix-Csrf-Token.
• ActionFilter\HttpMethod([...]) — ограничение по методу.
• ActionFilter\CloseSession — закрывает сессию перед действием (параллельные AJAX).
• ActionFilter\ContentType(['application/json']) — допустимый Content-Type.
• ActionFilter\Scope($scope) — ограничивает вызов конкретным scope (ajax/rest/cli).

Формат в configureActions():

'default' => [
    'prefilters' => [...],   // полностью заменить список
    '+prefilters' => [...],  // добавить
    '-prefilters' => [...],  // удалить (по FQCN)
    'postfilters' => [...],
],

Ошибки

• $this->addError(new \Bitrix\Main\Error('msg', 'CODE', ['key' => 'value']));
• $this->addErrors($result->getErrors());
• Никогда не бросай исключения наружу ради «обычных» пользовательских ошибок — они ухудшают UX и сложнее тестируются. Используй Result + Error.
• Ответ с ошибками автоматически получает status: 'error' и массив errors.

Типы ответов

• array → JSON: { "status": "success", "data": [...] }.
• null → { "status": "success" } без данных.
• Bitrix\Main\HttpResponse — кастомный ответ (заголовки, статус, тело).
• Bitrix\Main\Engine\Response\Html / Json / Redirect / AjaxJson.
• Bitrix\Main\Engine\Response\Component — рендер компонента.
• Bitrix\Main\Engine\Response\Component\Ajax — JSON + рендер компонента.
• Bitrix\Main\Engine\Response\BFile / File / HttpResponseFile — отдача файла.

Помощники контроллера:

return $this->renderView('list', ['items' => $items]);
// => /local/modules/vendor.module/views/list.php

return $this->renderComponent('vendor:post.list', '.default', ['IBLOCK_ID' => 12]);

return $this->renderExtension('vendor.post.list', ['items' => $items]);

Scope (AJAX / REST / CLI)

• AJAX: вызов через /bitrix/services/main/ajax.php?action=... или BX.ajax.runAction('...', {}) из JS. Автоматически доступен если контроллер объявлен и есть controllers в .settings.php.
• REST: требуется restIntegration.enabled = true в настройках + установленный модуль rest.
• CLI: контроллер можно вызвать из команды, если есть ActionFilter\Scope.

Разные сценарии — разные наборы фильтров. Пример переопределения по scope:

public function configureActions(): array
{
    return [
        'get' => [
            'prefilters' => [
                new ActionFilter\Scope(ActionFilter\Scope::AJAX),
                new ActionFilter\HttpMethod([ActionFilter\HttpMethod::METHOD_GET]),
            ],
        ],
    ];
}

Вызов с фронта

BX.ajax.runAction('vendor:module.post.create', {
    data: { title: 'Title', body: 'Body' },
}).then((response) => {
    console.log(response.data);
});

Для REST — BX.rest.callMethod('vendor.module.post.create', {...}).

Чек-лист

• Контроллер тонкий: вызывает сервис, возвращает DTO/массив.
• Указаны HttpMethod и Authentication/Csrf там, где нужно.
• Вход валидируется через Request DTO + #[ValidationParameter] (см. bitrix-validation).
• Ошибки возвращаются через $this->addError(...), а не через исключения.
• Возвращаемый тип явный: array, HttpResponse или renderXxx.
• Зависимости инжектятся через конструктор; сервисы зарегистрированы в ServiceLocator.