8000 [Routing][Security] Document the `LogoutRouteLoader` · symfony/symfony-docs@8906132 · GitHub
[go: up one dir, main page]

Skip to content

Commit 8906132

Browse files
MatTheCatwouterj
authored andcommitted
[Routing][Security] Document the LogoutRouteLoader
1 parent f1c0f13 commit 8906132

File tree

1 file changed

+124
-36
lines changed

1 file changed

+124
-36
lines changed

security.rst

+124-36
Original file line numberDiff line numberDiff line change
@@ -1796,7 +1796,7 @@ To enable logging out, activate the ``logout`` config parameter under your fire
17961796
main:
17971797
# ...
17981798
logout:
1799-
path: app_logout
1799+
path: /logout
18001800
18011801
# where to redirect after logout
18021802
# target: app_any_route
@@ -1817,11 +1817,10 @@ To enable logging out, activate the ``logout`` config parameter under your fire
18171817
<!-- ... -->
18181818
18191819
<firewall name="main">
1820-
<!-- ... -->
1821-
<logout path="app_logout"/>
1820+
<logout path="/logout"/>
18221821
18231822
<!-- use "target" to configure where to redirect after logout
1824-
<logout path="app_logout" target="app_any_route"/>
1823+
<logout path="/logout" target="app_any_route"/>
18251824
-->
18261825
</firewall>
18271826
</config>
@@ -1838,68 +1837,58 @@ To enable logging out, activate the ``logout`` config parameter under your fire
18381837
$mainFirewall = $security->firewall('main');
18391838
// ...
18401839
$mainFirewall->logout()
1841-
// the argument can be either a route name or a path
1842-
->path('app_logout')
1840+
->path('/logout')
18431841
18441842
// where to redirect after logout
18451843
// ->target('app_any_route')
18461844
;
18471845
};
18481846
1849-
Next, you need to create a route for this URL (but not a controller):
1847+
Symfony will then un-authenticate users navigating to the configured ``path``,
1848+
and redirect them to the configured ``target``.
18501849

1851-
.. configuration-block::
1852-
1853-
.. code-block:: php-attributes
1850+
.. tip::
18541851

1855-
// src/Controller/SecurityController.php
1856-
namespace App\Controller;
1852+
If you need to reference the logout path, you can use the ``_logout_<firewallname>``
1853+
route name (e.g. ``_logout_main``).
18571854

1858-
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
1859-
use Symfony\Component\Routing\Annotation\Route;
1855+
If your project does not use :ref:`Symfony Flex <symfony-flex>`, make sure
1856+
you have imported the logout route loader in your routes:
18601857

1861-
class SecurityController extends AbstractController
1862-
{
1863-
#[Route('/logout', name: 'app_logout', methods: ['GET'])]
1864-
public function logout(): never
1865-
{
1866-
// controller can be blank: it will never be called!
1867-
throw new \Exception('Don\'t forget to activate logout in security.yaml');
1868-
}
1869-
}
1858+
.. configuration-block::
18701859

18711860
.. code-block:: yaml
18721861
1873-
# config/routes.yaml
1874-
app_logout:
1875-
path: /logout
1876-
methods: GET
1862+
# config/routes/security.yaml
1863+
_symfony_logout:
1864+
resource: security.route_loader.logout
1865+
type: service
18771866
18781867
.. code-block:: xml
18791868
1880-
<!-- config/routes.xml -->
1869+
<!-- config/routes/security.xml -->
18811870
<?xml version="1.0" encoding="UTF-8" ?>
18821871
<routes xmlns="http://symfony.com/schema/routing"
18831872
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
18841873
xsi:schemaLocation="http://symfony.com/schema/routing
18851874
https://symfony.com/schema/routing/routing-1.0.xsd">
18861875
1887-
<route id="app_logout" path="/logout" methods="GET"/>
1876+
<import resource="security.route_loader.logout" type="service"/>
18881877
</routes>
18891878
18901879
.. code-block:: php
18911880
1892-
// config/routes.php
1881+
// config/routes/security.php
18931882
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
18941883
1895-
return function (RoutingConfigurator $routes): void {
1896-
$routes->add('app_logout', '/logout')
1897-
->methods(['GET'])
1898-
;
1884+
return static function (RoutingConfigurator $routes): void {
1885+
$routes->import('security.route_loader.logout', 'service');
18991886
};
19001887
1901-
That's it! By sending a user to the ``app_logout`` route (i.e. to ``/logout``)
1902-
Symfony will un-authenticate the current user and redirect them.
1888+
.. versionadded:: 6.4
1889+
1890+
The :class:`Symfony\\Bundle\\SecurityBundle\\Routing\\LogoutRouteLoader` was
1891+
introduced in Symfony 6.4.
19031892

19041893
Logout programmatically
19051894
~~~~~~~~~~~~~~~~~~~~~~~
@@ -1989,6 +1978,105 @@ to execute custom logic::
19891978
}
19901979
}
19911980

