Merge branch '5.2' into 5.x

* 5.2:
  Add troubleshooting for parallel merges to maintainer guide
  Update framework.rst
  JsonResponse content updated
  Fixed table markup
  [Messenger] Add options for PostgreSQL LISTEN/NOTIFY support
  Update data_collector.rst
  [#14728] Be explicit about the double 's'
  [#14700] Minor rewording
  Update login_link.rst
  Added explaination on context in events and initial marking
  [Messenger] fix typo
  [Messenger] Routing & Inheritance
  docs(http-client): fix default retry_failed configuration example
  [Cache] Add TLS scheme for Redis connection

Author: wouterj

_build/maintainer_guide.rst

@@ -352,6 +352,26 @@ forgot to merge as ``gh merge NNNNN -s 5.1`` to change the merge branch. Solutio
     $ git merge 5.1
     $ ...
 
+Merging while the target branch changed
+.......................................
+
+Sometimes, someone else merges a PR in ``5.x`` at the same time as you are
+doing it. In these cases, ``gh merge ...`` failes to push. Solve this by
+resetting your local branch and restarting the merge:
+
+.. code-block:: terminal
+
+    $ gh merge ...
+    # this failed
+
+    # fetch the updated 5.x branch from GitHub
+    $ git fetch upstream
+    $ git checkout 5.x
+    $ git reset --hard upstream/5.x
+
+    # restart the merge
+    $ gh merge ...
+
 .. _`symfony/symfony-docs`: https://github.com/symfony/symfony-docs
 .. _`Symfony Docs team`: https://github.com/orgs/symfony/teams/team-symfony-docs
 .. _`Symfony's respectful review comments`: https://symfony.com/doc/current/contributing/community/review-comments.html

components/cache/adapters/redis_adapter.rst

@@ -62,15 +62,16 @@ helper method allows creating and configuring the Redis client class instance us
     );
 
 The DSN can specify either an IP/host (and an optional port) or a socket path, as well as a
-password and a database index.
+password and a database index. To enable TLS for connections, the scheme ``redis`` must be
+replaced by ``rediss`` (the second ``s`` means "secure").
 
 .. note::
 
     A `Data Source Name (DSN)`_ for this adapter must use the following format.
 
     .. code-block:: text
 
-        redis://[pass@][ip|host|socket[:port]][/db-index]
+        redis[s]://[pass@][ip|host|socket[:port]][/db-index]
 
 Below are common examples of valid DSNs showing a combination of available values::
 

components/http_foundation.rst

@@ -706,9 +706,11 @@ class, which can make this even easier::
     // if you know the data to send when creating the response
     $response = new JsonResponse(['data' => 123]);
 
-    // if you don't know the data to send when creating the response
+    // if you don't know the data to send or if you want to customize the encoding options
     $response = new JsonResponse();
     // ...
+    // configure any custom encoding options (if needed, it must be called before "setData()")
+    //$response->setEncodingOptions(JsonResponse::DEFAULT_ENCODING_OPTIONS | \JSON_PRESERVE_ZERO_FRACTION);
     $response->setData(['data' => 123]);
 
     // if the data to send is already encoded in JSON

messenger.rst

@@ -313,6 +313,13 @@ to multiple transports:
             ],
         ]);
 
+.. note::
+
+    If you configure routing for both a child and parent class, both rules
+    are used. E.g. if you have an ``SmsNotification`` object that extends
+    from ``Notification``, both the routing for ``Notification`` and
+    ``SmsNotification`` will be used.
+
 Doctrine Entities in Messages
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1107,6 +1114,12 @@ a table named ``messenger_messages``.
 Or, to create the table yourself, set the ``auto_setup`` option to ``false`` and
 :ref:`generate a migration <doctrine-creating-the-database-tables-schema>`.
 
+.. caution::
+
+    The datetime property of the messages stored in the database uses the
+    timezone of the current system. This may cause issues if multiple machines
+    with different timezone configuration use the same storage.
+
 The transport has a number of options:
 
 ==================  =====================================  ======================
@@ -1126,11 +1139,28 @@ auto_setup          Whether the table should be created
                     automatically during send / get.       true
 ==================  =====================================  ======================
 
-.. caution::
+.. versionadded:: 5.1
 
