Controller — базовый класс контроллера

Пространство имен: Bitrix\Main\Engine

Модуль: main — подключать отдельно не нужно

Доступно с версии: 20.5.400

Когда использовать

Класс Controller — родитель контроллеров, которые обрабатывают AJAX-запросы BX.ajax.runAction, REST-вызовы и консольные команды. Свой контроллер создают наследником. Действие — публичный метод с суффиксом Action, например listAction. Ядро подбирает аргументы метода из параметров запроса по именам и возвращает результат клиенту в JSON.

namespace Vendor\Units\Controller;

use Bitrix\Main\Engine\Controller;

class Unit extends Controller
{
    public function configureActions()
    {
        return [
            'list' => [
                '-prefilters' => [\Bitrix\Main\Engine\ActionFilter\Authentication::class],
            ],
        ];
    }

    public function listAction(int $limit = 20): array
    {
        return ['items' => []];
    }
}

Метод run выполняет действие по шагам.

  1. Находит действие по имени и создает объект Action.
  2. Подключает префильтры и постфильтры. По умолчанию это проверка авторизации, проверка метода HTTP (GET или POST) и проверка CSRF-токена.
  3. Отправляет событие onBeforeAction и выполняет действие.
  4. Отправляет событие onAfterAction и возвращает результат.

Метод не выбрасывает исключения, а собирает их вместе с ошибками в коллекцию. Коллекцию возвращает метод getErrors.

Подробнее — в статье Контроллеры.

Методы класса

Действия и выполнение

Метод Описание С версии
__construct Создает контроллер
configureActions Задает фильтры и классы действий
getConfigurationOfActions Возвращает настройки действий
listNameActions Возвращает имена всех действий
run Выполняет действие
forward Выполняет действие другого контроллера
getCurrentAction Возвращает выполняемое действие
generateActionMethodName Возвращает имя метода действия
getFullEventName Возвращает полное имя события контроллера
finalizeResponse Меняет ответ перед отправкой клиенту
redirectTo Возвращает ответ с переадресацией
convertKeysToCamelCase Переводит ключи массива в camelCase

Запрос и окружение

Метод Описание С версии
getRequest Возвращает запрос
getSourceParametersList Возвращает источники параметров действия
setSourceParametersList Задает источники параметров действия
getUnsignedParameters Возвращает расшифрованные параметры компонента
getCurrentUser Возвращает текущего пользователя
setCurrentUser Задает текущего пользователя
getScope Возвращает область вызова
setScope Задает область вызова
getModuleId Возвращает модуль контроллера
isLocatedUnderPsr4 Проверяет, лежит ли файл класса по правилам PSR-4
getActionUri Возвращает адрес действия для AJAX
className Возвращает полное имя класса

Автоподстановка параметров

Метод Описание С версии
getAutoWiredParameters Возвращает правила автоподстановки объектов в аргументы действий
getPrimaryAutoWiredParameter Возвращает основное правило автоподстановки
getDefaultAutoWiredParameters Возвращает правила автоподстановки по умолчанию

Ошибки

Метод Описание С версии
getErrors Возвращает ошибки
hasErrors Проверяет, есть ли ошибки
getErrorByCode Возвращает ошибку по коду

Защищенные методы для наследника

Наследник переопределяет защищенные методы, чтобы изменить поведение, или вызывает их в действиях.

Метод Назначение
init Конструктор вызывает его в конце. Метод читает настройки действий. Наследник переопределяет его, чтобы подготовить контроллер, и вызывает parent::init()
getDefaultPreFilters, getDefaultPostFilters Возвращают фильтры по умолчанию для всех действий. Переопределяют, чтобы сменить фильтры
processBeforeAction Метод run вызывает его перед действием. Значение false отменяет действие
processAfterAction Метод run вызывает его после действия. Значение, отличное от null, заменяет результат
addError, addErrors Добавляют ошибки в коллекцию. Вызывают в действиях
renderComponent, renderComponentAjax, renderView, renderExtension Возвращают ответ с HTML компонента, представления или расширения. Вызывают в действиях

Константы

Константа Значение Описание
SCOPE_AJAX, SCOPE_REST, SCOPE_CLI 'ajax', 'rest', 'cli' Области вызова для setScope
EVENT_ON_BEFORE_ACTION, EVENT_ON_AFTER_ACTION 'onBeforeAction', 'onAfterAction' Короткие имена событий для getFullEventName
ERROR_REQUIRED_PARAMETER 'MAIN_CONTROLLER_22001' Код ошибки из исключения ArgumentNullException
ERROR_UNKNOWN_ACTION 'MAIN_CONTROLLER_22002' Контроллер не использует константу. Ошибка неизвестного действия получает код 22002
EXCEPTION_UNKNOWN_ACTION 22002 Код исключения и ошибки неизвестного действия
INTERNAL_ERROR_MESSAGE 'Internal server error.' Текст ошибки вместо текста исключения вне режима отладки. В более ранних версиях, например 26.150.0, константы нет, и ошибка содержит текст исключения

Смотрите также