Add Usage and Subscribed services sections to Service subscribers

Author: codedmonkey

service_container/service_subscribers.rst

@@ -4,19 +4,21 @@ single: DependencyInjection; Service Subscribers
 Service Subscribers
 ================
 
-Symfony's Service Locators provide a powerful way of passing a subset of
-services from the service container to a service. Sometimes, you may want a
-more concrete way of defining the services contained within a service locator.
-By implementing ``ServiceSubscriberInterface`` you can specify the contents of
-the service locator from the object itself. This is useful when a set of
-services have the same parent class and similar dependencies.
+Symfony's :doc:`Service Locators </service_container/service_locators>` provide
+a powerful way of passing a subset of services from the service container to a
+service. Sometimes, you may want a more concrete way of defining the services
+contained within a service locator. By implementing
+:class:`Symfony\\Component\\DependencyInjection\\ServiceSubscriberInterface`
+you can specify the contents of the service locator from the object itself.
+This is useful when a set of services have the same parent class and similar
+dependencies.
 
 Suppose you've got a mailing system with multiple ``Updater`` classes for
 sending out mails on different occasions. Since every updater has the same
 purpose, we start with a base updater::
 
-    // src/Updates/AbstractUpdater.php
-    namespace App\Updates;
+    // src/AppBundle/Updates/AbstractUpdater.php
+    namespace AppBundle\Updates;
 
     use Twig\Environment;
 
@@ -56,10 +58,10 @@ purpose, we start with a base updater::
 
 Now that we have a base class, we can add updaters for different entities. Note
 that we have to inject the dependencies of ``AbstractUpdater`` to each
-updater.::
+updater::
 
-    // src/Updates/FooUpdater.php
-    namespace App\Updates;
+    // src/AppBundle/Updates/FooUpdater.php
+    namespace AppBundle\Updates;
 
     use Doctrine\Common\Persistence\ManagerRegistry;
     use Twig\Environment;
@@ -84,9 +86,10 @@ updater.::
         }
     }
 
-    // src/Updates/BarUpdater.php
-    namespace App\Updates;
+    // src/AppBundle/Updates/BarUpdater.php
+    namespace AppBundle\Updates;
 
+    use AppBundle\BarManager;
     use Doctrine\Common\Persistence\ManagerRegistry;
     use Twig\Environment;
 
@@ -95,7 +98,7 @@ updater.::
         private $doctrine;
         private $barManager;
 
-        public function __construct(\Swift_Mailer $mailer, Environment $twig, ManagerRegistry $doctrine, $barManager = null)
+        public function __construct(\Swift_Mailer $mailer, Environment $twig, ManagerRegistry $doctrine, BarManager $barManager)
         {
             parent::__construct($mailer, $twig);
 
@@ -112,10 +115,11 @@ updater.::
         }
     }
 
-If you're using the `default services.yaml configuration`_, no additional
-configuration is required for these services thanks to autowiring, but
-maintaining the list of dependencies through constructor injection will quickly
-become cumbersome, especially if you add a dependency in ``AbstractUpdater``.
+If you're using the :ref:`default services.yml configuration <service-container-services-load-example>`,
+no additional configuration is required for these services thanks to autowiring,
+but maintaining the list of dependencies through constructor injection will
+quickly become cumbersome, especially if you add a dependency in
+``AbstractUpdater``.
 
 By creating a service subscriber of the base class, we can create a more
 practical solution for our dependencies.
@@ -126,50 +130,274 @@ Defining a Service Subscriber
 First, turn ``AbstractUpdater`` into an implementation of
 ``ServiceSubscriberInterface`` by adding the static method
 ``getSubscribedServices`` which maintains a list of subscribed services and
-replacing our dependencies with a service locator.::
+replacing our dependencies with a service locator::
+
+    // src/AppBundle/Updates/AbstractUpdater.php
+    namespace AppBundle\Updates;
+
+    use Doctrine\Common\Persistence\ManagerRegistry;
+    use Psr\Container\ContainerInterface;
+    use Symfony\Component\DependencyInjection\ServiceSubscriberInterface;
+    use Twig\Environment;
+
+    abstract class AbstractUpdater implements ServiceSubscriberInterface
+    {
+        protected $locator;
+
+        public function __construct(ContainerInterface $locator)
+        {
+            $this->locator = $locator;
+        }
+
+        public static function getSubscribedServices()
+        {
+            return [
+                'doctrine' => '?'.ManagerRegistry::class,
+                'mailer' => \Swift_Mailer::class,
+                'twig' => Environment::class
+            ];
+        }
+
+
+        abstract public function update($entity);
+
+        /**
+         * Renders a view with Twig
+         */
+        public function render($template, $parameters)
+        {
+            return $this->locator->get('twig')->render($template, $parameters);
+        }
+
+        /**
+         * Sends an email with Swiftmailer
+         */
+        public function send($recipient, $title, $body)
+        {
+            $message = new \Swift_Message();
+
+            // ...
+
+            $this->locator->get('mailer')->send($message);
+        }
+    }
 
-    <code>
 
 With this newly created service subscriber, the updaters can be adapted to
 coincide with the service locator::
 