-    The datetime property of the messages stored in the database uses the
-    timezone of the current system. This may cause issues if multiple machines
-    with different timezone configuration use the same storage.
+    The ability to leverage PostgreSQL's LISTEN/NOTIFY was introduced
+    in Symfony 5.1.
+
+When using PostgreSQL, you have access to the following options to leverage
+the `LISTEN/NOTIFY`_ feature. This allow for a more performant approach
+than the default polling behavior of the Doctrine transport because
+PostgreSQL will directly notify the workers when a new message is inserted
+in the table.
+
+=======================  ==========================================  ======================
+Option                   Description                                 Default
+=======================  ==========================================  ======================
+use_notify               Whether to use LISTEN/NOTIFY.               true
+check_delayed_interval   The interval to check for delayed           1000
+                         messages, in milliseconds.
+                         Set to 0 to disable checks.
+get_notify_timeout       The length of time to wait for a            0
+                         response when calling
+                         ``PDO::pgsqlGetNotify```, in milliseconds.
+=======================  ==========================================  ======================
 
 Beanstalkd Transport
 ~~~~~~~~~~~~~~~~~~~~
@@ -2081,3 +2111,4 @@ Learn more
 .. _`Long polling`: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-short-and-long-polling.html
 .. _`Visibility Timeout`: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-visibility-timeout.html
 .. _`FIFO queue`: https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues.html
+.. _`LISTEN/NOTIFY`: https://www.postgresql.org/docs/current/sql-notify.html

profiler/data_collector.rst

@@ -31,7 +31,6 @@ request::
     use Symfony\Bundle\FrameworkBundle\DataCollector\AbstractDataCollector;
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpFoundation\Response;
-    use Symfony\Component\HttpKernel\DataCollector\DataCollector;
 
     class RequestCollector extends AbstractDataCollector
     {

reference/configuration/framework.rst

@@ -831,17 +831,18 @@ will automatically retry failed HTTP requests.
         # ...
         http_client:
             # ...
-            retry_failed:
-                # retry_strategy: app.custom_strategy
-                http_codes:
-                    0: ['GET', 'HEAD']   # retry network errors if request method is GET or HEAD
-                    429: true            # retry all responses with 429 status code
-                    500: ['GET', 'HEAD']
-                max_retries: 2
-                delay: 1000
-                multiplier: 3
-                max_delay: 5000
-                jitter: 0.3
+            default_options:
+                retry_failed:
+                    # retry_strategy: app.custom_strategy
+                    http_codes:
+                        0: ['GET', 'HEAD']   # retry network errors if request method is GET or HEAD
+                        429: true            # retry all responses with 429 status code
+                        500: ['GET', 'HEAD']
+                    max_retries: 2
+                    delay: 1000
+                    multiplier: 3
+                    max_delay: 5000
+                    jitter: 0.3
 
             scoped_clients:
                 my_api.client:
@@ -1415,7 +1416,7 @@ The value can be one of:
 ``true``
     Throw an exception when the requirements are not met;
 ``false``
-    Disable exceptions when the requirements are not met and return ``null``
+    Disable exceptions when the requirements are not met and return ``''``
     instead;
 ``null``
     Disable checking the requirements (thus, match the route even when the

security/login_link.rst

@@ -654,3 +654,88 @@ user create this POST request (e.g. by clicking a button)::
             <button type="submit">Continue</button>
         </form>
     {% endblock %}
+
+Customizing the Success Handler
+-------------------------------
+
+Sometimes, the default success handling does not fit your use-case (e.g.
+when you need to generate and return an API key). To customize how the
+success handler behaves, create your own
+:class:`Symfony\Component\Security\Http\Authentication\AuthenticationSuccessHandlerInterface`::
+
+    // src/Security/Authentication/AuthenticationSuccessHandler.php
+    namespace App\Security\Authentication;
+
+    use Symfony\Component\HttpFoundation\JsonResponse;
+    use Symfony\Component\HttpFoundation\Request;
+    use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
+    use Symfony\Component\Security\Http\Authentication\AuthenticationSuccessHandlerInterface;
+
+    class AuthenticationSuccessHandler implements AuthenticationSuccessHandlerInterface
+    {
+        public function onAuthenticationSuccess(Request $request, TokenInterface $token): JsonResponse
+        {
+            $user = $token->getUser();
+            $userApiToken = $user->getApiToken();
+
+            return new JsonResponse(['apiToken' => 'userApiToken']);
+        }
+    }
+
+Then, configure this service ID as the ``success_handler``:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        security:
+            firewalls:
+                main:
+                    login_link:
+                        check_route: login_check
+                        lifetime: 600
+                        max_uses: 1
+                        success_handler: App\Security\Authentication\AuthenticationSuccessHandler
+
+    .. code-block:: xml
+
+        <!-- config/packages/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/security
+                https://symfony.com/schema/dic/security/security-1.0.xsd">
+
+            <config>
+                <firewall name="main">
+                    <login-link check-route="login_check"
+                        check-post-only="true"
+                        max-uses="1"
+                        lifetime="600"
+                        success-handler="App\Security\Authentication\AuthenticationSuccessHandler"
+                    />
+                </firewall>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // config/packages/security.php
+        use App\Security\Authentication\AuthenticationSuccessHandler;
+
+        $container->loadFromExtension('security', [
+            'firewalls' => [
+                'main' => [
+                    'login_link' => [
+                        'check_route' => 'login_check',
+                        'lifetime' => 600,
+                        'max_uses' => 1,
+                        'success_handler' => AuthenticationSuccessHandler::class,
+                    ],
+                ],
+            ],
+        ]);

workflow.rst

@@ -381,11 +381,36 @@ order:
     * ``workflow.[workflow name].announce``
     * ``workflow.[workflow name].announce.[transition name]``
 
+    You can avoid triggering those events by using the context::
+
+        $workflow->apply($subject, $transitionName, [Workflow::DISABLE_ANNOUNCE_EVENT => true]);
+
+    .. versionadded:: 5.1
+
+        The ``Workflow::DISABLE_ANNOUNCE_EVENT`` constant was introduced in Symfony 5.1.
+
+    .. versionadded:: 5.2
+
+        In Symfony 5.2, the context is accessible in all events::
+
+            // $context must be an array
+            $context = ['context_key' => 'context_value'];
+            $workflow->apply($subject, $transitionName, $context);
+
+            // in an event listener
+            $context = $event->getContext(); // returns ['context']
+
 .. note::
 
     The leaving and entering events are triggered even for transitions that stay
     in same place.
 
+.. note::
+
+    If you initialize the marking by calling ``$workflow->getMarking($object);``,
+    then the ``workflow.[workflow_name].entered.[initial_place_name]`` event will
+    be called with the default context (``Workflow::DEFAULT_INITIAL_CONTEXT``).
+
 Here is an example of how to enable logging for every time a "blog_publishing"
 workflow leaves a place::