Service subscribers draft

Author: codedmonkey

service_container/service_subscribers.rst

@@ -0,0 +1,175 @@
+.. index::
+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.
+
+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;
+
+    use Twig\Environment;
+
+    abstract class AbstractUpdater
+    {
+        protected $mailer;
+        protected $twig;
+
+        public function __construct(\Swift_Mailer $mailer, Environment $twig)
+        {
+            $this->mailer = $mailer;
+            $this->twig = $twig;
+        }
+
+        abstract public function update($entity);
+
+        /**
+         * Renders a view with Twig
+         */
+        public function render($template, $parameters)
+        {
+            return $this->twig->render($template, $parameters);
+        }
+
+        /**
+         * Sends an email with Swiftmailer
+         */
+        public function send($recipient, $title, $body)
+        {
+            $message = new \Swift_Message();
+
+            // ...
+
+            $this->mailer->send($message);
+        }
+    }
+
+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.::
+
+    // src/Updates/FooUpdater.php
+    namespace App\Updates;
+
+    use Doctrine\Common\Persistence\ManagerRegistry;
+    use Twig\Environment;
+
+    class FooUpdater extends AbstractUpdater
+    {
+        private $doctrine;
+
+        public function __construct(\Swift_Mailer $mailer, Environment $twig, ManagerRegistry $doctrine)
+        {
+            parent::__construct($mailer, $twig);
+
+            $this->doctrine = $doctrine;
+        }
+
+        public function update($entity)
+        {
+            // ...
+
+            $body = $this->render('Emails/foo_update.html.twig', [/* ... */]);
+            $this->send($entity->getRecipient(), 'Foo update', $body);
+        }
+    }
+
+    // src/Updates/BarUpdater.php
+    namespace App\Updates;
+
+    use Doctrine\Common\Persistence\ManagerRegistry;
+    use Twig\Environment;
+
+    class BarUpdater extends AbstractUpdater
+    {
+        private $doctrine;
+        private $barManager;
+
+        public function __construct(\Swift_Mailer $mailer, Environment $twig, ManagerRegistry $doctrine, $barManager = null)
+        {
+            parent::__construct($mailer, $twig);
+
+            $this->doctrine = $doctrine;
+            $this->barManager = $barManager;
+        }
+
+        public function update($entity)
+        {
+            // ...
+
+            $body = $this->render('Emails/bar_update.html.twig', [/* ... */]);
+            $this->send($entity->getRecipient(), 'Bar update', $body);
+        }
+    }
+
+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``.
+
+By creating a service subscriber of the base class, we can create a more
+practical solution for our dependencies.
+
+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.::
+
+    <code>
+
+With this newly created service subscriber, the updaters can be adapted to
+coincide with the service locator::
+
+    <code>
+
+Optionally, you'll need to add the ``container.service_subscriber`` tag to
+configure the services to be recognized as service subscribers.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        <code>
+
+    .. code-block:: xml
+
+        <code>
+
+    .. code-block:: php
+
+        <code>
+
+Usage
+-----
+
+Subscribed services
+-------------------
+
+Returns an array of service types required by such instances, optionally keyed by the service names used internally.
+
+For mandatory dependencies:
+
+ * 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')
+
+otherwise:
+
+ * array('logger' => '?Psr\Log\LoggerInterface') denotes an optional dependency
+ * array('?Psr\Log\LoggerInterface') is a shortcut for
+ * array('Psr\Log\LoggerInterface' => '?Psr\Log\LoggerInterface')
+