[!!!][FEATURE] Introduce Backend Routing
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / master / Feature-65493-BackendRouting.rst
1 =========================================
2 Feature: #58621 - Unified Backend Routing
3 =========================================
4
5 Description
6 ===========
7
8 A new Routing component was added to the TYPO3 Backend which handles addressing different calls / modules inside TYPO3.
9
10 A Route is the smallest entity consisting of a path (e.g. "/records/edit/") as well as an identifier for addressing
11 the route, and the information about how to dispatch the route to a PHP controller.
12
13 A Route can be a module, wizard or any page inside the TYPO3 Backend. The Router contains the public API for matching
14 paths to fetch a Route, and is resolved inside the RequestHandler of the Backend.
15
16 The entry point for Routes is typo3/index.php?route=myroute&token=.... The main RequestHandler for all Backend requests
17 detects where a route parameter from the server is given and uses this as the route identifier and then resolves to a
18 controller defined inside the Route.
19
20 Routes are defined inside the file "Configuration/Backend/Routes.php" of any extension.
21
22 Example of a Configuration/Backend/Routes.php file:
23
24 .. code-block:: php
25
26         return [
27                 'myRouteIdentifier' => [
28                         'path' => '/document/edit',
29                         'controller' => Acme\MyExtension\Controller\MyExampleController::class
30                 ]
31         ];
32
33 The controller to be called receives a PSR-7 compliant Request object, and returns a PSR-7 Response object.
34 The UriBuilder generates any kind of URL for the Backend, may it be a module, a typical route or an AJAX call. The
35 UriBuilder returns a PSR-7-conform Uri object that can be casted to string when needed.
36
37 Usage:
38
39 .. code-block:: php
40
41         $uriBuilder = GeneralUtility::makeInstance(UriBuilder::class);
42         $uri = $uriBuilder->buildUriFromRoute('myRouteIdentifier', array('foo' => 'bar'));
43
44 See http://wiki.typo3.org/Blueprints/BackendRouting for more details.
45
46 Impact
47 ======
48
49 Handling of existing modules works the same as before and fully transparent. Any existing registration of entrypoints
50 can be moved to the new registration file in Configuration/Backend/Routes.php.