Structure of routes

A route maps a URL path to a specific function or class. In Drupal, routes are defined in a your_module.routing.yml file located in your module's root directory.

Drupal version compatibility

• Modern: 11.x, 10.x
• Legacy: 9.x, 8.x (Standard routing remains the same, but excludes Drupal 11+ features like route aliases).

1. Prerequisites

Before defining routes, ensure your module follows the PSR-4 directory standard.

Typical structure

my_module/
├── my_module.info.yml
├── my_module.routing.yml    <-- Routes go here
└── src/
    ├── Controller/
    │   └── HelloController.php
    └── Form/
        └── MySettingsForm.php

Naming conventions

• File name: Must be {module_name}.routing.yml.
• Case logic: Module names are snake_case, while class names are PascalCase.

2. Anatomy of a route

Each route is identified by a machine name (e.g., my_module.route_name). Below are the properties available for each entry.

Required properties

Note: You can also define optional parameters at the end of your path. See "Optional Parameters" in Using parameters in routes.

Defaults: Output handlers (one required)

Defaults: Metadata (optional)

Requirements: Access & validation (optional)

Determines what conditions must be met to grant access to the route. All conditions must be met to gain access.

Options: System interaction (optional)

3. Annotated example

# Each route is defined by a machine name, in the form of my_module_name.route_name.

book.render:

# The path always starts with a leading forward-slash.

path: '/book'

# Defines the default properties of a route.

defaults:
# For page callbacks that return a render array use _controller.
_controller: '\Drupal\book\Controller\BookController::bookRender'

# Require a permission to access this route.

requirements:
_permission: 'access content'

book.export:

# This path takes dynamic arguments, which are enclosed in { }.

path: '/book/export/{type}/{node}'
defaults:
# This route returns a Response object so also uses _controller
_controller: '\Drupal\book\Controller\BookController::bookExport'
requirements:
_permission: 'access printer-friendly version'
# Ensure user has access to view the node passed in.
_entity_access: 'node.view'
options:
# Enable the admin theme for this route.
_admin_route: TRUE

4. Passing arguments to your code

Route alias

As of Drupal 11.x, a route can have an alias.

my_route.alias: alias: 'main_route' 

Passing arguments to controllers

All keys under the defaults section, which do not start with an underscore, will be passed in as arguments to the controller. Name your arguments appropriately for the arguments of the controller. For example a my_module_name.routing.yml file with the following:

example.content:
  path: '/example' 
  defaults: 
    _controller: '\Drupal\example\Controller\ExampleController::content' 
    custom_arg: 12
  requirements: 
    _permission: 'access content' 

Will pass on $custom_arg to the controller, so your content method can take $custom_arg:

// ...
public function content($custom_arg) {
// Now you can use $custom_arg (which will get 12 here).
}

Using parameters from the URL path

If your route defines parameters directly in the path (e.g., {op}), Drupal automatically passes these parameters as arguments to the controller method by matching their names.

Example:

entity.block.operation:
  path: '/admin/structure/block/manage/{block}/{op}'
  defaults:
    _controller: '\Drupal\block\Controller\BlockController::performOperation'
  requirements:
    _entity_access: 'block.{op}'
    op: 'enable|disable'

In this example, the controller method will receive both $block and $op parameters extracted from the URL:

public function performOperation($block, $op) {
  if ($op === 'enable') {
    // Enable block logic
  }
  elseif ($op === 'disable') {
    // Disable block logic
  }
}

Fixed parameters via defaults vs dynamic parameters via URL

Fixed operation parameter

When the operation is fixed and tied to a specific route (e.g., always enabling a block), you specify the parameter in defaults. The controller receives this fixed value without needing to parse the URL:

entity.block.enable:
  path: '/admin/structure/block/manage/{block}/enable'
  defaults:
    _controller: '\Drupal\block\Controller\BlockController::performOperation'
    op: enable

Dynamic operation parameter

When the operation is variable and part of the URL, you define it as a path parameter {op}. Drupal parses the URL and passes this value directly to the controller:

entity.block.operation:
  path: '/admin/structure/block/manage/{block}/{op}'
  defaults:
    _controller: '\Drupal\block\Controller\BlockController::performOperation'
  requirements:
    op: 'enable|disable'

Routing for Form

module_name.route_machine_name:
    path: '/{module_name}/personal-info'
    defaults:
        _form: 'Drupal\{module_name}\Form\InfoForm'
        _title: 'Personal information'
    requirements:    
        _permission : 'custom_module_permission'

Combine this with dynamic routes to get true flexibility.

5. Next steps

After modifying your routing.yml file, you must clear the routing cache for Drupal to recognize the changes: bash drush cache:rebuild.