Skip to content

Commit

Permalink
[DI] Add some documentation for the deprecation feature
Browse files Browse the repository at this point in the history
  • Loading branch information
Taluu committed Sep 14, 2015
1 parent de141d5 commit cebdb1b
Showing 1 changed file with 51 additions and 0 deletions.
51 changes: 51 additions & 0 deletions components/dependency_injection/advanced.rst
Original file line number Diff line number Diff line change
Expand Up @@ -218,3 +218,54 @@ You can change the inner service name if you want to:
->addArgument(new Reference('bar.wooz'))
->setPublic(false)
->setDecoratedService('foo', 'bar.wooz');
Deprecating Services
--------------------

Once you have decided to deprecate the use of a service (because it is outdated,
or you decided not to use and maintain it anymore), you can deprecate its
definition:

.. configuration-block::

.. code-block: yaml
bar:
class: stdClass
deprecated: true
deprecation_message: The '%service_id%' service is deprecated. You should stop using it, as it will soon be removed.
.. code-block:: xml
<service id="bar" class="stdClass">
<deprecated>The '%service_id%' service is deprecated. You should stop using it, as it will soon be removed.</deprecated>
</service>
.. code-block:: php
$container->register('bar', 'stdClass')
->setDeprecated(true, 'The \'%service_id%\' service is deprecated. You should stop using it, as it will soon be removed.');
Now, every time a service is created using this deprecated definition will
trigger a deprecation error, advising you to stop or change your uses of that
service.

.. note::
The deprecation message is optional. If not set, Symfony will show a default
message ``The '%service_id%' service is deprecated. You should stop using it,
as it will soon be removed.``.

.. note::
The message is actually a template message, which will replace occurrences
of ``%service_id%`` by the service's id. You **must** have at least one
occurrence of ``%service_id%`` in your template message.

.. note::
We really recommand you to fill the template message, to avoid a message that
could be too generic such as the default one. A good message explains
(shortly) why this service was deprecated, from which version and until when
it will be maintained.

For services decorators (see above), if the definition does not modify the
deprecated status, it will inherit the status from the definition that is
decorated.

0 comments on commit cebdb1b

Please sign in to comment.