[DI] Add section about Service Locators

chalasr · chalasr · commit 36a3f92c7817 · 2017-02-10T00:05:28.000+01:00
diff --git a/service_container/service_locators.rst b/service_container/service_locators.rst
@@ -0,0 +1,155 @@
+.. index::
+    single: DependencyInjection; Service Locators
+
+Service Locators
+================
+
+What is a Service Locator
+-------------------------
+
+Sometimes, a service needs the ability to access other services without being sure
+that all of them will actually be used.
+
+In such cases, you may want the instantiation of these services to be lazy, that is
+not possible using explicit dependency injection since services are not all meant to
+be ``lazy`` (see :doc:`/service_container/lazy_services`).
+
+A real-world example being a CommandBus which maps CommandHandler services by Command
+class names and use them to handle their respective command when it is asked for::
+
+    // ...
+    class CommandBus
+    {
+        /**
+         * @var CommandHandler[]
+         */
+        private $handlerMap;
+
+        // ...
+
+        public function handle(Command $command)
+        {
+            if (isset($handlerMap[$commandClass = get_class($command)])) {
+                $handler = $handlerMap[$commandClass];
+
+                return $handler->handle($command);
+            }
+        }
+    }
+
+    // ...
+    $commandBus->handle(new FooCommand());
+
+Because only one command is handled at a time, other CommandHandler services are not
+used but unnecessarily instantiated.
+
+Service Locators are intended to solve this problem by giving access to a set of
+identified services while instantiating them only when really needed, providing
+laziness.
+
+Configuration
+-------------
+
+For injecting a service locator in a service, use the `service_locator` argument
+type and define the set of services that needs to be accessible from:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        services:
+
+            app.command_bus:
+                class: AppBundle\CommandBus
+                arguments:
+                    - =service_locator:
+                        AppBundle\FooCommand: '@app.command_handler.foo'
+                        AppBundle\BarCommand: '@app.command_handler.bar'
+
+    .. code-block:: 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="app.command_bus" class="AppBundle\CommandBus">
+                    <argument type="service-locator">
+                        <argument key="AppBundle\FooCommand" type="service" id="app.command_handler.foo" />
+                        <argument key="AppBundle\BarCommand" type="service" id="app.command_handler.bar" />
+                    </argument>
+                </service>
+
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        use Symfony\Component\DependencyInjection\Argument\ServiceLocatorArgument;
+        use Symfony\Component\DependencyInjection\Reference;
+
+        //...
+
+        $container
+            ->register('app.command_bus')
+            ->setArguments(array(new ServiceLocatorArgument(array(
+                'AppBundle\FooCommand' => new Reference('app.command_handler.foo'),
+                'AppBundle\BarCommand' => new Reference('app.command_handler.bar'),
+            ))))
+        ;
+
+.. note::
+
+    The services defined in the service locator argument must be keyed,
+    as keys become their unique identifier inside the locator.
+
+.. tip::
+
+    Not only services can be passed accessible through a service locator,
+    but all types which are supported by the configuration format used to
+    configure it.
+
+Usage
+-----
+
+Back to our CommandBus which would now look like::
+
+    // ...
+    use Psr\Container\ContainerInterface;
+
+    class CommandBus
+    {
+        /**
+         * @var ContainerInterface
+         */
+        private $handlerMap;
+
+        // ...
+
+        public function handle(Command $command)
+        {
+            $commandClass = get_class($command);
+            $handler = $this->handlerMap->get($commandClass);
+
+            return $handler->handle($command);
+        }
+    }
+
+The injected service is an instance of :class:`Symfony\\Component\\DependencyInjection\\ServiceLocator`
+which implements the PSR-11 ``ContainerInterface`` but is also a callable::
+
+    // ...
+    $handlerMap = $this->handlerMap;
+
+    return $handlerMap($handlerId)->handle($command);
+
+And can be used in a loop to iterate over all available services::
+
+    // ...
+    foreach ($this->handlerMap as $commandClass => $handler) {
+        if ($commandClass === get_class($command)) {
+            return $handler->handle($command);
+        }
+    }
