Apr 3, 2014 · Apr 3, 2014 · Apr 4, 2014 · Apr 4, 2014 · Sep 11, 2014 · Sep 16, 2014
diff --git a/components/dependency_injection/advanced.rst b/components/dependency_injection/advanced.rst

 Notice that Symfony will internally call the PHP statement ``require_once``,
 which means that your file will be included only once per request.

 Decorating Services
 -------------------

 .. versionadded:: 2.5
    Decorated services were introduced in Symfony 2.5.

 When overriding an existing definition, the old service is lost:

 .. code-block:: php

    $container->register('foo', 'FooService');

    // this is going to replace the old definition with the new one
    // old definition is lost
    $container->register('foo', 'CustomFooService');

 Most of the time, that's exactly what you want to do. But sometimes,
 you might want to decorate the old one instead. In this case, the
 old service should be kept around to be able to reference it in the
 new one. This configuration replaces ``foo`` with a new one, but keeps
 a reference of the old one  as ``bar.inner``:

 .. configuration-block::

    .. code-block:: yaml

       bar:
         public: false
         class: stdClass
         decorates: foo
         arguments: ["@bar.inner"]

    .. code-block:: xml

        <service id="bar" class="stdClass" decorates="foo" public="false">
            <argument type="service" id="bar.inner" />
        </service>

    .. code-block:: php

        use Symfony\Component\DependencyInjection\Reference;

        $container->register('bar', 'stdClass')
            ->addArgument(new Reference('bar.inner'))
            ->setPublic(false)
            ->setDecoratedService('foo');

 Here is what's going on here: the ``setDecoratedService()` method tells
 the container that the ``bar`` service should replace the ``foo`` service,
 renaming ``foo`` to ``bar.inner``.
 By convention, the old ``foo`` service is going to be renamed ``bar.inner``,
 so you can inject it into your new service.

 .. note::
    The generated inner id is based on the id of the decorator service
    (``bar`` here), not of the decorated service (``foo`` here).  This is
    mandatory to allow several decorators on the same service (they need to have
    different generated inner ids).

    Most of the time, the decorator should be declared private, as you will not
    need to retrieve it as ``bar`` from the container. The visibility of the
    decorated ``foo`` service (which is an alias for ``bar``) will still be the
    same as the original ``foo`` visibility.

 You can change the inner service name if you want to:

 .. configuration-block::

    .. code-block:: yaml

       bar:
         class: stdClass
         public: false
         decorates: foo
         decoration_inner_name: bar.wooz
         arguments: ["@bar.wooz"]

    .. code-block:: xml

        <service id="bar" class="stdClass" decorates="foo" decoration-inner-name="bar.wooz" public="false">
            <argument type="service" id="bar.wooz" />
        </service>

    .. code-block:: php

        use Symfony\Component\DependencyInjection\Reference;

        $container->register('bar', 'stdClass')
            ->addArgument(new Reference('bar.wooz'))
            ->setPublic(false)
            ->setDecoratedService('foo', 'bar.wooz');
Original file line number	Diff line number	Diff line change
Expand Up		@@ -185,3 +185,95 @@ the service itself gets loaded. To do so, you can use the ``file`` directive.

		Notice that Symfony will internally call the PHP statement ``require_once``,
		which means that your file will be included only once per request.

		Decorating Services
		-------------------

		.. versionadded:: 2.5
		Decorated services were introduced in Symfony 2.5.

		When overriding an existing definition, the old service is lost:

		.. code-block:: php

		$container->register('foo', 'FooService');

		// this is going to replace the old definition with the new one
		// old definition is lost
		$container->register('foo', 'CustomFooService');

		Most of the time, that's exactly what you want to do. But sometimes,
		you might want to decorate the old one instead. In this case, the
		old service should be kept around to be able to reference it in the
		new one. This configuration replaces ``foo`` with a new one, but keeps
		a reference of the old one as ``bar.inner``:

		.. configuration-block::

		.. code-block:: yaml

		bar:
		public: false
		class: stdClass
		decorates: foo
		arguments: ["@bar.inner"]

		.. code-block:: xml

		<service id="bar" class="stdClass" decorates="foo" public="false">
		<argument type="service" id="bar.inner" />
		</service>

		.. code-block:: php

		use Symfony\Component\DependencyInjection\Reference;

		$container->register('bar', 'stdClass')
		->addArgument(new Reference('bar.inner'))
		->setPublic(false)
		->setDecoratedService('foo');
Copy link Member wouterjApr 3, 2014 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. I would prefer if we used`Definition` and`Container#setDefinition` here

		Here is what's going on here: the ``setDecoratedService()` method tells
		the container that the ``bar`` service should replace the ``foo`` service,
		renaming ``foo`` to ``bar.inner``.
		By convention, the old ``foo`` service is going to be renamed ``bar.inner``,
		so you can inject it into your new service.
Copy link Member xabbuhApr 4, 2014 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. What about using`foo` and`bar` as the service names? I guess, that would make thing more clear. With the current situation, people might think that the names of the decorated service and that of the decorating service must be the same except of the`1`. Copy link ContributorAuthor romainneutronApr 4, 2014 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. 👍

Copy link Contributor docteurkleinSep 11, 2014 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. `foo` and`bar` are sooo confusing! Wouldn't it be better to use a real world example, let's say a`router` ? We would have`router`,`router.inner` and`custom_router` f.e. Copy link Member weaverryanSep 16, 2014 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Yes, in fact, why not use a real service from the framework? Sure, this is the components, butany service we choose here will be "invented", so why not use on that's a real service somewhere.
		.. note::
		The generated inner id is based on the id of the decorator service
		(``bar`` here), not of the decorated service (``foo`` here). This is
		mandatory to allow several decorators on the same service (they need to have
		different generated inner ids).

		Most of the time, the decorator should be declared private, as you will not
		need to retrieve it as ``bar`` from the container. The visibility of the
		decorated ``foo`` service (which is an alias for ``bar``) will still be the
		same as the original ``foo`` visibility.

		You can change the inner service name if you want to:

		.. configuration-block::

		.. code-block:: yaml

		bar:
		class: stdClass
		public: false
		decorates: foo
		decoration_inner_name: bar.wooz
		arguments: ["@bar.wooz"]

		.. code-block:: xml

		<service id="bar" class="stdClass" decorates="foo" decoration-inner-name="bar.wooz" public="false">
		<argument type="service" id="bar.wooz" />
		</service>

		.. code-block:: php

		use Symfony\Component\DependencyInjection\Reference;

		$container->register('bar', 'stdClass')
		->addArgument(new Reference('bar.wooz'))
Copy link Member wouterjApr 10, 2014 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. missing use statement
		->setPublic(false)
		->setDecoratedService('foo', 'bar.wooz');