From 70d745ac26d30564b094a22e8d9ae4fcee636a71 Mon Sep 17 00:00:00 2001
From: HypeMC <hypemc@gmail.com>
Date: Thu, 19 Aug 2021 15:47:53 +0200
Subject: [PATCH] [DI] Add section about Service Closures

---
 service_container/lazy_services.rst           |  3 +-
 service_container/service_closures.rst        | 91 +++++++++++++++++++
 .../service_subscribers_locators.rst          |  5 +
 3 files changed, 98 insertions(+), 1 deletion(-)
 create mode 100644 service_container/service_closures.rst

diff --git a/service_container/lazy_services.rst b/service_container/lazy_services.rst
index 405298718a5..c31308c0a42 100644
--- a/service_container/lazy_services.rst
+++ b/service_container/lazy_services.rst
@@ -6,7 +6,8 @@ Lazy Services
 
 .. seealso::
 
-    Another way to inject services lazily is via a :doc:`service subscriber </service_container/service_subscribers_locators>`.
+    Other ways to inject services lazily is via a :doc:`service closure </service_container/service_closures>` or
+    :doc:`service subscriber </service_container/service_subscribers_locators>`.
 
 Why Lazy Services?
 ------------------
diff --git a/service_container/service_closures.rst b/service_container/service_closures.rst
new file mode 100644
index 00000000000..f299a086104
--- /dev/null
+++ b/service_container/service_closures.rst
@@ -0,0 +1,91 @@
+.. index::
+    single: DependencyInjection; Service Closures
+
+Service Closures
+================
+
+This feature wraps the injected service into a closure allowing it to be
+lazily loaded when and if needed.
+This is useful if the service being injected is a bit heavy to instantiate
+or is used only in certain cases.
+The service is instantiated the first time the closure is called, while
+all subsequent calls return the same instance, unless the service is
+:doc:`not shared </service_container/shared>`::
+
+    // src/Service/MyService.php
+    namespace App\Service;
+
+    use Symfony\Component\Mailer\MailerInterface;
+
+    class MyService
+    {
+        /**
+         * @var callable(): MailerInterface
+         */
+        private \Closure $mailer;
+
+        public function __construct(\Closure $mailer)
+        {
+            $this->mailer = $mailer;
+        }
+
+        public function doSomething(): void
+        {
+            // ...
+
+            $this->getMailer()->send($email);
+        }
+
+        private function getMailer(): MailerInterface
+        {
+            return ($this->mailer)();
+        }
+    }
+
+To define a service closure and inject it to another service, create an
+argument of type ``service_closure``:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        services:
+            App\Service\MyService:
+                arguments: [!service_closure '@mailer']
+
+    .. 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>
+                <service id="App\Service\MyService">
+                    <argument type="service_closure" id="mailer"/>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+        use App\Service\MyService;
+        use Symfony\Component\DependencyInjection\Argument\ServiceClosureArgument;
+        use Symfony\Component\DependencyInjection\Reference;
+
+        return function (ContainerConfigurator $containerConfigurator) {
+            $services = $containerConfigurator->services();
+
+            $services->set(MyService::class)
+                ->args([new ServiceClosureArgument(new Reference('mailer'))]);
+        };
+
+.. seealso::
+
+    Another way to inject services lazily is via a
+    :doc:`service locators </service_container/service_subscribers_locators>`.
diff --git a/service_container/service_subscribers_locators.rst b/service_container/service_subscribers_locators.rst
index d10c71f4867..93d69e540f0 100644
--- a/service_container/service_subscribers_locators.rst
+++ b/service_container/service_subscribers_locators.rst
@@ -12,6 +12,11 @@ instantiation of the services to be lazy. However, that's not possible using
 the explicit dependency injection since services are not all meant to
 be ``lazy`` (see :doc:`/service_container/lazy_services`).
 
+.. seealso::
+
+    Another way to inject services lazily is via a
+    :doc:`service closure </service_container/service_closures>`.
+
 This can typically be the case in your controllers, where you may inject several
 services in the constructor, but the action called only uses some of them.
 Another example are applications that implement the `Command pattern`_