@@ -218,3 +218,47 @@ 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 service bar 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 service bar 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 %service_id% 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 message is optional, so you can basically set only the status, a
255+ default message will be used instead.
256+
257+ ..note ::
258+ The message is actually a template message, which will replace occurrences
259+ of ``%service_id% `` by the service's id. While this is not really necessary
260+ while using the xml or yaml loaders, it should be used for the php definition.
261+
262+ For services decorators (see above), if the definition does not modify the
263+ deprecated status, it will inherit the status from the definition that is
264+ decorated.