Refactor service locators article to primarily describe service subscribers

Author: codedmonkey

service_container/lazy_services.rst

@@ -6,7 +6,7 @@ Lazy Services
 
 .. seealso::
 
-    Another way to inject services lazily is via a :doc:`service locator </service_container/service_locators>`.
+    Another way to inject services lazily is via a :doc:`service subscriber </service_container/service_subscribers>`.
 
 Why Lazy Services?
 ------------------

service_container/service_locators.rst renamed to service_container/service_subscribers.rst

@@ -1,8 +1,8 @@
 .. index::
-    single: DependencyInjection; Service Locators
+    single: DependencyInjection; Service Subscribers
 
-Service Locators
-================
+Service Subscribers
+===================
 
 Sometimes, a service needs access to several other services without being sure
 that all of them will actually be used. In those cases, you may want the
@@ -77,15 +77,177 @@ However, injecting the entire container is discouraged because it gives too
 broad access to existing services and it hides the actual dependencies of the
 services.
 
-**Service Locators** are intended to solve this problem by giving access to a
-set of predefined services while instantiating them only when actually needed.
+**Service Subscribers** are intended to solve this problem by giving access to a
+set of predefined services while instantiating them only when actually needed
+through a service locator.
+
+Defining a Service Subscriber
+-----------------------------
+
+First, turn ``CommandBus`` into an implementation of :class:`Symfony\\Component\\DependencyInjection\\ServiceSubscriberInterface`.
+Use its ``getSubscribedServices`` method to include as many services as needed
+in the service locater and change the container to a PSR-11 ``ContainerInterface``::
+
+    // src/AppBundle/CommandBus.php
+    namespace AppBundle;
+
+    use AppBundle\CommandHandler\BarHandler;
+    use AppBundle\CommandHandler\FooHandler;
+    use Psr\Container\ContainerInterface;
+    use Symfony\Component\DependencyInjection\ServiceSubscriberInterface;
+
+    class CommandBus implements ServiceSubscriberInterface
+    {
+        private $locator;
+
+        public function __construct(ContainerInterface $locator)
+        {
+            $this->locator = $locator;
+        }
+
+        public static function getSubscribedServices()
+        {
+            return [
+                'AppBundle\FooCommand' => FooHandler::class,
+                'AppBundle\BarCommand' => BarHandler::class
+            ];
+        }
+
+        public function handle(Command $command)
+        {
+            $commandClass = get_class($command);
+
+            if ($this->locator->has($commandClass)) {
+                $handler = $this->locator->get($commandClass);
+
+                return $handler->handle($command);
+            }
+        }
+    }
+
+.. tip::
+
+    If the container does *not* contain the subscribed services, double-check
+    that you  have :ref:`autoconfigure <services-autoconfigure>` enabled. You
+    can also manually add the ``container.service_subscriber`` tag.
+
+The injected service is an instance of :class:`Symfony\\Component\\DependencyInjection\\ServiceLocator`
+which implements the PSR-11 ``ContainerInterface``, but it is also a callable::
+
+    // ...
+    $locateHandler = $this->locator;
+    $handler = $locateHandler($commandClass);
+
+    return $handler->handle($command);
+
+Including services
+------------------
+
+In order to add a new dependency to the service subscriber, use the
+``getSubscribedServices()`` method to add service types to include in the
+service locator::
+
+    use Psr\Log\LoggerInterface;
+
+    public static function getSubscribedServices()
+    {
+        return [
+            //...
+            LoggerInterface::class
+        ];
+    }
+
+Service types can also be keyed by a service name for use internally::
+
+    use Psr\Log\LoggerInterface;
+
+    public static function getSubscribedServices()
+    {
+        return [
+            //...
+            'logger' => LoggerInterface::class
+        ];
+    }
+
+Optional services
+~~~~~~~~~~~~~~~~~
+
+For optional dependencies, prepend the service type with a ``?`` to prevent
+errors if there's no matching service in the service container::
+
+    use Psr\Log\LoggerInterface;
+
+    public static function getSubscribedServices()
+    {
+        return [
+            //...
+            '?'.LoggerInterface::class
+        ];
+    }
+
+.. note::
+
+    Make sure an optional service exists by calling ``has()`` on the service
+    locator before calling the service itself.
+
+Aliased services
+~~~~~~~~~~~~~~~~
+
+By default, autowiring is used to match a service type to a service from the
+service container. If you don't use autowiring or need to add a non-traditional
+service as a dependency, use the ``container.service_subscriber`` tag to map a
+service type to a service.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        // app/config/services.yml
+        services:
+            AppBundle\CommandBus:
+                tags:
+                    - { name: 'container.service_subscriber', key: 'logger', id: 'monolog.logger.event' }
+
+    .. 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\CommandBus">
+                    <tag name="container.service_subscriber" key="logger" id="monolog.logger.event" />
+                </service>
+
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/services.php
+        use AppBundle\CommandBus;
+
+        //...
+
+        $container
+            ->register(CommandBus::class)
+            ->addTag('container.service_subscriber', array('key' => 'logger', 'id' => 'monolog.logger.event'))
+        ;
+
+.. tip::
+
+    The ``key`` attribute can be omitted if the service name internally is the
+    same as in the service container.
 
 Defining a Service Locator
 --------------------------
 
-First, define a new service for the service locator. Use its ``arguments``
-option to include as many services as needed to it and add the
-``container.service_locator`` tag to turn it into a service locator:
+To manually define a service locator, create a new service definition and add
+the ``container.service_locator`` tag to it. Use its ``arguments`` option to
+include as many services as needed in it.
 
 .. configuration-block::
 
@@ -188,45 +350,4 @@ Now you can use the service locator injecting it in any other service:
     If the service locator is not intended to be used by multiple services, it's
     better to create and inject it as an anonymous service.
 
-Usage
------
-
-Back to the previous ``CommandBus`` example, it looks like this when using the
-service locator::
-
-    // ...
-    use Psr\Container\ContainerInterface;
-
-    class CommandBus
-    {
-        /**
-         * @var ContainerInterface
-         */
-        private $handlerLocator;
-
-        // ...
-
-        public function handle(Command $command)
-        {
-            $commandClass = get_class($command);
-
-            if (!$this->handlerLocator->has($commandClass)) {
-                return;
-            }
-
-            $handler = $this->handlerLocator->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 it is also a callable::
-
-    // ...
-    $locateHandler = $this->handlerLocator;
-    $handler = $locateHandler($commandClass);
-
-    return $handler->handle($command);
-
 .. _`Command pattern`: https://en.wikipedia.org/wiki/Command_pattern