[FrameworkBundle][Routing] Added doc for new "template", "redirect" shortcuts

Author: Jules Pietri

routing/redirect_in_config.rst

@@ -40,6 +40,13 @@ action to redirect to this new url:
                 path: /app
                 permanent: true
 
+        # or
+        homepage:
+            path: /
+            url_redirect: /app
+            defaults:
+                permanent: true
+
     .. code-block:: xml
 
         <!-- config/routes.xml -->
@@ -59,6 +66,11 @@ action to redirect to this new url:
                 <default key="path">/app</default>
                 <default key="permanent">true</default>
             </route>
+
+            <!-- or -->
+            <route id="homepage" path="/" url-redirect="path">/app">
+                <default key="permanent">true</default>
+            </route>
         </routes>
 
     .. code-block:: php
@@ -81,8 +93,17 @@ action to redirect to this new url:
                     'permanent' => true,
                 ])
             ;
+
+            // or
+            $routes->urlRedirect('homepage', '/', '/app)
+                ->permanent(true)
+            ;
         };
 
+.. versionadded:: 4.3
+
+    The "url redirect" shortcut has been introduced in Symfony 4.3.
+
 In this example, you configured a route for the ``/`` path and let the
 ``RedirectController`` redirect it to ``/app``. The ``permanent`` switch
 tells the action to issue a ``301`` HTTP status code instead of the default
@@ -115,6 +136,14 @@ action:
                 # ...and keep the original query string parameters
                 keepQueryParams: true
 
+        # or
+        admin:
+            path: /wp-admin
+            redirect: sonata_admin_dashboard
+            defaults:
+                permanent: true
+                keepQueryParams: true
+
     .. code-block:: xml
 
         <!-- config/routes.xml -->
@@ -135,6 +164,12 @@ action:
                 <!-- ...and keep the original query string parameters -->
                 <default key="keepQueryParams">true</default>
             </route>
+
+            <!-- or -->
+            <route id="admin" path="/wp-admin" redirect="sonata_admin_dashboard">
+                <default key="permanent">true</default>
+                <default key="keepQueryParams">true</default>
+            </route>
         </routes>
 
     .. code-block:: php
@@ -156,8 +191,18 @@ action:
                     'keepQueryParams' => true,
                 ])
             ;
+
+            // or
+            $routes->redirect('admin', '/wp-admin', 'sonata_admin_dashboard')
+                ->permanent(true)
+                ->keepQueryParams(true)
+            ;
         };
 
+.. versionadded:: 4.3
+
+    The ``redirect`` shortcut has been introduced in Symfony 4.3.
+
 .. caution::
 
     Because you are redirecting to a route instead of a path, the required
@@ -190,18 +235,17 @@ permanent redirects use ``308`` code instead of ``301``:
         # config/routes.yaml
 
         # redirects with the 308 status code
-        route_foo:
-            # ...
-            controller: Symfony\Bundle\FrameworkBundle\Controller\RedirectController::redirectAction
+        legacy_foo:
+            path: /legacy/foo
+            url_redirect: /foo
             defaults:
-                # ...
                 permanent: true
                 keepRequestMethod: true
 
         # redirects with the 307 status code
         route_bar:
-            # ...
-            controller: Symfony\Bundle\FrameworkBundle\Controller\RedirectController::redirectAction
+            path: /bar
+            url_redirect: /tmp/bar
             defaults:
                 # ...
                 permanent: false
@@ -217,19 +261,13 @@ permanent redirects use ``308`` code instead of ``301``:
                 http://symfony.com/schema/routing/routing-1.0.xsd">
 
             <!-- redirects with the 308 status code -->
-            <route id="route_foo"
-                path="..."
-                controller="Symfony\Bundle\FrameworkBundle\Controller\RedirectController::urlRedirectAction">
-                <!-- ... -->
+            <route id="legacy_foo" path="/legacy/foo" url-redirect="/foo">
                 <default key="permanent">true</default>
                 <default key="keepRequestMethod">true</default>
             </route>
 
             <!-- redirects with the 307 status code -->
-            <route id="route_bar"
-                path="..."
-                controller="Symfony\Bundle\FrameworkBundle\Controller\RedirectController::urlRedirectAction">
-                <!-- ... -->
+            <route id="route_bar" path="/bar" url-redirect="/tmp/bar">
                 <default key="permanent">false</default>
                 <default key="keepRequestMethod">true</default>
             </route>
@@ -238,25 +276,18 @@ permanent redirects use ``308`` code instead of ``301``:
     .. code-block:: php
 
         // config/routes.php
