Merge branch '6.1' into 6.2

* 6.1:
  Remove 5.4 versionadded
  Document new Logstash handler argument
  Example remote ElasticsearchLogstashHandler
  [#15428] Add a bit more detail to bootstrap article
  Fix example code of customization of bootstrapping in test
  [#15186] Update example
  Adding full subscriber example
  [Validator] Add hint for testing custom constraints

Author: wouterj

logging/handlers.rst

@@ -26,6 +26,16 @@ To use it, declare it as a service:
         services:
             Symfony\Bridge\Monolog\Handler\ElasticsearchLogstashHandler: ~
 
+            # optionally, configure the handler using the constructor arguments (shown values are default)
+            Symfony\Bridge\Monolog\Handler\ElasticsearchLogstashHandler: ~
+                arguments:
+                    $endpoint: "http://127.0.0.1:9200"
+                    $index: "monolog"
+                    $client: null
+                    $level: !php/const Monolog\Logger::DEBUG
+                    $bubble: true
+                    $elasticsearchVersion: '1.0.0'
+
     .. code-block:: xml
 
         <!-- config/services.xml -->
@@ -40,16 +50,39 @@ To use it, declare it as a service:
 
             <services>
                 <service id="Symfony\Bridge\Monolog\Handler\ElasticsearchLogstashHandler"/>
+
+                <!-- optionally, configure the handler using the constructor arguments (shown values are default) -->
+                <service id="Symfony\Bridge\Monolog\Handler\ElasticsearchLogstashHandler">
+                    <argument key="endpoint">http://127.0.0.1:9200</argument>
+                    <argument key="index">monolog</argument>
+                    <argument key="client"/>
+                    <argument key="level" type="constant">Monolog\Logger::DEBUG</argument>
+                    <argument key="bubble">true</argument>
+                    <argument key="elasticsearchVersion">1.0.0</argument>
+                </service>
             </services>
         </container>
 
     .. code-block:: php
 
         // config/services.php
+        use Monolog\Logger;
         use Symfony\Bridge\Monolog\Handler\ElasticsearchLogstashHandler;
 
         $container->register(ElasticsearchLogstashHandler::class);
 
+        // optionally, configure the handler using the constructor arguments (shown values are default)
+        $container->register(ElasticsearchLogstashHandler::class)
+            ->setArguments(
+                '$endpoint' => "http://127.0.0.1:9200",
+                '$index' => "monolog",
+                '$client' => null,
+                '$level' => Logger::DEBUG,
+                '$bubble' => true,
+                '$elasticsearchVersion' => '1.0.0',
+            )
+        ;
+
 Then reference it in the Monolog configuration:
 
 .. configuration-block::

security.rst

@@ -1777,17 +1777,47 @@ 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\Component\EventDispatcher\EventSubscriberInterface;
+    use Symfony\Component\HttpFoundation\RedirectResponse;
+    use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
+    use Symfony\Component\Security\Http\Event\LogoutEvent;
+
+    class LogoutSubscriber implements EventSubscriberInterface
+    {
+        public function __construct(
+            private UrlGeneratorInterface $urlGenerator
+        ) {
+        }
+
+        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 to the homepage
+            $response = new RedirectResponse(
+                $this->urlGenerator->generate('homepage'),
+                RedirectResponse::HTTP_SEE_OTHER
+            );
+            $event->setResponse($response);
+        }
+    }
 
 .. _retrieving-the-user-object:
 
@@ -2511,7 +2541,7 @@ for these events.
             services:
                 # ...
 
-                App\EventListener\CustomLogoutSubscriber:
+                App\EventListener\LogoutSubscriber:
                     tags:
                         - name: kernel.event_subscriber
                           dispatcher: security.event_dispatcher.main
@@ -2528,7 +2558,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"
                          />
@@ -2541,14 +2571,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',
                     ]);

testing.rst

