8000 feature #13520 [Security] Documented new logout event (wouterj) · symfony/symfony-docs@3ef6848 · GitHub
[go: up one dir, main page]
Skip to content

Commit 3ef6848

Browse files
wouterjwouterj
committed
feature #13520 [Security] Documented new logout event (wouterj)
This PR was merged into the master branch. Discussion ---------- [Security] Documented new logout event Fixes #13484 Commits ------- 1d77a45 Documented new logout event
2 parents 888593e + 1d77a45 commit 3ef6848

File tree

2 files changed

+94
-3
lines changed

2 files changed

+94
-3
lines changed

‎reference/configuration/security.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -538,9 +538,18 @@ The ``invalidate_session`` option allows to redefine this behavior. Set this
538538
option to ``false`` in every firewall and the user will only be logged out from
539539
the current firewall and not the other ones.
540540

541+
.. _reference-security-logout-success-handler:
542+
541543
success_handler
542544
~~~~~~~~~~~~~~~
543545

546+
.. deprecated:: 5.1
547+
548+
This option is deprecated since Symfony 5.1. Register an
549+
:doc:`event listener </event_dispatcher>` on the
550+
:class:`Symfony\\Component\\Security\\Http\\Event\\LogoutEvent`
551+
instead.
552+
544553
**type**: ``string`` **default**: ``'security.logout.success_handler'``
545554

546555
The service ID used for handling a successful logout. The service must implement

‎security.rst

Lines changed: 85 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -912,11 +912,93 @@ Next, you'll need to create a route for this URL (but not a controller):
912912
And that's it! By sending a user to the ``app_logout`` route (i.e. to ``/logout``)
913913
Symfony will un-authenticate the current user and redirect them.
914914

915+
Customizing Logout
916+
~~~~~~~~~~~~~~~~~~
917+
918+
.. versionadded:: 5.1
919+
920+
The ``LogoutEvent`` was introduced in Symfony 5.1. Prior to this
921+
version, you had to use a
922+
:ref:`logout success handler <reference-security-logout-success-handler>`
923+
to customize the logout.
924+
925+
In some cases you need to execute extra logic upon logout (e.g. invalidate
926+
some tokens) or want to customize what happens after a logout. During
927+
logout, a :class:`Symfony\\Component\\Security\\Http\\Event\\LogoutEvent`
928+
is dispatched. Register an :doc:`event listener or subscriber </event_dispatcher>`
929+
to execute custom logic. The following information is available in the
930+
event class:
931+
932+
``getToken()``
933+
Returns the security token of the session that is about to be logged
934+
out.
935+
``getRequest()``
936+
Returns the current request.
937+
``getResponse()``
938+
Returns a response, if it is already set by a custom listener. Use
939+
``setResponse()`` to configure a custom logout response.
940+
941+
915942
.. tip::
916943

917-
Need more control of what happens after logout? Add a ``success_handler`` key
918-
under ``logout`` and point it to a service id of a class that implements
919-
:class:`Symfony\\Component\\Security\\Http\\Logout\\LogoutSuccessHandlerInterface`.
944+
Every Security firewall has its own event dispatcher
945+
(``security.event_dispatcher.FIREWALLNAME``). The logout event is
946+
dispatched on both the global and firewall dispatcher. You can register
947+
on the firewall dispatcher if you want your listener to only be
948+
executed for a specific firewall. For instance, if you have an ``api``
949+
and ``main`` firewall, use this configuration to register only on the
950+
logout event in the ``main`` firewall:
951+
952+
.. configuration-block::
953+
954+
.. code-block:: yaml
955+
956+
# config/services.yaml
957+
services:
958+
# ...
959+
960+
App\EventListener\CustomLogoutSubscriber:
961+
tags:
962+
- name: kernel.event_subscriber
963+
dispacher: security.event_dispatcher.main
964+
965+
.. code-block:: xml
966+
967+
<!-- config/services.xml -->
968+
<?xml version="1.0" encoding="UTF-8" ?>
969+
<container xmlns="http://symfony.com/schema/dic/services"
970+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
971+
xsi:schemaLocation="http://symfony.com/schema/dic/services
972+
https://symfony.com/schema/dic/services/services-1.0.xsd">
973+
974+
<services>
975+
<!-- ... -->
976+
977+
<service id="App\EventListener\CustomLogoutSubscriber">
978+
<tag name="kernel.event_subscriber"
979+
dispacher="security.event_dispatcher.main"
980+
/>
981+
</service>
982+
</services>
983+
</container>
984+
985+
.. code-block:: php
986+
987+
// config/services.php
988+
namespace Symfony\Component\DependencyInjection\Loader\Configurator;
989+
990+
use App\EventListener\CutomLogoutListener;
991+
use App\EventListener\CutomLogoutSubscriber;
992+
use Symfony\Component\Security\Http\Event\LogoutEvent;
993+
994+
return function(ContainerConfigurator $configurator) {
995+
$services = $configurator->services();
996+
997+
$services->set(CustomLogoutSubscriber::class)
998+
->tag('kernel.event_subscriber', [
999+
'dispatcher' => 'security.event_dispatcher.main',
1000+
]);
1001+
};
9201002
9211003
.. _security-role-hierarchy:
9221004

0 commit comments

Comments
 (0)
0