Drupal 8  8.0.2
Routing API

Data Structures

interface  RouteMatchInterface

Detailed Description

Route page requests to code based on URLs.

Overview and terminology

The Drupal routing system defines how Drupal responds to URL requests that the web server passes on to Drupal. The routing system is based on the Symfony framework. The central idea is that Drupal subsystems and modules can register routes (basically, URL paths and context); they can also register to respond dynamically to routes, for more flexibility. When Drupal receives a URL request, it will attempt to match the request to a registered route, and query dynamic responders. If a match is made, Drupal will then instantiate the required classes, gather the data, format it, and send it back to the web browser. Otherwise, Drupal will return a 404 or 403 response.

The following sections of this topic provide an overview of the routing API. For more detailed information, see https://www.drupal.org/developing/api/8/routing

Registering simple routes

To register a route, add lines similar to this to a module_name.routing.yml file in your top-level module directory:

path: '/admin/reports/dblog'
_controller: '\Drupal\dblog\Controller\DbLogController::overview'
_title: 'Recent log messages'
_permission: 'access site reports'

Some notes:

See https://www.drupal.org/node/2092643 for more details about *.routing.yml files, and https://www.drupal.org/node/2122201 for information on how to set up dynamic routes. The Events topic is also relevant to dynamic routes.

Defining routes with placeholders

Some routes have placeholders in them, and these can also be defined in a module_name.routing.yml file, as in this example from the Block module:

path: '/admin/structure/block/manage/{block}'
_entity_form: 'block.default'
_title: 'Configure block'
_entity_access: 'block.update'

In the path, '{block}' is a placeholder - it will be replaced by the ID of the block that is being configured by the entity system. See the Entity API topic for more information.

Route controllers for simple routes

For simple routes, after you have defined the route in a *.routing.yml file (see Registering simple routes above), the next step is to define a page controller class and method. Page controller classes do not necessarily need to implement any particular interface or extend any particular base class. The only requirement is that the method specified in your *.routing.yml file returns:

If the route has placeholders (see Defining routes with placeholders above) the placeholders will be passed to the method (using reflection) by name. For example, the placeholder '{myvar}' in a route will become the $myvar parameter to the method.

Additionally, if a parameter is typed to one of the following special classes the system will pass those values as well.

Most controllers will need to display some information stored in the Drupal database, which will involve using one or more Drupal services (see the Services and container topic ). In order to properly inject services, a controller should implement ; simple controllers can do this by extending the class. See for a straightforward example of a controller class.