Newer
Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
<?php
/**
* @file
* Hooks and documentation related to the routing system.
*/
/**
* @defgroup routing Routing API
* @{
* Route page requests to code based on URLs.
*
* @section sec_overview 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
* @link http://symfony.com Symfony framework. @endlink 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
*
* @section sec_register 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:
* @code
* dblog.overview:
* path: '/admin/reports/dblog'
* defaults:
* _controller: '\Drupal\dblog\Controller\DbLogController::overview'
* _title: 'Recent log messages'
* requirements:
* _permission: 'access site reports'
* @endcode
* Some notes:
* - The first line is the machine name of the route. Typically, it is prefixed
* by the machine name of the module that defines the route, or the name of
* a subsystem.
* - The 'path' line gives the URL path of the route (relative to the site's
* base URL). Generally, paths in Drupal are treated as case-insensitive,
* which overrides the default Symfony behavior. Specifically:
* - If different routes are defined for /example and /EXAmplE, the exact
* match is respected.
* - If there is no exact match, the route falls back to a case-insensitive
* match, so /example and /EXAmplE will return the same page.
* Relying on case-sensitive path matching is not recommended because it
* negatively affects user experience, and path aliases do not support case-
* sensitive matches. The case-sensitive exact match is currently supported
* only for backwards compatibility and may be deprecated in a later release.
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
* - The 'defaults' section tells how to build the main content of the route,
* and can also give other information, such as the page title and additional
* arguments for the route controller method. There are several possibilities
* for how to build the main content, including:
* - _controller: A callable, usually a method on a page controller class
* (see @ref sec_controller below for details).
* - _form: A form controller class. See the
* @link form_api Form API topic @endlink for more information about
* form controllers.
* - _entity_form: A form for editing an entity. See the
* @link entity_api Entity API topic @endlink for more information.
* - The 'requirements' section is used in Drupal to give access permission
* instructions (it has other uses in the Symfony framework). Most
* routes have a simple permission-based access scheme, as shown in this
* example. See the @link user_api Permission system topic @endlink for
* more information about permissions.
*
* 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 @link events Events topic @endlink is also
* relevant to dynamic routes.
*
* @section sec_placeholders 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:
* @code
* entity.block.edit_form:
* path: '/admin/structure/block/manage/{block}'
* defaults:
* _entity_form: 'block.default'
* _title: 'Configure block'
* requirements:
* _entity_access: 'block.update'
* @endcode
* 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
* @link entity_api Entity API topic @endlink for more information.
*
* @section sec_controller Route controllers for simple routes
* For simple routes, after you have defined the route in a *.routing.yml file
* (see @ref sec_register 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:
* - A render array (see the
* @link theme_render Theme and render topic @endlink for more information).
* This render array is then rendered in the requested format (HTML, dialog,
* modal, AJAX are supported by default). In the case of HTML, it will be
* surrounded by blocks by default: the Block module is enabled by default,
* and hence its Page Display Variant that surrounds the main content with
* blocks is also used by default.
* - A \Symfony\Component\HttpFoundation\Response object.
* As a note, if your module registers multiple simple routes, it is usual
* (and usually easiest) to put all of their methods on one controller class.
*
* If the route has placeholders (see @ref sec_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.
*
* - \Symfony\Component\HttpFoundation\Request: The raw Symfony request object.
* It is generally only useful if the controller needs access to the query
* parameters of the request. By convention, this parameter is usually named
* $request.
* - \Psr\Http\Message\ServerRequestInterface: The raw request, represented
* using the PSR-7 ServerRequest format. This object is derived as necessary
* from the Symfony request, so if either will suffice the Symfony request
* will be slightly more performant. By convention this parameter is usually
* named $request.
* - \Drupal\Core\Routing\RouteMatchInterface: The "route match" data from
* this request. This object contains various standard data derived from
* the request and routing process. Consult the interface for details.
*
* Most controllers will need to display some information stored in the Drupal
* database, which will involve using one or more Drupal services (see the
* @link container Services and container topic @endlink). In order to properly
* inject services, a controller should implement
* \Drupal\Core\DependencyInjection\ContainerInjectionInterface; simple
* controllers can do this by extending the
* \Drupal\Core\Controller\ControllerBase class. See
* \Drupal\dblog\Controller\DbLogController for a straightforward example of
* a controller class.
*
* @}
*/