minor #7377 More clear description of factory service creation (hvt)

xabbuh · xabbuh · commit 67cdaaeb0942 · 2017-01-31T22:15:22.000+01:00
This PR was submitted for the master branch but it was merged into the 2.7 branch instead (closes #7377). Discussion ---------- More clear description of factory service creation I found the service container factory description a bit ambiguous. Especially the two different examples of both static and regular create method usage. Hopefully this clarifies some things. Eager to know what you guys think... Commits ------- a5f99d8 More clear description of factory service creation
diff --git a/service_container/factories.rst b/service_container/factories.rst
@@ -18,9 +18,9 @@ instantiating the class.
     syntax for factories prior to 2.6.
 
 Suppose you have a factory that configures and returns a new ``NewsletterManager``
-object::
+object by calling the static ``createNewsletterManager()`` method::
 
-    class NewsletterManagerFactory
+    class NewsletterManagerStaticFactory
     {
         public static function createNewsletterManager()
         {
@@ -34,45 +34,98 @@ object::
 
 To make the ``NewsletterManager`` object available as a service, you can
 configure the service container to use the
-``NewsletterManagerFactory::createNewsletterManager()`` factory method:
+``NewsletterManagerStaticFactory::createNewsletterManager()`` factory method:
 
 .. configuration-block::
 
     .. code-block:: yaml
 
+        # app/config/services.yml
+
         services:
             app.newsletter_manager:
                 class:   AppBundle\Email\NewsletterManager
-                # call a static method
-                factory: ['AppBundle\Email\NewsletterManager', create]
+                # call the static method
+                factory: ['AppBundle\Email\NewsletterManagerStaticFactory', createNewsletterManager]
+
+    .. 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.newsletter_manager" class="AppBundle\Email\NewsletterManager">
+                    <!-- call the static method -->
+                    <factory class="AppBundle\Email\NewsletterManagerStaticFactory" method="createNewsletterManager" />
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/services.php
+
+        use AppBundle\Email\NewsletterManager;
+        use AppBundle\Email\NewsletterManagerStaticFactory;
+        use Symfony\Component\DependencyInjection\Definition;
+        // ...
+
+        $definition = new Definition(NewsletterManager::class);
+        // call the static method
+        $definition->setFactory(array(NewsletterManagerStaticFactory::class, 'createNewsletterManager'));
+
+        $container->setDefinition('app.newsletter_manager', $definition);
+
+.. note::
+
+    When using a factory to create services, the value chosen for the ``class``
+    option has no effect on the resulting service. The actual class name
+    only depends on the object that is returned by the factory. However,
+    the configured class name may be used by compiler passes and therefore
+    should be set to a sensible value.
+
+If your factory is not using a static function to configure and create your
+service, but a regular method, you can instantiate the factory itself as a
+service too. Later, in the ":ref:`factories-passing-arguments-factory-method`"
+section, you learn how you can inject arguments in this method.
+
+Configuration of the service container then looks like this:
+
+.. configuration-block::
+
+    .. code-block:: yaml
 
+        # app/config/services.yml
+
+        services:
             app.newsletter_manager_factory:
                 class: AppBundle\Email\NewsletterManagerFactory
 
             app.newsletter_manager:
                 class:   AppBundle\Email\NewsletterManager
-                # call a method on the specified service
+                # call a method on the specified factory service
                 factory: 'app.newsletter_manager_factory:createNewsletterManager'
 
     .. 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.newsletter_manager" class="AppBundle\Email\NewsletterManager">
-                    <!-- call a static method -->
-                    <factory class="AppBundle\Email\NewsletterManager" method="create" />
-                </service>
-
                 <service id="app.newsletter_manager_factory"
                     class="AppBundle\Email\NewsletterManagerFactory"
                 />
 
                 <service id="app.newsletter_manager" class="AppBundle\Email\NewsletterManager">
-                    <!-- call a method on the specified service -->
+                    <!-- call a method on the specified factory service -->
                     <factory service="app.newsletter_manager_factory"
                         method="createNewsletterManager"
                     />
@@ -82,50 +135,42 @@ configure the service container to use the
 
     .. code-block:: php
 
+        // app/config/services.php
+
         use AppBundle\Email\NewsletterManager;
         use AppBundle\Email\NewsletterManagerFactory;
         use Symfony\Component\DependencyInjection\Definition;
         // ...
 
-        $definition = new Definition(NewsletterManager::class);
-        // call a static method
-        $definition->setFactory(array(NewsletterManager::class, 'create'));
-
-        $container->setDefinition('app.newsletter_manager', $definition);
-
         $container->register('app.newsletter_manager_factory', NewsletterManagerFactory::class);
 
         $newsletterManager = new Definition(NewsletterManager::class);
 
-        // call a method on the specified service
+        // call a method on the specified factory service
         $newsletterManager->setFactory(array(
             new Reference('app.newsletter_manager_factory'),
             'createNewsletterManager'
         ));
 
         $container->setDefinition('app.newsletter_manager', $newsletterManager);
 
-.. note::
-
-    When using a factory to create services, the value chosen for the ``class``
-    option has no effect on the resulting service. The actual class name
-    only depends on the object that is returned by the factory. However,
-    the configured class name may be used by compiler passes and therefore
-    should be set to a sensible value.
-
 .. note::
 
     The traditional configuration syntax in YAML files used an array to define
     the factory service and the method name:
 
     .. code-block:: yaml
 
+        # app/config/services.yml
+
         app.newsletter_manager:
             # new syntax
             factory: 'app.newsletter_manager_factory:createNewsletterManager'
             # old syntax
             factory: ['@app.newsletter_manager_factory', createNewsletterManager]
 
+.. _factories-passing-arguments-factory-method:
+
 Passing Arguments to the Factory Method
 ---------------------------------------
 
@@ -137,6 +182,8 @@ method in the previous example takes the ``templating`` service as an argument:
 
     .. code-block:: yaml
 
+        # app/config/services.yml
+
         services:
             # ...
 
@@ -147,6 +194,8 @@ method in the previous example takes the ``templating`` service as an argument:
 
     .. 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"
@@ -164,6 +213,8 @@ method in the previous example takes the ``templating`` service as an argument:
 
     .. code-block:: php
 
+        // app/config/services.php
+
         use AppBundle\Email\NewsletterManager;
         use Symfony\Component\DependencyInjection\Reference;
         use Symfony\Component\DependencyInjection\Definition;
