From 162ce755beae7364832b3051d7fa89674a4b47d4 Mon Sep 17 00:00:00 2001
From: Mathieu Lechat <math.lechat@gmail.com>
Date: Mon, 16 Oct 2023 11:17:17 +0200
Subject: [PATCH] Rewording

---
 security.rst | 53 +++++++++++++++++++++++++++++-----------------------
 1 file changed, 30 insertions(+), 23 deletions(-)

diff --git a/security.rst b/security.rst
index 2b3a3a32dea..68b86789e33 100644
--- a/security.rst
+++ b/security.rst
@@ -1796,7 +1796,7 @@ To enable logging out, activate the  ``logout`` config parameter under your fire
                 main:
                     # ...
                     logout:
-                        path: app_logout
+                        path: /logout
 
                         # where to redirect after logout
                         # target: app_any_route
@@ -1817,8 +1817,7 @@ To enable logging out, activate the  ``logout`` config parameter under your fire
                 <!-- ... -->
 
                 <firewall name="main">
-                    <!-- ... -->
-                    <logout path="app_logout"/>
+                    <logout path="/logout"/>
 
                     <!-- use "target" to configure where to redirect after logout
                     <logout path="app_logout" target="app_any_route"/>
@@ -1838,30 +1837,28 @@ To enable logging out, activate the  ``logout`` config parameter under your fire
             $mainFirewall = $security->firewall('main');
             // ...
             $mainFirewall->logout()
-                // the argument can be either a route name or a path
-                ->path('app_logout')
+                ->path('/logout')
 
                 // where to redirect after logout
                 // ->target('app_any_route')
             ;
         };
 
-``path`` can be either a route name, or a URI.
+Symfony will then un-authenticate users navigating to the configured ``path``,
+and redirect them to the configured ``target``.
 
-Since Symfony 6.4, you can leverage the
-:class:`Symfony\\Bundle\\SecurityBundle\\Routing\\LogoutRouteLoader`
-to automatically register a route for every logout URI you configured.
-If your project uses :ref:`Symfony Flex <symfony-flex>`,
-this is already done for you.
-Otherwise, you need to import the ``security.route_loader.logout`` service
-as a routing resource:
+If your project uses :ref:`Symfony Flex <symfony-flex>`, you're all set:
+the :class:`Symfony\\Bundle\\SecurityBundle\\Routing\\LogoutRouteLoader` will
+automatically register a route for every logout URI you configured!
+Otherwise, you can enable this behavior yourself by importing the
+``security.route_loader.logout`` service as a routing resource:
 
 .. configuration-block::
 
     .. code-block:: yaml
 
         # config/routes/security.yaml
-        logout:
+        _symfony_logout:
             resource: security.route_loader.logout
             type: service
 
@@ -1891,8 +1888,10 @@ as a routing resource:
     The :class:`Symfony\\Bundle\\SecurityBundle\\Routing\\LogoutRouteLoader` was
     introduced in Symfony 6.4.
 
-Another option is to create a route matching the name or URI you configured as
-``path``. You don't have to associate a controller because it wouldn't be called:
+Another option is to configure ``path`` as a route name, which can be useful if
+you want logout URIs to be translated according to the current locale e.g.
+In that case, you have to create this route yourself.
+Note that it doesn't need a controller, because it wouldn't be called anyways:
 
 .. configuration-block::
 
@@ -1906,7 +1905,10 @@ Another option is to create a route matching the name or URI you configured as
 
         class SecurityController extends AbstractController
         {
-            #[Route('/logout', name: 'app_logout', methods: ['GET'])]
+            #[Route([
+                'en' => '/logout',
+                'fr' => '/deconnexion'
+            ], name: 'app_logout', methods: ['GET'])]
             public function logout(): never
             {
                 // controller can be blank: it will never be called!
@@ -1918,7 +1920,9 @@ Another option is to create a route matching the name or URI you configured as
 
         # config/routes.yaml
         app_logout:
-            path: /logout
+            path:
+                en: /logout
+                fr: /deconnexion
             methods: GET
 
     .. code-block:: xml
@@ -1930,7 +1934,10 @@ Another option is to create a route matching the name or URI you configured as
             xsi:schemaLocation="http://symfony.com/schema/routing
                 https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="app_logout" path="/logout" methods="GET"/>
+            <route id="app_logout" path="/logout" methods="GET">
+                <path locale="en">/logout</path>
+                <path locale="fr">/deconnexion</path>
+            </route>
         </routes>
 
     .. code-block:: php
@@ -1939,14 +1946,14 @@ Another option is to create a route matching the name or URI you configured as
         use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
         return function (RoutingConfigurator $routes): void {
-            $routes->add('app_logout', '/logout')
+            $routes->add('app_logout', [
+                'en' => '/logout',
+                'fr' => '/deconnexion',
+            ])
                 ->methods(['GET'])
             ;
         };
 
-That's it! By sending a user to the ``app_logout`` route (i.e. to ``/logout``)
-Symfony will un-authenticate the current user and redirect them.
-
 Logout programmatically
 ~~~~~~~~~~~~~~~~~~~~~~~