diff --git a/cookbook/service_container/service_replacements.rst b/cookbook/service_container/service_replacements.rst new file mode 100644 index 00000000000..6001c9988fd --- /dev/null +++ b/cookbook/service_container/service_replacements.rst @@ -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. + +Lets assume that some bundle provides service with ID ``bundle.service`` +and we want to replace that service with our implementation: + +.. configuration-block:: + + .. code-block:: yaml + + # yoursbundle/Resources/config/services.yml + service: + yoursbundle.my.service: + class: YoursBundle\YourClass + tags: + - { name: framework.service_replacer, replaces: bundle.service } + + .. code-block:: xml + + + + + + + .. code-block:: php + + $container->register('yoursbundle.my.service', 'YoursBundle\YourClass') + ->addTag('framework.service_replacer', array('replaces' => 'bundle.service')); + +Now when you'll request ``bundle.service`` from container, you'll get yours +implementation (``yoursbundle.my.service``) instead. + +.. note:: + + If old service was tagged, the tags will be removed, you have to properly + tag yours definition to behave correctly, as replacement. + +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.