Skip to content

[FrameworkBundle] Document service replacements feature #2228

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

[FrameworkBundle] Document service replacements feature #2228

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
aba4da9
Document service replacements feature
canni Feb 11, 2013
46edfd8
Add info about renameTo tag argument
canni Feb 11, 2013
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions cookbook/service_container/service_replacements.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@

How to replace services and aliases provided by other Bundles
=============================================================

.. versionadded:: 2.3
The ability to replace existing services and aliases
is new to version 2.3

Sometimes you might want to replace service or alias that is provided by
different Bundle; for example you might want to completely re-invent the
wheel or just decorate implementation of particular feature.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sometimes, you might want to replace a service or alias that is provided by
another bundle. For instance, when you want to completelly re-invent the
wheel or just decorate the implementation of a particular feature


Lets assume that some bundle provides service with ID ``bundle.service``
and we want to replace that service with our implementation:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Assume that some bundle provides a service called foo.service and we
want to replace that service with our own implementation. We need to
create a service, which we call Acme\DemoBundle\YourClass, and register
it with the framework.service_replacer tag:


.. configuration-block::

.. code-block:: yaml

# yoursbundle/Resources/config/services.yml
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You should use src/Acme/DemoBundle (or some other bundle name) everywhere in this document.

service:
yoursbundle.my.service:
class: YoursBundle\YourClass
tags:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please put # ... before this line

- { name: framework.service_replacer, replaces: bundle.service }

.. code-block:: xml

<!-- yoursbundle/Resources/config/services.xml -->
<service id="yoursbundle.my.service"
class="YoursBundle\YourClass">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this should be indented 4 spaces

<tag name="framework.service_replacer" replaces="bundle.service" />
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you can place <!-- ... --> before this line

</service>

.. code-block:: php

$container->register('yoursbundle.my.service', 'YoursBundle\YourClass')
->addTag('framework.service_replacer', array('replaces' => 'bundle.service'));
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you should use:

$container
    ->register(...)
    ->addTag(..., array(
        'replaces' => 'bundle.service',
    ))
;


Now when you'll request ``bundle.service`` from container, you'll get yours
implementation (``yoursbundle.my.service``) instead.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now, when you'll request bundle.service from the container, you'll get your
implementation (...) instead of the original one.


.. note::
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this should be a .. caution:: block


If old service was tagged, the tags will be removed, you have to properly
tag yours definition to behave correctly, as replacement.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If an old service was tagged, the tags will be removed. Make sure you have properly
tagged you definition to make it behave correctly.


Old service will be still accessible witch changed ID, by default changed
ID will have ``.orig`` suffix, but you can change it for some completely
different, by setting ``renameTo`` argument on tag.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Old services will still be available from another ID, it will get a
.orig suffix by default. You can override the default behaviour
by setting the renameto argument on the tag.