[DependencyInjection] Invokable Factory Services

Document new invokable factories (and configurators) implemented in symfony/symfony#30255.

Author: zanbaldwin

service_container/configurators.rst

@@ -195,6 +195,74 @@ the service id and the method name:
         # old syntax
         configurator: ['@App\Mail\EmailConfigurator', configure]
 
+.. _configurators-invokable:
+
+Starting from Symfony 4.3 services can be configured via invokable configurators
+(replacing the ``configure()`` method with ``__invoke()``) by omitting the
+method name, just as route definitions can reference :ref:`invokable
+controllers <controller-service-invoke>`.
+
+.. code-block:: yaml
+
+    # app/config/services.yml
+    services:
+        # ...
+
+        # Registers all 4 classes as services, including AppBundle\Mail\EmailConfigurator
+        AppBundle\:
+            resource: '../../src/AppBundle/*'
+            # ...
+
+        # override the services to set the configurator
+        AppBundle\Mail\NewsletterManager:
+            configurator: '@AppBundle\Mail\EmailConfigurator'
+
+        AppBundle\Mail\GreetingCardManager:
+            configurator: '@AppBundle\Mail\EmailConfigurator'
+
+.. code-block:: xml
+
+    <!-- app/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
+            http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+        <services>
+            <prototype namespace="AppBundle\" resource="../../src/AppBundle/*" />
+
+            <service id="AppBundle\Mail\NewsletterManager">
+                <configurator service="AppBundle\Mail\EmailConfigurator" />
+            </service>
+
+            <service id="AppBundle\Mail\GreetingCardManager">
+                <configurator service="AppBundle\Mail\EmailConfigurator" />
+            </service>
+        </services>
+    </container>
+
+.. code-block:: php
+
+    // app/config/services.php
+    use AppBundle\Mail\GreetingCardManager;
+    use AppBundle\Mail\NewsletterManager;
+    use Symfony\Component\DependencyInjection\Definition;
+    use Symfony\Component\DependencyInjection\Reference;
+
+    // Same as before
+    $definition = new Definition();
+
+    $definition->setAutowired(true);
+
+    $this->registerClasses($definition, 'AppBundle\\', '../../src/AppBundle/*');
+
+    $container->getDefinition(NewsletterManager::class)
+        ->setConfigurator(new Reference(EmailConfigurator::class));
+
+    $container->getDefinition(GreetingCardManager::class)
+        ->setConfigurator(new Reference(EmailConfigurator::class));
+
 That's it! When requesting the ``App\Mail\NewsletterManager`` or
 ``App\Mail\GreetingCardManager`` service, the created instance will first be
 passed to the ``EmailConfigurator::configure()`` method.

service_container/factories.rst

@@ -157,6 +157,72 @@ Configuration of the service container then looks like this:
             # old syntax
             factory: ['@App\Email\NewsletterManagerFactory', createNewsletterManager]
 
+.. _factories-invokable:
+
+Suppose you now change your factory method to ``__invoke()`` so that your
+factory service can be used as a callback::
+
+    class InvokableNewsletterManagerFactory
+    {
+        public function __invoke()
+        {
+            $newsletterManager = new NewsletterManager();
+
+            // ...
+
+            return $newsletterManager;
+        }
+    }
+
+Starting from Symfony 4.3 services can be created and configured via invokable
+factory services by omitting the method name, just as route definitions can
+reference :ref:`invokable controllers <controller-service-invoke>`.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/services.yml
+
+        services:
+            # ...
+
+            AppBundle\Email\NewsletterManager:
+                class:     AppBundle\Email\NewsletterManager
+                factory:   '@AppBundle\Email\NewsletterManagerFactory'
+
+    .. code-block:: xml
+
+        <!-- app/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
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <!-- ... -->
+
+                <service id="AppBundle\Email\NewsletterManager"
+                         class="AppBundle\Email\NewsletterManager">
+                    <factory service="AppBundle\Email\NewsletterManagerFactory" />
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/services.php
+
+        use AppBundle\Email\NewsletterManager;
+        use AppBundle\Email\NewsletterManagerFactory;
+        use Symfony\Component\DependencyInjection\Reference;
+
+        // ...
+        $container->register(NewsletterManager::class, NewsletterManager::class)
+            ->setFactory(new Reference(NewsletterManagerFactory::class));
+
 .. _factories-passing-arguments-factory-method:
 
 Passing Arguments to the Factory Method