@@ -8,6 +8,8 @@ Whenever you write a new line of code, you also potentially add new bugs.
 To build better and more reliable applications, you should test your code
 using both functional and unit tests.
 
+.. _testing-installation:
+
 The PHPUnit Testing Framework
 -----------------------------
 

testing/bootstrap.rst

@@ -6,47 +6,64 @@ running those tests. For example, if you're running a functional test and
 have introduced a new translation resource, then you will need to clear your
 cache before running those tests.
 
-Symfony already created the following ``tests/bootstrap.php`` file when installing
-the package to work with tests. If you don't have this file, create it::
+When :ref:`installing testing <testing-installation>` using Symfony Flex,
+it already created a ``tests/bootstrap.php`` file that is run by PHPUnit
+before your tests.
 
-    // tests/bootstrap.php
-    use Symfony\Component\Dotenv\Dotenv;
+You can modify this file to add custom logic:
 
-    require dirname(__DIR__).'/vendor/autoload.php';
+.. code-block:: diff
 
-    if (file_exists(dirname(__DIR__).'/config/bootstrap.php')) {
-        require dirname(__DIR__).'/config/bootstrap.php';
-    } elseif (method_exists(Dotenv::class, 'bootEnv')) {
-        (new Dotenv())->bootEnv(dirname(__DIR__).'/.env');
-    }
+      // tests/bootstrap.php
+      use Symfony\Component\Dotenv\Dotenv;
 
-Then, check that your ``phpunit.xml.dist`` file runs this ``bootstrap.php`` file
-before running the tests:
+      require dirname(__DIR__).'/vendor/autoload.php';
 
-.. code-block:: xml
+      if (file_exists(dirname(__DIR__).'/config/bootstrap.php')) {
+          require dirname(__DIR__).'/config/bootstrap.php';
+      } elseif (method_exists(Dotenv::class, 'bootEnv')) {
+          (new Dotenv())->bootEnv(dirname(__DIR__).'/.env');
+      }
 
-    <!-- phpunit.xml.dist -->
-    <?xml version="1.0" encoding="UTF-8" ?>
-    <phpunit
-        bootstrap="tests/bootstrap.php"
-    >
-        <!-- ... -->
-    </phpunit>
+    + if (isset($_ENV['BOOTSTRAP_CLEAR_CACHE_ENV'])) {
+    +     // executes the "php bin/console cache:clear" command
+    +     passthru(sprintf(
+    +         'APP_ENV=%s php "%s/../bin/console" cache:clear --no-warmup',
+    +         $_ENV['BOOTSTRAP_CLEAR_CACHE_ENV'],
+    +         __DIR__
+    +     ));
+    + }
+
+.. note::
+
+    If you don't use Symfony Flex, make sure this file is configured as
+    bootstrap file in your ``phpunit.xml.dist`` file:
 
-Now, you can define in your ``phpunit.xml.dist`` file which environment you want the
-cache to be cleared:
+    .. code-block:: xml
+
+        <!-- phpunit.xml.dist -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <phpunit
+            bootstrap="tests/bootstrap.php"
+        >
+            <!-- ... -->
+        </phpunit>
+
+Now, you can update the ``phpunit.xml.dist`` file to declare the custom
+environment variable introduced to ``tests/bootstrap.php``:
 
 .. code-block:: xml
 
     <!-- phpunit.xml.dist -->
     <?xml version="1.0" encoding="UTF-8" ?>
     <phpunit>
-        <!-- ... -->
-
         <php>
             <env name="BOOTSTRAP_CLEAR_CACHE_ENV" value="test"/>
+            <!-- ... -->
         </php>
+
+        <!-- ... -->
     </phpunit>
 
-This now becomes an environment variable (i.e. ``$_ENV``) that's available
-in the custom bootstrap file (``tests/bootstrap.php``).
+Now, when running ``vendor/bin/phpunit``, the cache will be cleared
+automatically by the bootstrap file before running all tests.