[config] Add ability to deprecate a node

src/Symfony/Component/Config/CHANGELOG.md

@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+3.4.0
+-----
+
+ * added `setDeprecated()` method to indicate a deprecated node
+
 3.3.0
 -----
 

src/Symfony/Component/Config/Definition/ArrayNode.php

@@ -234,6 +234,10 @@ class ArrayNode extends BaseNode implements PrototypeNodeInterface
         }
 
         foreach ($this->children as $name => $child) {
+            if ($child->isDeprecated()) {
+                @trigger_error($child->getDeprecationMessage($name, $this->getPath()), E_USER_DEPRECATED);
+            }
+
             if (!array_key_exists($name, $value)) {
                 if ($child->isRequired()) {
                     $msg = sprintf('The child node "%s" at path "%s" must be configured.', $name, $this->getPath());

src/Symfony/Component/Config/Definition/BaseNode.php

@@ -29,6 +29,7 @@ abstract class BaseNode implements NodeInterface
     protected $finalValidationClosures = array();
     protected $allowOverwrite = true;
     protected $required = false;
+    protected $deprecationMessage = null;
     protected $equivalentValues = array();
     protected $attributes = array();
 
@@ -141,6 +142,19 @@ abstract class BaseNode implements NodeInterface
         $this->required = (bool) $boolean;
     }
 
+    /**
+     * Sets this node as deprecated.
+     *
+     * You can use %node% and %path% placeholders in your message to display,
+     * respectively, the node name and its complete path.
+     *
+     * @param string|null $message Deprecated message
+     */
+    public function setDeprecated($message)
+    {
+        $this->deprecationMessage = $message;
+    }
+
     /**
      * Sets if this node can be overridden.
      *
@@ -181,6 +195,29 @@ abstract class BaseNode implements NodeInterface
         return $this->required;
     }
 
+    /**
+     * Checks if this node is deprecated.
+     *
+     * @return bool
+     */
+    public function isDeprecated()
+    {
+        return null !== $this->deprecationMessage;
+    }
+
+    /**
+     * Returns the deprecated message.
+     *
+     * @param string $node the configuration node name
+     * @param string $path the path of the node
+     *
+     * @return string
+     */
+    public function getDeprecationMessage($node, $path)
+    {
+        return strtr($this->deprecationMessage, array('%node%' => $node, '%path%' => $path));
+    }
+
     /**
      * Returns the name of this node.
      *

src/Symfony/Component/Config/Definition/Builder/NodeDefinition.php

@@ -27,6 +27,7 @@ abstract class NodeDefinition implements NodeParentInterface
     protected $defaultValue;
     protected $default = false;
     protected $required = false;
+    protected $deprecationMessage = null;
     protected $merge;
     protected $allowEmptyValue = true;
     protected $nullEquivalent;
@@ -168,6 +169,23 @@ abstract class NodeDefinition implements NodeParentInterface
         return $this;
     }
 
+    /**
+     * Sets the node as deprecated.
+     *
+     * You can use %node% and %path% placeholders in your message to display,
+     * respectively, the node name and its complete path.
+     *
+     * @param string $message Deprecation message
+     *
+     * @return $this
+     */
+    public function setDeprecated($message = 'The child node "%node%" at path "%path%" is deprecated.')
+    {
+        $this->deprecationMessage = $message;
+
+        return $this;
+    }
+
     /**
      * Sets the equivalent value used when the node contains null.
      *

src/Symfony/Component/Config/Definition/Builder/VariableNodeDefinition.php

@@ -54,6 +54,7 @@ class VariableNodeDefinition extends NodeDefinition
         $node->addEquivalentValue(true, $this->trueEquivalent);
         $node->addEquivalentValue(false, $this->falseEquivalent);
         $node->setRequired($this->required);
+        $node->setDeprecated($this->deprecationMessage);
 
         if (null !== $this->validation) {
             $node->setFinalValidationClosures($this->validation->rules);

src/Symfony/Component/Config/Definition/Dumper/XmlReferenceDumper.php

@@ -153,6 +153,10 @@ class XmlReferenceDumper
                         $comments[] = 'Required';
                     }
 
+                    if ($child->isDeprecated()) {
+                        $comments[] = sprintf('Deprecated (%s)', $child->getDeprecationMessage($child->getName(), $child->getPath()));
+                    }
+
                     if ($child instanceof EnumNode) {
                         $comments[] = 'One of '.implode('; ', array_map('json_encode', $child->getValues()));
                     }

src/Symfony/Component/Config/Definition/Dumper/YamlReferenceDumper.php

@@ -123,6 +123,11 @@ class YamlReferenceDumper
             $comments[] = 'Required';
         }
 
+        // deprecated?
+        if ($node->isDeprecated()) {
+            $comments[] = sprintf('Deprecated (%s)', $node->getDeprecationMessage($node->getName(), $node->getPath()));
+        }
+
         // example
         if ($example && !is_array($example)) {
             $comments[] = 'Example: '.$example;

src/Symfony/Component/Config/Tests/Definition/Dumper/XmlReferenceDumperTest.php

@@ -38,6 +38,8 @@ class XmlReferenceDumperTest extends TestCase
         return str_replace("\n", PHP_EOL, <<<'EOL'
 <!-- Namespace: http://example.org/schema/dic/acme_root -->
 <!-- scalar-required: Required -->
+<!-- scalar-deprecated: Deprecated (The child node "scalar_deprecated" at path "acme_root.scalar_deprecated" is deprecated.) -->
+<!-- scalar-deprecated-with-message: Deprecated (Deprecation custom message for "scalar_deprecated_with_message" at "acme_root.scalar_deprecated_with_message") -->
 <!-- enum-with-default: One of "this"; "that" -->
 <!-- enum: One of "this"; "that" -->
 <config
@@ -50,6 +52,8 @@ class XmlReferenceDumperTest extends TestCase
     scalar-array-empty=""
     scalar-array-defaults="elem1,elem2"
     scalar-required=""
+    scalar-deprecated=""
+    scalar-deprecated-with-message=""
     node-with-a-looong-name=""
     enum-with-default="this"
     enum=""

src/Symfony/Component/Config/Tests/Definition/Dumper/YamlReferenceDumperTest.php

@@ -98,6 +98,8 @@ acme_root:
         - elem1
         - elem2
     scalar_required:      ~ # Required
+    scalar_deprecated:    ~ # Deprecated (The child node "scalar_deprecated" at path "acme_root.scalar_deprecated" is deprecated.)
+    scalar_deprecated_with_message: ~ # Deprecated (Deprecation custom message for "scalar_deprecated_with_message" at "acme_root.scalar_deprecated_with_message")
     node_with_a_looong_name: ~
     enum_with_default:    this # One of "this"; "that"
     enum:                 ~ # One of "this"; "that"

src/Symfony/Component/Config/Tests/Fixtures/Configuration/ExampleConfiguration.php

@@ -35,6 +35,8 @@ class ExampleConfiguration implements ConfigurationInterface
                 ->scalarNode('scalar_array_empty')->defaultValue(array())->end()
                 ->scalarNode('scalar_array_defaults')->defaultValue(array('elem1', 'elem2'))->end()
                 ->scalarNode('scalar_required')->isRequired()->end()
+                ->scalarNode('scalar_deprecated')->setDeprecated()->end()
+                ->scalarNode('scalar_deprecated_with_message')->setDeprecated('Deprecation custom message for "%node%" at "%path%"')->end()
                 ->scalarNode('node_with_a_looong_name')->end()
                 ->enumNode('enum_with_default')->values(array('this', 'that'))->defaultValue('this')->end()
                 ->enumNode('enum')->values(array('this', 'that'))->end()