8000 feature #19000 [Routing][Security] Document the `LogoutRouteLoader` (… · symfony/symfony-docs@f0f261d · GitHub
[go: up one dir, main page]
Skip to content

Commit f0f261d

Browse files
wouterjwouterj
committed
feature #19000 [Routing][Security] Document the LogoutRouteLoader (MatTheCat)
This PR was squashed before being merged into the 6.4 branch. Discussion ---------- [Routing][Security] Document the `LogoutRouteLoader` Related to * symfony/symfony#50946 Commits ------- 8906132 [Routing][Security] Document the `LogoutRouteLoader`
2 parents bb34c43 + 8906132 commit f0f261d

File tree

1 file changed

+124
-36
lines changed

1 file changed

+124
-36
lines changed

‎security.rst‎

Lines changed: 124 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1801,7 +1801,7 @@ To enable logging out, activate the ``logout`` config parameter under your fire
18011801
main:
18021802
# ...
18031803
logout:
1804-
path: app_logout
1804+
path: /logout
18051805
18061806
# where to redirect after logout
18071807
# target: app_any_route
@@ -1822,11 +1822,10 @@ To enable logging out, activate the ``logout`` config parameter under your fire
18221822
<!-- ... -->
18231823
18241824
<firewall name="main">
1825-
<!-- ... -->
1826-
<logout path="app_logout"/>
1825+
<logout path="/logout"/>
18271826
18281827
<!-- use "target" to configure where to redirect after logout
1829-
<logout path="app_logout" target="app_any_route"/>
1828+
<logout path="/logout" target="app_any_route"/>
18301829
-->
18311830
</firewall>
18321831
</config>
@@ -1843,68 +1842,58 @@ To enable logging out, activate the ``logout`` config parameter under your fire
18431842
$mainFirewall = $security->firewall('main');
18441843
// ...
18451844
$mainFirewall->logout()
1846-
// the argument can be either a route name or a path
1847-
->path('app_logout')
1845+
->path('/logout')
18481846
18491847
// where to redirect after logout
18501848
// ->target('app_any_route')
18511849
;
18521850
};
18531851
1854-
Next, you need to create a route for this URL (but not a controller):
1852+
Symfony will then un-authenticate users navigating to the configured ``path``,
1853+
and redirect them to the configured ``target``.
18551854

1856-
.. configuration-block::
1857-
1858-
.. code-block:: php-attributes
1855+
.. tip::
18591856

1860-
// src/Controller/SecurityController.php
1861-
namespace App\Controller;
1857+
If you need to reference the logout path, you can use the ``_logout_<firewallname>``
1858+
route name (e.g. ``_logout_main``).
18621859

1863-
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
1864-
use Symfony\Component\Routing\Annotation\Route;
1860+
If your project does not use :ref:`Symfony Flex <symfony-flex>`, make sure
1861+
you have imported the logout route loader in your routes:
18651862

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

18761865
.. code-block:: yaml
18771866
1878-
# config/routes.yaml
1879-
app_logout:
1880-
path: /logout
1881-
methods: GET
1867+
# config/routes/security.yaml
1868+
_symfony_logout:
1869+
resource: security.route_loader.logout
1870+
type: service
18821871
18831872
.. code-block:: xml
18841873
1885-
<!-- config/routes.xml -->
1874+
<!-- config/routes/security.xml -->
18861875
<?xml version="1.0" encoding="UTF-8" ?>
18871876
<routes xmlns="http://symfony.com/schema/routing"
18881877
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
18891878
xsi:schemaLocation="http://symfony.com/schema/routing
18901879
https://symfony.com/schema/routing/routing-1.0.xsd">
18911880
1892-
<route id="app_logout" path="/logout" methods="GET"/>
1881+
<import resource="security.route_loader.logout" type="service"/>
18931882
</routes>
18941883
18951884
.. code-block:: php
18961885
1897-
// config/routes.php
1886+
// config/routes/security.php
18981887
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
18991888
1900-
return function (RoutingConfigurator $routes): void {
1901-
$routes->add('app_logout', '/logout')
1902-
->methods(['GET'])
1903-
;
1889+
return static function (RoutingConfigurator $routes): void {
1890+
$routes->import('security.route_loader.logout', 'service');
19041891
};
19051892
1906-
That's it! By sending a user to the ``app_logout`` route (i.e. to ``/logout``)
1907-
Symfony will un-authenticat 9E88 e the current user and redirect them.
1893+
.. versionadded:: 6.4
1894+
1895+
The :class:`Symfony\\Bundle\\SecurityBundle\\Routing\\LogoutRouteLoader` was
1896+
introduced in Symfony 6.4.
19081897

19091898
Logout programmatically
19101899
~~~~~~~~~~~~~~~~~~~~~~~
@@ -1994,6 +1983,105 @@ to execute custom logic::
19941983
}
19951984
}
19961985

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

19992087
Fetching the User Object

0 commit comments

Comments
 (0)
0