www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Routing/routing.api.php

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