-        use Symfony\Component\Routing\RouteCollection;
-        use Symfony\Component\Routing\Route;
-
-        $collection = new RouteCollection();
-
-        // redirects with the 308 status code
-        $collection->add('route_foo', new Route('...', [
-            // ...
-            '_controller'       => 'Symfony\Bundle\FrameworkBundle\Controller\RedirectController::urlRedirectAction',
-            'permanent'         => true,
-            'keepRequestMethod' => true,
-        ]));
-
-        // redirects with the 307 status code
-        $collection->add('route_bar', new Route('...', [
-            // ...
-            '_controller'       => 'Symfony\Bundle\FrameworkBundle\Controller\RedirectController::urlRedirectAction',
-            'permanent'         => false,
-            'keepRequestMethod' => true,
-        ]));
-
-        return $collection;
+        namespace Symfony\Bundle\FrameworkBundle\Routing\Loader\Configurator;
+
+        return function (RoutingConfigurator $routes) {
+            // redirects with the 308 status code
+            $routes->urlRedirect('legacy_foo', '/legacy/foo', '/foo')
+                ->permanent(true)
+                ->keepRequestMethod(true)
+            ;
+
+            // redirects with the 307 status code
+            $routes->urlRedirect('route_bar', '/bar', '/tpm/bar')
+                ->permanent(false)
+                ->keepRequestMethod(true)
+            ;
+        };

templating/render_without_controller.rst

@@ -27,6 +27,12 @@ can do this without creating a controller:
                 template: static/privacy.html.twig
             methods: GET
 
+        # or
+        acme_privacy:
+            path:         /privacy
+            template: static/privacy.html.twig
+            methods: GET
+
     .. code-block:: xml
 
         <!-- config/routes.xml -->
@@ -41,12 +47,18 @@ can do this without creating a controller:
                 methods="GET">
                 <default key="template">static/privacy.html.twig</default>
             </route>
+
+            <!-- or -->
+            <route id="acme_privacy"
+                path="/privacy"
+                template="static/privacy.html.twig"
+                methods="GET" />
         </routes>
 
     .. code-block:: php
 
         // config/routes.php
-        namespace Symfony\Component\Routing\Loader\Configurator;
+        namespace Symfony\Bundle\FrameworkBundle\Routing\Loader\Configurator;
 
         use Symfony\Bundle\FrameworkBundle\Controller\TemplateController;
 
@@ -58,6 +70,12 @@ can do this without creating a controller:
                     'template'  => 'static/privacy.html.twig',
                 ])
             ;
+
+            // or
+            $routes->add('acme_privacy', '/privacy')
+                ->template('static/privacy.html.twig')
+                ->methods(['GET'])
+            ;
         };
 
 The ``TemplateController`` will render whatever template you've passed as the
@@ -89,11 +107,10 @@ exactly how your page is cached:
         # config/routes.yaml
         acme_privacy:
             path:          /privacy
-            controller:    Symfony\Bundle\FrameworkBundle\Controller\TemplateController
+            template:  'static/privacy.html.twig'
             defaults:
-                template:  'static/privacy.html.twig'
                 maxAge:    86400
-                sharedAge: 86400
+                sharedMaxAge: 86400
             methods: GET
 
     .. code-block:: xml
@@ -106,37 +123,42 @@ exactly how your page is cached:
 
             <route id="acme_privacy"
                 path="/privacy"
-                controller="Symfony\Bundle\FrameworkBundle\Controller\TemplateController"
+                template="static/privacy.html.twig"
                 methods="GET">
-                <default key="template">static/privacy.html.twig</default>
                 <default key="maxAge">86400</default>
-                <default key="sharedAge">86400</default>
+                <default key="sharedMaxAge">86400</default>
             </route>
         </routes>
 
     .. code-block:: php
 
         // config/routes.php
-        namespace Symfony\Component\Routing\Loader\Configurator;
+        namespace Symfony\Bundle\FrameworkBundle\Routing\Loader\Configurator;
 
         use Symfony\Bundle\FrameworkBundle\Controller\TemplateController;
 
         return function (RoutingConfigurator $routes) {
             $routes->add('acme_privacy', '/privacy')
-                ->controller(TemplateController::class)
+                ->template('static/privacy.html.twig')
                 ->methods(['GET'])
-                ->defaults([
-                    'template'  => 'static/privacy.html.twig',
-                    'maxAge'    => 86400,
-                    'sharedAge' => 86400,
-                ])
+                ->maxAge(86400)
+                ->sharedMaxAge(86400)
             ;
         };
 
+.. versionadded:: 4.3
+
+    The ``template`` shortcut has been introduced in Symfony 4.3
+
 The ``maxAge`` and ``sharedAge`` values are used to modify the Response
 object created in the controller. For more information on caching, see
 :doc:`/http_cache`.
 
 There is also a ``private`` variable (not shown here). By default, the Response
-will be made public, as long as ``maxAge`` or ``sharedAge`` are passed.
+will be made public, as long as ``maxAge`` or ``sharedAge`` (or
+``sharedMaxAge``) are passed.
 If set to ``true``, the Response will be marked as private.
+
+.. versionadded:: 4.3
+
+    The ``sharedMaxAge`` variable has been introduced in Symfony 4.3