annotate core/lib/Drupal/Core/Routing/routing.api.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 4c8ae668cc8c
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 /**
Chris@0 4 * @file
Chris@0 5 * Hooks and documentation related to the routing system.
Chris@0 6 */
Chris@0 7
Chris@0 8 /**
Chris@0 9 * @defgroup routing Routing API
Chris@0 10 * @{
Chris@0 11 * Route page requests to code based on URLs.
Chris@0 12 *
Chris@0 13 * @section sec_overview Overview and terminology
Chris@0 14 * The Drupal routing system defines how Drupal responds to URL requests that
Chris@0 15 * the web server passes on to Drupal. The routing system is based on the
Chris@0 16 * @link http://symfony.com Symfony framework. @endlink The central idea is
Chris@0 17 * that Drupal subsystems and modules can register routes (basically, URL
Chris@0 18 * paths and context); they can also register to respond dynamically to
Chris@0 19 * routes, for more flexibility. When Drupal receives a URL request, it will
Chris@0 20 * attempt to match the request to a registered route, and query dynamic
Chris@0 21 * responders. If a match is made, Drupal will then instantiate the required
Chris@0 22 * classes, gather the data, format it, and send it back to the web browser.
Chris@0 23 * Otherwise, Drupal will return a 404 or 403 response.
Chris@0 24 *
Chris@0 25 * The following sections of this topic provide an overview of the routing API.
Chris@0 26 * For more detailed information, see
Chris@0 27 * https://www.drupal.org/developing/api/8/routing
Chris@0 28 *
Chris@0 29 * @section sec_register Registering simple routes
Chris@0 30 * To register a route, add lines similar to this to a module_name.routing.yml
Chris@0 31 * file in your top-level module directory:
Chris@0 32 * @code
Chris@0 33 * dblog.overview:
Chris@0 34 * path: '/admin/reports/dblog'
Chris@0 35 * defaults:
Chris@0 36 * _controller: '\Drupal\dblog\Controller\DbLogController::overview'
Chris@0 37 * _title: 'Recent log messages'
Chris@0 38 * requirements:
Chris@0 39 * _permission: 'access site reports'
Chris@0 40 * @endcode
Chris@0 41 * Some notes:
Chris@0 42 * - The first line is the machine name of the route. Typically, it is prefixed
Chris@0 43 * by the machine name of the module that defines the route, or the name of
Chris@0 44 * a subsystem.
Chris@0 45 * - The 'path' line gives the URL path of the route (relative to the site's
Chris@0 46 * base URL). Generally, paths in Drupal are treated as case-insensitive,
Chris@0 47 * which overrides the default Symfony behavior. Specifically:
Chris@0 48 * - If different routes are defined for /example and /EXAmplE, the exact
Chris@0 49 * match is respected.
Chris@0 50 * - If there is no exact match, the route falls back to a case-insensitive
Chris@0 51 * match, so /example and /EXAmplE will return the same page.
Chris@0 52 * Relying on case-sensitive path matching is not recommended because it
Chris@0 53 * negatively affects user experience, and path aliases do not support case-
Chris@0 54 * sensitive matches. The case-sensitive exact match is currently supported
Chris@0 55 * only for backwards compatibility and may be deprecated in a later release.
Chris@0 56 * - The 'defaults' section tells how to build the main content of the route,
Chris@0 57 * and can also give other information, such as the page title and additional
Chris@0 58 * arguments for the route controller method. There are several possibilities
Chris@0 59 * for how to build the main content, including:
Chris@0 60 * - _controller: A callable, usually a method on a page controller class
Chris@0 61 * (see @ref sec_controller below for details).
Chris@0 62 * - _form: A form controller class. See the
Chris@0 63 * @link form_api Form API topic @endlink for more information about
Chris@0 64 * form controllers.
Chris@0 65 * - _entity_form: A form for editing an entity. See the
Chris@0 66 * @link entity_api Entity API topic @endlink for more information.
Chris@0 67 * - The 'requirements' section is used in Drupal to give access permission
Chris@0 68 * instructions (it has other uses in the Symfony framework). Most
Chris@0 69 * routes have a simple permission-based access scheme, as shown in this
Chris@0 70 * example. See the @link user_api Permission system topic @endlink for
Chris@0 71 * more information about permissions.
Chris@0 72 *
Chris@0 73 * See https://www.drupal.org/node/2092643 for more details about *.routing.yml
Chris@0 74 * files, and https://www.drupal.org/node/2122201 for information on how to
Chris@0 75 * set up dynamic routes. The @link events Events topic @endlink is also
Chris@0 76 * relevant to dynamic routes.
Chris@0 77 *
Chris@0 78 * @section sec_placeholders Defining routes with placeholders
Chris@0 79 * Some routes have placeholders in them, and these can also be defined in a
Chris@0 80 * module_name.routing.yml file, as in this example from the Block module:
Chris@0 81 * @code
Chris@0 82 * entity.block.edit_form:
Chris@0 83 * path: '/admin/structure/block/manage/{block}'
Chris@0 84 * defaults:
Chris@0 85 * _entity_form: 'block.default'
Chris@0 86 * _title: 'Configure block'
Chris@0 87 * requirements:
Chris@0 88 * _entity_access: 'block.update'
Chris@0 89 * @endcode
Chris@0 90 * In the path, '{block}' is a placeholder - it will be replaced by the
Chris@0 91 * ID of the block that is being configured by the entity system. See the
Chris@0 92 * @link entity_api Entity API topic @endlink for more information.
Chris@0 93 *
Chris@0 94 * @section sec_controller Route controllers for simple routes
Chris@0 95 * For simple routes, after you have defined the route in a *.routing.yml file
Chris@0 96 * (see @ref sec_register above), the next step is to define a page controller
Chris@0 97 * class and method. Page controller classes do not necessarily need to
Chris@0 98 * implement any particular interface or extend any particular base class. The
Chris@0 99 * only requirement is that the method specified in your *.routing.yml file
Chris@0 100 * returns:
Chris@0 101 * - A render array (see the
Chris@0 102 * @link theme_render Theme and render topic @endlink for more information).
Chris@0 103 * This render array is then rendered in the requested format (HTML, dialog,
Chris@0 104 * modal, AJAX are supported by default). In the case of HTML, it will be
Chris@0 105 * surrounded by blocks by default: the Block module is enabled by default,
Chris@0 106 * and hence its Page Display Variant that surrounds the main content with
Chris@0 107 * blocks is also used by default.
Chris@0 108 * - A \Symfony\Component\HttpFoundation\Response object.
Chris@0 109 * As a note, if your module registers multiple simple routes, it is usual
Chris@0 110 * (and usually easiest) to put all of their methods on one controller class.
Chris@0 111 *
Chris@0 112 * If the route has placeholders (see @ref sec_placeholders above) the
Chris@0 113 * placeholders will be passed to the method (using reflection) by name.
Chris@0 114 * For example, the placeholder '{myvar}' in a route will become the $myvar
Chris@0 115 * parameter to the method.
Chris@0 116 *
Chris@0 117 * Additionally, if a parameter is typed to one of the following special classes
Chris@0 118 * the system will pass those values as well.
Chris@0 119 *
Chris@0 120 * - \Symfony\Component\HttpFoundation\Request: The raw Symfony request object.
Chris@0 121 * It is generally only useful if the controller needs access to the query
Chris@0 122 * parameters of the request. By convention, this parameter is usually named
Chris@0 123 * $request.
Chris@0 124 * - \Psr\Http\Message\ServerRequestInterface: The raw request, represented
Chris@0 125 * using the PSR-7 ServerRequest format. This object is derived as necessary
Chris@0 126 * from the Symfony request, so if either will suffice the Symfony request
Chris@0 127 * will be slightly more performant. By convention this parameter is usually
Chris@0 128 * named $request.
Chris@0 129 * - \Drupal\Core\Routing\RouteMatchInterface: The "route match" data from
Chris@0 130 * this request. This object contains various standard data derived from
Chris@0 131 * the request and routing process. Consult the interface for details.
Chris@0 132 *
Chris@0 133 * Most controllers will need to display some information stored in the Drupal
Chris@0 134 * database, which will involve using one or more Drupal services (see the
Chris@0 135 * @link container Services and container topic @endlink). In order to properly
Chris@0 136 * inject services, a controller should implement
Chris@0 137 * \Drupal\Core\DependencyInjection\ContainerInjectionInterface; simple
Chris@0 138 * controllers can do this by extending the
Chris@0 139 * \Drupal\Core\Controller\ControllerBase class. See
Chris@0 140 * \Drupal\dblog\Controller\DbLogController for a straightforward example of
Chris@0 141 * a controller class.
Chris@0 142 *
Chris@0 143 * @}
Chris@0 144 */