[DependencyInjection] Enable deprecating parameters

alexandre-daubois · alexandre-daubois · commit 04ad117ff8fa · 2023-01-14T17:58:01.000+01:00
diff --git a/configuration.rst b/configuration.rst
@@ -58,7 +58,7 @@ Configuration Formats
 ~~~~~~~~~~~~~~~~~~~~~
 
 Unlike other frameworks, Symfony doesn't impose a specific format on you to
-configure your applications, but lets you choose between YAML, XML and PHP. 
+configure your applications, but lets you choose between YAML, XML and PHP.
 Throughout the Symfony documentation, all configuration examples will be
 shown in these three formats.
 
diff --git a/service_container.rst b/service_container.rst
@@ -607,6 +607,22 @@ accessor methods for parameters::
     To learn more about compiling the container see
     :doc:`/components/dependency_injection/compilation`.
 
+It is also possible to deprecate a container parameter. This is particularly useful
+if you're writing your own package and want to warn developers to not use a parameter anymore
+because it will be removed in one of the next version of your package.
+Deprecating a container parameter can be done as follow::
+
+    $container->deprecateParameter(
+        'vendor.foo',
+        'vendor-name/package-name', '1.3',
+        // optionally you can set a custom deprecation message
+        '"vendor.foo" is deprecated, you should use "vendor.foo_replacement" instead.'
+    );
+
+.. versionadded:: 6.3
+
+    The ``ContainerBuilder::deprecateParameter`` method was introduced in Symfony 6.3.
+
 .. _services-wire-specific-service:
 
 Choose a Specific Service
