minor #7794 [config] Add a note about deprecated a node (sanpii, javiereguiluz)

xabbuh · xabbuh · commit f8ddf1fb3bd7 · 2017-10-13T09:36:43.000+02:00
This PR was submitted for the master branch but it was merged into the 3.4 branch instead (closes #7794). Discussion ---------- [config] Add a note about deprecated a node Documentation for symfony/symfony#22382 Commits ------- 1939371 Explained the possibility of defining custom deprecation messages d6a8624 [config] Add a note about deprecated a node
diff --git a/components/config/definition.rst b/components/config/definition.rst
@@ -424,6 +424,29 @@ has a certain value:
         ->end()
     ;
 
+Deprecating the Option
+----------------------
+
+You can deprecate options using the
+:method:`Symfony\\Component\\Config\\Definition\\Builder\\NodeDefinition::setDeprecated`
+method::
+
+    $rootNode
+        ->children()
+            ->integerNode('old_option')
+                // this outputs the following generic deprecation message:
+                // The child node "old_option" at path "..." is deprecated.
+                ->setDeprecated()
+
+                // you can also pass a custom deprecation message (%node% and %path% placeholders are available):
+                ->setDeprecated('The "%node%" option is deprecated. Use "new_config_option" instead.')
+            ->end()
+        ->end()
+    ;
+
+If you use the Web Debug Toolbar, these deprecation notices are shown when the
+configuration is rebuilt.
+
 Documenting the Option
 ----------------------
 
