Jan 17, 2017 · Jan 17, 2017 · Jan 17, 2017 · Jan 17, 2017 · Jan 17, 2017 · Jan 18, 2017
diff --git a/service_container/factories.rst b/service_container/factories.rst
 instantiating the class.

 Suppose you have a factory that configures and returns a new ``NewsletterManager``
 object::
 object by calling the static ``createNewsletterManager()`` method::

    classNewsletterManagerFactory
    classNewsletterManagerStaticFactory
    {
        public static function createNewsletterManager()
        {

 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 specifiedfactoryservice
                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 specifiedfactoryservice -->
                    <factory service="app.newsletter_manager_factory"
                        method="createNewsletterManager"
                    />

    .. 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 specifiedfactoryservice
        $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
 ---------------------------------------


    .. code-block:: yaml

        # app/config/services.yml

        services:
            # ...


    .. 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"

    .. code-block:: php

        // app/config/services.php

        use AppBundle\Email\NewsletterManager;
        use Symfony\Component\DependencyInjection\Reference;
        use Symfony\Component\DependencyInjection\Definition;
Original file line number	Diff line number	Diff line change
Expand Up		@@ -13,9 +13,9 @@ the service container to call a method on the factory rather than directly
		instantiating the class.

		Suppose you have a factory that configures and returns a new ``NewsletterManager``
		object::
		object by calling the static ``createNewsletterManager()`` method::

		classNewsletterManagerFactory
		classNewsletterManagerStaticFactory
Copy link Member javiereguiluzJan 17, 2017 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. This class name looks ugly ... but at the same time it's perfectly understandable. I'm divided about it 😕 Copy link ContributorAuthor hvtJan 17, 2017 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Exactly my thought, I'm happy to change it either way ;].
		{
		public static function createNewsletterManager()
		{
Expand All		@@ -29,45 +29,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

Copy link Member xabbuhJan 17, 2017 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. we should add a comment containing the filename like this: <!-- app/config/services.xml--> Copy link Member xabbuhJan 17, 2017 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Can you please add this for the other formats too (using`config.yml` and`config.php` respectively)? Copy link ContributorAuthor hvtJan 18, 2017 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. I've done this. Am however wondering whether it's not`app/config/services.yml` and`app/config/services.php` to be exactly? Copy link Member xabbuhJan 18, 2017 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Of course, you are absolutely right. Sorry for the confusion. Copy link ContributorAuthor hvtJan 18, 2017 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. No worries ;].
		<!-- 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,
Copy link Member javiereguiluzJan 17, 2017 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. About this: However, the configured class name may be used by compiler passes and therefore should be set to a sensible value. Should I open a Symfony code issue to improve this behavior and make this class optional? Copy link ContributorAuthor hvtJan 17, 2017 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. (This note was already there, don't know why it is marked as new by the diff.) I do however believe the note is still valid, because it might be handy to use the class definition somewhere in a compiler pass. On the other hand, it might be good to check why no active validation is done on the return type of the creation method...
		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 specifiedfactoryservice
		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 specifiedfactoryservice -->
		<factory service="app.newsletter_manager_factory"
		method="createNewsletterManager"
		/>
Expand All		@@ -77,50 +130,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 specifiedfactoryservice
		$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
		---------------------------------------

Expand All		@@ -132,6 +177,8 @@ method in the previous example takes the ``templating`` service as an argument:

		.. code-block:: yaml

		# app/config/services.yml

		services:
		# ...

Expand All		@@ -142,6 +189,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"
Expand All		@@ -159,6 +208,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;
Expand Down