-    <code>
+    // src/AppBundle/Updates/FooUpdater.php
+    namespace AppBundle\Updates;
+
+    class FooUpdater extends AbstractUpdater
+    {
+        public function update($entity)
+        {
+            // ...
+
+            $body = $this->render('Emails/foo_update.html.twig', [/* ... */]);
+            $this->send($entity->getRecipient(), 'Foo update', $body);
+        }
+    }
+
+    // src/AppBundle/Updates/BarUpdater.php
+    namespace AppBundle\Updates;
+
+    use AppBundle\BarManager;
+    use Psr\Container\ContainerInterface;
+
+    class BarUpdater extends AbstractUpdater
+    {
+        private $barManager;
+
+        public function __construct(ContainerInterface $locator, BarManager $barManager)
+        {
+            parent::__construct($locator);
+
+            $this->barManager = $barManager;
+        }
+
+        public function update($entity)
+        {
+            // ...
+
+            $body = $this->render('Emails/bar_update.html.twig', [/* ... */]);
+            $this->send($entity->getRecipient(), 'Bar update', $body);
+        }
+    }
 
 Optionally, you'll need to add the ``container.service_subscriber`` tag to
-configure the services to be recognized as service subscribers.
+the services definitions of the updaters to enable the service subscribers.
 
 .. configuration-block::
 
     .. code-block:: yaml
 
-        <code>
+        // app/config/services.yml
+        services:
+            AppBundle\Updates\:
+                resource: '../src/Updates'
+                tags: ['container.service_subscriber']
+
+        // or
+
+        services:
+            AppBundle\Updates\FooUpdater:
+                tags: ['container.service_subscriber']
+
+            AppBundle\Updates\BarUpdater:
+                tags: ['container.service_subscriber']
+                arguments:
+                    - '@Psr\Container\ContainerInterface'
+                    - '@AppBundle\BarManager'
 
     .. code-block:: xml
 
-        <code>
+        <!-- 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\Updates\" resource="../src/Updates">
+                    <tag name="container.service_subscriber" />
+                </prototype>
+
+            </services>
+        </container>
 
     .. code-block:: php
 
         <code>
 
+Subscribed services
+-------------------
+
+Service subscribers rely on the ``getSubscribedServices()`` method to return a
+list of services types required to build a service locator for instances of
+that service subscriber::
+
+    use Psr\Log\LoggerInterface;
+
+    public static function getSubscribedServices()
+    {
+        return [
+            'AppBundle\FooInterface',
+            LoggerInterface::class
+        ];
+    }
+
+Service types can optionally be keyed by the service names used internally by
+the service subscriber::
+
+    use Psr\Log\LoggerInterface;
+
+    public static function getSubscribedServices()
+    {
+        return [
+            'foo' => 'AppBundle\FooInterface',
+            'logger' => LoggerInterface::class
+        ];
+    }
+
+Optional dependencies
+~~~~~~~~~~~~~~~~~~~~~
+
+For optional dependencies, prepend the service type with a ``?`` to prevent
+errors if the service type has not been implemented in the service container::
+
+    use Psr\Log\LoggerInterface;
+
+    public static function getSubscribedServices()
+    {
+        return [
+            '?AppBundle\FooInterface',
+            'logger' => '?'.LoggerInterface::class
+        ];
+    }
+
+.. note::
+
+    Make sure an optional service exists by calling ``has()`` on the service
+    locator before calling the service itself.
+
 Usage
 -----
 
-Subscribed services
--------------------
+Add the ``container.service_subscriber`` tag to a service definition to turn it
+into a service subscriber and add a ``Psr\Container\ContainerInterface``
+argument to pass the generated service locator to the service instance.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        // app/config/services.yml
+        services:
+            AppBundle\FooHandler:
+                tags: ['container.service_subscriber']
+                arguments:
+                    - '@Psr\Container\ContainerInterface'
 
-Returns an array of service types required by such instances, optionally keyed by the service names used internally.
+    .. 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="app.foo_handler" class="AppBundle\FooHandler">
+                    <argument type="service" id="Psr\Container\ContainerInterface" />
+                    <tag name="container.service_subscriber" />
+                </service>
 
-For mandatory dependencies:
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        <code>
 
- * array('logger' => 'Psr\Log\LoggerInterface') means the objects use the "logger" name
-   internally to fetch a service which must implement Psr\Log\LoggerInterface.
- * array('Psr\Log\LoggerInterface') is a shortcut for
- * array('Psr\Log\LoggerInterface' => 'Psr\Log\LoggerInterface')
+An instance of this service would look like this::
 
-otherwise:
+    namespace AppBundle;
 
- * array('logger' => '?Psr\Log\LoggerInterface') denotes an optional dependency
- * array('?Psr\Log\LoggerInterface') is a shortcut for
- * array('Psr\Log\LoggerInterface' => '?Psr\Log\LoggerInterface')
+    use Psr\Container\ContainerInterface;
+    use Psr\Log\LoggerInterface;
+    use Symfony\Component\DependencyInjection\ServiceSubscriberInterface;
+
+    class FooHandler implements ServiceSubscriberInterface
+    {
+        /**
+         * @var ContainerInterface
+         */
+        private $locator;
+
+        public function __construct(ContainerInterface $locator)
+        {
+            $this->locator = $locator;
+        }
+
+        public static function getSubscribedServices()
+        {
+            return [
+                'AppBundle\FooInterface',
+                'logger' => '?'.LoggerInterface::class
+            ];
+        }
+
+        public function handle()
+        {
+            $this->locator->get('AppBundle\FooInterface')->execute();
+
+            if ($this->locator->has('logger')) {
+                $this->locator->get('logger')->info('Executed foo.');
+            }
+        }
+    }