Merge branch '6.2' into 6.3

* 6.2:
  [DependencyInjection] Add `closure` argument type
  import function env to avoid fatal error if copying docs
  Use DOCtor-RST 1.37.0
  [Lock] Complete Lock example for less ambiguity

Author: javiereguiluz

.github/workflows/ci.yaml

@@ -73,7 +73,7 @@ jobs:
                     key: ${{ runner.os }}-doctor-rst-${{ steps.extract_base_branch.outputs.branch }}
 
             -   name: "Run DOCtor-RST"
-                uses: docker://oskarstark/doctor-rst:1.35.1
+                uses: docker://oskarstark/doctor-rst:1.37.0
                 with:
                     args: --short --error-format=github --cache-file=/github/workspace/.cache/doctor-rst.cache
 

components/lock.rst

@@ -75,8 +75,42 @@ Serializing Locks
 The :class:`Symfony\\Component\\Lock\\Key` contains the state of the
 :class:`Symfony\\Component\\Lock\\Lock` and can be serialized. This
 allows the user to begin a long job in a process by acquiring the lock, and
-continue the job in another process using the same lock::
+continue the job in another process using the same lock.
 
+First, you may create a serializable class containing the resource and the
+key of the lock::
+
+    // src/Lock/RefreshTaxonomy.php
+    namespace App\Lock;
+
+    use Symfony\Component\Lock\Key;
+
+    class RefreshTaxonomy
+    {
+        private object $article;
+        private Key $key;
+
+        public function __construct(object $article, Key $key)
+        {
+            $this->article = $article;
+            $this->key = $key;
+        }
+
+        public function getArticle(): object
+        {
+            return $this->article;
+        }
+
+        public function getKey(): Key
+        {
+            return $this->key;
+        }
+    }
+
+Then, you can use this class to dispatch all that's needed for another process
+to handle the rest of the job::
+
+    use App\Lock\RefreshTaxonomy;
     use Symfony\Component\Lock\Key;
     use Symfony\Component\Lock\Lock;
 

mailer.rst

@@ -54,6 +54,7 @@ over SMTP by configuring the DSN in your ``.env`` file (the ``user``,
     .. code-block:: php
 
         // config/packages/mailer.php
+        use function Symfony\Component\DependencyInjection\Loader\Configurator\env;
         use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
 
         return static function (ContainerConfigurator $containerConfigurator): void {
@@ -1179,6 +1180,7 @@ This can be configured by replacing the ``dsn`` configuration entry with a
     .. code-block:: php
 
         // config/packages/mailer.php
+        use function Symfony\Component\DependencyInjection\Loader\Configurator\env;
         use Symfony\Config\FrameworkConfig;
 
         return static function (FrameworkConfig $framework) {

service_container.rst

@@ -700,6 +700,100 @@ For a full list of *all* possible services in the container, run:
 
     $ php bin/console debug:container
 
+Injecting a Closure as an Argument
+----------------------------------
+
+It is possible to inject a callable as an argument of a service.
+Let's add an argument to our ``MessageGenerator`` constructor::
+
+    // src/Service/MessageGenerator.php
+    namespace App\Service;
+
+    use Psr\Log\LoggerInterface;
+
+    class MessageGenerator
+    {
+        private $logger;
+        private $messageHash;
+
+        public function __construct(LoggerInterface $logger, callable $generateMessageHash)
+        {
+            $this->logger = $logger;
+            $this->messageHash = $generateMessageHash();
+        }
+        // ...
+    }
+
+Now, we would add a new invokable service to generate the message hash::
+
+    // src/Hash/MessageHashGenerator.php
+    namespace App\Hash;
+
+    class MessageHashGenerator
+    {
+        public function __invoke(): string
+        {
+            // Compute and return a message hash
+        }
+    }
+
+Our configuration looks like this:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        services:
+            # ... same code as before
+
+            # explicitly configure the service
+            App\Service\MessageGenerator:
+                arguments:
+                    $logger: '@monolog.logger.request'
+                    $generateMessageHash: !closure '@App\Hash\MessageHashGenerator'
+
+    .. code-block:: xml
+
+        <!-- config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="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">
+
+            <services>
+                <!-- ... same code as before -->
+
+                <!-- Explicitly configure the service -->
+                <service id="App\Service\MessageGenerator">
+                    <argument key="$logger" type="service" id="monolog.logger.request"/>
+                    <argument key="$generateMessageHash" type="closure" id="App\Hash\MessageHashGenerator"/>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+        use App\Service\MessageGenerator;
+
+        return function(ContainerConfigurator $containerConfigurator) {
+            // ... same code as before
+
+            // explicitly configure the service
+            $services->set(MessageGenerator::class)
+                ->arg('$logger', service('monolog.logger.request'))
+                ->arg('$generateMessageHash', closure('App\Hash\MessageHashGenerator'))
+            ;
+        };
+
+.. versionadded:: 6.1
+
+    The ``closure`` argument type was introduced in Symfony 6.1.
+
 .. _services-binding:
 
 Binding Arguments by Name or Type