1981+
Customizing Logout Path
1982+
~~~~~~~~~~~~~~~~~~~~~~~
1983+
1984+
Another option is to configure ``path`` as a route name. This can be useful
1985+
if you want logout URIs to be dynamic (e.g. translated according to the
1986+
current locale). In that case, you have to create this route yourself:
1987+
1988+
.. configuration-block::
1989+
1990+
.. code-block:: yaml
1991+
1992+
# config/routes.yaml
1993+
app_logout:
1994+
path:
1995+
en: /logout
1996+
fr: /deconnexion
1997+
methods: GET
1998+
1999+
.. code-block:: xml
2000+
2001+
<!-- config/routes.xml -->
2002+
<?xml version="1.0" encoding="UTF-8" ?>
2003+
<routes xmlns="http://symfony.com/schema/routing"
2004+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2005+
xsi:schemaLocation="http://symfony.com/schema/routing
2006+
https://symfony.com/schema/routing/routing-1.0.xsd">
2007+
2008+
<route id="app_logout" path="/logout" methods="GET">
2009+
<path locale="en">/logout</path>
2010+
<path locale="fr">/deconnexion</path>
2011+
</route>
2012+
</routes>
2013+
2014+
.. code-block:: php
2015+
2016+
// config/routes.php
2017+
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
2018+
2019+
return function (RoutingConfigurator $routes): void {
2020+
$routes->add('app_logout', [
2021+
'en' => '/logout',
2022+
'fr' => '/deconnexion',
2023+
])
2024+
->methods(['GET'])
2025+
;
2026+
};
2027+
2028+
Then, pass the route name to the ``path`` option:
2029+
2030+
.. configuration-block::
2031+
2032+
.. code-block:: yaml
2033+
2034+
# config/packages/security.yaml
2035+
security:
2036+
# ...
2037+
2038+
firewalls:
2039+
main:
2040+
# ...
2041+
logout:
2042+
path: app_logout
2043+
2044+
.. code-block:: xml
2045+
2046+
<!-- config/packages/security.xml -->
2047+
<?xml version="1.0" encoding="UTF-8" ?>
2048+
<srv:container xmlns="http://symfony.com/schema/dic/security"
2049+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2050+
xmlns:srv="http://symfony.com/schema/dic/services"
2051+
xsi:schemaLocation="http://symfony.com/schema/dic/services
2052+
https://symfony.com/schema/dic/services/services-1.0.xsd
2053+
http://symfony.com/schema/dic/security
2054+
https://symfony.com/schema/dic/security/security-1.0.xsd">
2055+
2056+
<config>
2057+
<!-- ... -->
2058+
2059+
<firewall name="main">
2060+
<logout path="app_logout"/>
2061+
</firewall>
2062+
</config>
2063+
</srv:container>
2064+
2065+
.. code-block:: php
2066+
2067+
// config/packages/security.php
2068+
use Symfony\Config\SecurityConfig;
2069+
2070+
return static function (SecurityConfig $security): void {
2071+
// ...
2072+
2073+
$mainFirewall = $security->firewall('main');
2074+
// ...
2075+
$mainFirewall->logout()
2076+
->path('app_logout')
2077+
;
2078+
};
2079+
19922080
.. _retrieving-the-user-object:
19932081

19942082
Fetching the User Object

0 commit comments

Comments
 (0)
0