@@ -218,3 +218,48 @@ You can change the inner service name if you want to:
218218 ->addArgument(new Reference('bar.wooz'))
219219 ->setPublic(false)
220220 ->setDecoratedService('foo', 'bar.wooz');
221+
222+
223+ --------------------
224+
225+ Once you have decided to deprecate the use of a service (because it is outdated,
226+ or you decided not to use and maintain it anymore), you can deprecate its
227+ definition:
228+
229+ ..configuration-block ::
230+
231+ .. code-block: yaml
232+
233+ bar:
234+ class: stdClass
235+ deprecated: true
236+ deprecation_message: The 'bar' service is deprecated. You should stop using it, as it will soon be removed.
237+
238+ .. code-block:: xml
239+
240+ <service id="bar" class="stdClass">
241+ <deprecated>The 'bar' service is deprecated. You should stop using it, as it will soon be removed.</deprecated>
242+ </service>
243+
244+ .. code-block:: php
245+
246+ $container->register('bar', 'stdClass')
247+ ->setDeprecated(true, 'The \'%service_id%\' service is deprecated. You should stop using it, as it will soon be removed.');
248+
249+
250+ trigger a deprecation error, advising you to stop or change your uses of that
251+ service.
252+
253+ ..note ::
254+ The deprecation message is optional. If not set, Symfony will show a default
255+ message ``The '%service_id%' service is deprecated. You should stop using it,
256+ as it will soon be removed. ``
257+
258+ ..note ::
259+ The message is actually a template message, which will replace occurrences
260+ of ``%service_id% `` by the service's id. While this is not really necessary
261+ while using the XML or YAML loaders, it should be used for the PHP definition.
262+
263+ For services decorators (see above), if the definition does not modify the
264+ deprecated status, it will inherit the status from the definition that is
265+ decorated.