Add stateless route attribute documentation

mtarld · mtarld · commit eb9de968e762 · 2020-04-04T20:03:54.000+02:00
diff --git a/routing.rst b/routing.rst
@@ -1805,6 +1805,77 @@ with a locale. This can be done by defining a different prefix for each locale
             ;
         };
 
+.. _stateless-routing:
+
+Stateless Routes
+----------------
+
+Routes can configure a ``stateless`` boolean option in order to make sure that the controller
+is not using the session during the request handling.
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Controller/MainController.php
+        namespace App\Controller;
+
+        use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+        use Symfony\Component\Routing\Annotation\Route;
+
+        class MainController extends AbstractController
+        {
+            /**
+             * @Route("/", name="homepage", stateless=true)
+             */
+            public function homepage()
+            {
+                // ...
+            }
+        }
+
+    .. code-block:: yaml
+
+        # config/routes.yaml
+        homepage:
+            controller: App\Controller\MainController::homepage
+            path: /
+            stateless: true
+
+    .. code-block:: xml
+
+        <!-- config/routes.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                https://symfony.com/schema/routing/routing-1.0.xsd">
+            <route id="homepage" controller="App\Controller\MainController::homepage" path="/" stateless="true"/>
+        </routes>
+
+    .. code-block:: php
+
+        // config/routes.php
+        use App\Controller\MainController;
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+        return function (RoutingConfigurator $routes) {
+            $routes->add('homepage', '/')
+                ->controller([MainController::class, 'homepage'])
+                ->stateless()
+            ;
+        };
+
+If a stateless declared route is using the session, the application will:
+- Throw an `Symfony\\Component\\HttpKernel\\Exception\\UnexpectedSessionUsageException` when debugging is enabled
+- Log a warning when debugging is disabled.
+
+.. tip::
+
+    When the application uses full "language + territory" locales (e.g. ``fr_FR``,
+    ``fr_BE``), if the URLs are the same in all related locales, routes can use
+    only the language part (e.g. ``fr``) to avoid repeating the same URLs.
+
 .. _routing-generating-urls:
 
 Generating URLs
