[DependencyInjection] Add ServiceLocatorArgument to generate array-based locators

service_container/service_subscribers_locators.rst

@@ -246,9 +246,80 @@ service type to a service.
 Defining a Service Locator
 --------------------------
 
-To manually define a service locator, create a new service definition and add
-the ``container.service_locator`` tag to it. Use the first argument of the
-service definition to pass a collection of services to the service locator:
+To manually define a service locator and inject it to another service, create an
+argument of type ``service_locator``:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        services:
+            App\CommandBus:
+                arguments:
+                    !service_locator
+                        App\FooCommand: '@app.command_handler.foo'
+                        App\BarCommand: '@app.command_handler.bar'
+
+    .. 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\CommandBus">
+                    <argument type="service_locator">
+                        <argument key="App\FooCommand" type="service" id="sapp.command_handler.foo"/>
+                        <argument key="App\BarCommandr" type="service" id="app.command_handler.bar"/>
+                        <!-- if the element has no key, the ID of the original service is used -->
+                        <argument type="service" id="app.command_handler.baz"/>
+                    </argument>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+        use App\CommandBus;
+
+        return function(ContainerConfigurator $configurator) {
+            $services = $configurator->services();
+
+            $services->set(CommandBus::class)
+                ->args([service_locator([
+                    'App\FooCommand' => ref('app.command_handler.foo'),
+                    'App\BarCommand' => ref('app.command_handler.bar'),
+                    // if the element has no key, the ID of the original service is used
+                    ref('app.command_handler.baz'),
+                ])]);
+        };
+
+.. versionadded:: 4.2
+
+    The ability to add services without specifying an array key was introduced
+    in Symfony 4.2.
+
+.. versionadded:: 4.2
+
+    The ``service_locator`` argument type was introduced in Symfony 4.2.
+
+As shown in the previous sections, the constructor of the ``CommandBus`` class
+must type-hint its argument with ``ContainerInterface``. Then, you can get any of
+the service locator services via their ID (e.g. ``$this->locator->get('App\FooCommand')``).
+
+Reusing a Service Locator in Multiple Services
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you inject the same service locator in several services, it's better to
+define the service locator as a stand-alone service and then inject it in the
+other services. To do so, create a new service definition using the
+``ServiceLocator`` class:
 
 .. configuration-block::
 
@@ -334,17 +405,7 @@ service definition to pass a collection of services to the service locator:
     previous Symfony versions you always needed to add the
     ``container.service_locator`` tag explicitly.
 
-.. versionadded:: 4.2
-
-    The ability to add services without specifying their id was introduced in
-    Symfony 4.2.
-
-.. note::
-
-    The services defined in the service locator argument must include keys,
-    which later become their unique identifiers inside the locator.
-
-Now you can use the service locator by injecting it in any other service:
+Now you can inject the service locator in any other services:
 
 .. configuration-block::
 
@@ -386,6 +447,9 @@ Now you can use the service locator by injecting it in any other service:
                 ->args([ref('app.command_handler_locator')]);
         };
 
+Using Service Locators in Compiler Passes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 In :doc:`compiler passes </service_container/compiler_passes>` it's recommended
 to use the :method:`Symfony\\Component\\DependencyInjection\\Compiler\\ServiceLocatorTagPass::register`
 method to create the service locators. This will save you some boilerplate and