minor #15186 Adding full subscriber example (ThomasLandauer)

This PR was submitted for the 5.2 branch but it was merged into the 5.4 branch instead.

Discussion
----------

Adding full subscriber example

Reason: It's not so easy to figure this out, since the linked Event Subscriber page doesn't show how to subscribe to this specific event.

Questions:
* The introduction text says "e.g. invalidate some tokens". How can this be done?
* How can you add a flash message? `$this->addFlash()` didn't work for me.
* I'm extending `AbstractController` to have access to `$this->generateUrl()` - is this the easiest/best way?

Commits
-------

4f90b3c Adding full subscriber example

Author: wouterj

security.rst

@@ -1766,17 +1766,40 @@ In some cases you need to run extra logic upon logout (e.g. invalidate
 some tokens) or want to customize what happens after a logout. During
 logout, a :class:`Symfony\\Component\\Security\\Http\\Event\\LogoutEvent`
 is dispatched. Register an :doc:`event listener or subscriber </event_dispatcher>`
-to run custom logic. The following information is available in the
-event class:
-
-``getToken()``
-    Returns the security token of the session that is about to be logged
-    out.
-``getRequest()``
-    Returns the current request.
-``getResponse()``
-    Returns a response, if it is already set by a custom listener. Use
-    ``setResponse()`` to configure a custom logout response.
+to execute custom logic::
+
+    // src/EventListener/LogoutSubscriber.php
+    namespace App\EventListener;
+
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+    use Symfony\Component\HttpFoundation\RedirectResponse;
+    use Symfony\Component\Security\Http\Event\LogoutEvent;
+
+    class LogoutSubscriber extends AbstractController implements EventSubscriberInterface
+    {
+        public static function getSubscribedEvents(): array
+        {
+            return [LogoutEvent::class => 'onLogout'];
+        }
+
+        public function onLogout(LogoutEvent $event): void
+        {
+            // get the security token of the session that is about to be logged out
+            $token = $event->getToken();
+
+            // get the current request
+            $request = $event->getRequest();
+
+            // get the current response, if it is already set by another listener
+            $response = $event->getResponse();
+
+            // configure a custom logout response
+            $event->setResponse(
+                new RedirectResponse($this->generateUrl('homepage', []), RedirectResponse::HTTP_SEE_OTHER)
+            );
+        }
+    }
 
 .. _retrieving-the-user-object:
 
@@ -2534,7 +2557,7 @@ for these events.
             services:
                 # ...
 
-                App\EventListener\CustomLogoutSubscriber:
+                App\EventListener\LogoutSubscriber:
                     tags:
                         - name: kernel.event_subscriber
                           dispatcher: security.event_dispatcher.main
@@ -2551,7 +2574,7 @@ for these events.
                 <services>
                     <!-- ... -->
 
-                    <service id="App\EventListener\CustomLogoutSubscriber">
+                    <service id="App\EventListener\LogoutSubscriber">
                         <tag name="kernel.event_subscriber"
                              dispatcher="security.event_dispatcher.main"
                          />
@@ -2564,14 +2587,12 @@ for these events.
             // config/services.php
             namespace Symfony\Component\DependencyInjection\Loader\Configurator;
 
-            use App\EventListener\CustomLogoutListener;
-            use App\EventListener\CustomLogoutSubscriber;
-            use Symfony\Component\Security\Http\Event\LogoutEvent;
+            use App\EventListener\LogoutSubscriber;
 
             return function(ContainerConfigurator $configurator) {
                 $services = $configurator->services();
 
-                $services->set(CustomLogoutSubscriber::class)
+                $services->set(LogoutSubscriber::class)
                     ->tag('kernel.event_subscriber', [
                         'dispatcher' => 'security.event_dispatcher.main',
                     ]);