Структура маршрутов

Маршруты, объявляемые в *.routing.yml могут содержать следующие свойства:

  • path: (обязательно) Путь маршрута, должен начинаться со слеша path: '/example'. Понимает динамически части, заключенные в фигурные скобки (например: path: '/foo/{argument}/bar').
  • defaults:
    • Обязательный параметр. Должен быть один из перечисленных:
      • _controller: Значение типа callable (callback-функция):
        • Class:method: В формате \Drupal\[module name]\Controller\[ClassName]::[method], например _controller: '\Drupal\foo\Controller\FooController::build'.

          В данном случае Drupal вызовет метод build() класса FooController из неймспейса \Drupal\foo\Controller.

        • Сервис: Позволяет формировать значение из сервиса. Значение задаётся в формате mymodule.service_name:[method], где mymodule.service_name - название сервиса, а [method] - название метода сервиса, который необходимо вызвать. Например _controller: 'mymodule.service_name:build'.

      • _form: Класс, реализующий Drupal\Core\Form\FormInterface.
      • _entity_view: Значение в формате [entity_type].[view_mode]. Маршрут найдёт сущность в пути и отрендерит её в указанном формате отображения. Например _entity_view: node.teaser.
      • _entity_list: Значение в формате [entity_type]. Выводит список сущностей указанного типа при помощи EntityListController данной сущности. Например _entity_list: user выведет список всех пользователей на сайте.
      • _entity_form: Значение в формате [entity_type].[form_view_mode]. Выведет форму редактирования сущности указанного типа, в определенном формате отображения формы. Например _entity_form: node.default выведет форму редактирования материала в стандартном режиме отображения формы.
      • _route: Название маршрута, чьим алиасом вы хотите сделать данный маршрут. Например _route: views.files.page_1.
    • Опциональные параметры.
      • _title: Заголовок страницы на английском языке. Данное значение будет обработано t().
      • _title_arguments: Дополнительные аргументы, передаваемые с заголовком в t().
      • _title_context: Контекст, передаваемый с заголовком в t().
      • _title_callback: Значение типа callable, которое возвращает значение для заголовка. В данном случае, перевод значения ложится на callback-функцию.
  • methods: (опционально) В дополнение к пути, вы можете ограничить типы запросов, на который будет реагировать маршрут. Значение должно быть в виде массива с перечислением всех допустимых типов запроса. Например methods: [GET, POST, UPDATE, DELETE].
  • requirements: (обязательно) Определяет, какие условия должны быть удовлетворены, для того чтобы получить доступ к маршруту. Должно быть одно или более значений (все они должны пройти успешно).
    • _permission: Строковое значение прав доступа, например _permission: 'access content'. Может принимать несколько значений разделяемых запятой , (логический оператор OR) (например: _permissions: 'access content,access user profiles) или плюсом + (логический оператор AND) (например: _permissions: 'acess content+access user').
    • _role: Строковое значение роли, например _role: 'administrator'. Вы также можете использовать указание нескольких ролей, разделяя их запятой , (логический оператор OR), или плюсом + (логический оператор AND). Рекомендуется использовать _permission, вместо _role, так как на различных сайтах роли могут иметь различные настройки и смыслы.
    • _access: Установите значение равное 'TRUE', чтобы не иметь никаких проверок и результат отдавался при любых условиях.
    • _entity_access: Значение в формате [entity_type].[operation]. Доступ будет предоставлен только если пользователь проходит проверки определенных прав, конкретного типа сущности. Например _entity_access: menu.edit.
    • _format: Производит проверку типа запроса. Например, указав _format: json, маршрут будет обрабатываться, только если указать ?_format=json при обращении по пути маршрута.
    • _content_type_format: Производит проверку по значению заголовка запроса Content-Type. Например, если зададите _content_type_format: json, то маршрут отработает только если при запросе был передан заголовок Content-Type: application/json.
    • _custom_access: Позволяет задать метод, который будет вызван для проверки прав доступа. Например _custom_access: '\Drupal\foo\Controller\FooController::access'
    • _module_dependencies: Производит проверку по модулю. Вы также можете использовать указание нескольких модулей, разделяя их запятой , (логический оператор OR), или плюсом + (логический оператор AND). Если указанный модуль отключен, то маршрут будет недоступен. Если модуль имеет зависимости, они также автоматически подразумевают проверку, поэтому нет никакого смысла указывать все зависимости.
    • _csrf_token: Значение равное 'TRUE' произведет проверку X-CSRF-Token из заголовка запроса, для проверки, является ли запрос валидным. Используйте, для того чтобы убедиться что запрос валидный и не изменен.
    • Любой другой существующий Access Check сервис. Для более подробной информации обратитесь к разделу контроля доступа маршрутов.
  • options: (опционально) Дополнительные настройки, с которыми маршрут должен взаимодействовать. Распространенные:
    • _admin_route: Помечает данный маршрут как часть административного интерфейса. Для всех маршрутов начинающихся с /admin, данное значение автоматически устанавливается в 'TRUE'.
    • _auth: Доступные способы авторизации для маршрута. По умолчанию доступны все варианты авторизации с значением global. Данное значение ограничивает варианты авторизации только для указанных. Например _auth: ['basic_auth', 'cookie']. Разработчики могут объявлять свои собственные способы авторизации при помощи Authentication API.
    • _maintenance_access: Значение равное 'TRUE' позволяет отрабатывать данному маршруту в режиме обслуживания.
    • no_cache: Значение равное 'TRUE' отключает кеширование ответа по этому маршруту.
    • parameters: TODO.

Примеры

Комплексный пример маршрутов

foo.routing.yml

foo.render:
  path: '/book'
  defaults:
    _controller: '\Drupal\foo\Controller\FooController::fooRender'
  requirements:
    _permission: 'access content'

foo.export:
  path: '/foo/export/{type}/{node}'
  defaults:
    _controller: '\Drupal\foo\Controller\FooController::fooExport'
  requirements:
    _permission: 'access printer-friendly version'
    _entity_access: 'node.view'
  options:
    _admin_route: TRUE

Передача аргументов в контроллер

foo.content:
  path: '/example' 
  defaults: 
    _controller: '\Drupal\foo\Controller\FooController::content' 
    custom_arg: 17
  requirements: 
    _permission: 'access content' 

Данное значение будет передано методу в качестве аргумента.

  public function content(Request $request, $custom_arg) {
    // $custom_arg == 17.
  }

Изменения в релизах

  • Drupal 9.2.0 (02.06.2021): Параметр _entity_bundles помечен устаревшим.

Помогите нам сделать документацию лучше!

Вся документация Druki с отрытым исходным кодом. Нашли ошибку или неточность? Создайте pull request.

Редактировать текущий документ Обсудить улучшение

Или узнайте как контрибутить.