diff --git a/src/Symfony/Component/Config/CHANGELOG.md b/src/Symfony/Component/Config/CHANGELOG.md index 4ef4e625ba566..ffa347dbf4976 100644 --- a/src/Symfony/Component/Config/CHANGELOG.md +++ b/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 ----- diff --git a/src/Symfony/Component/Config/Definition/ArrayNode.php b/src/Symfony/Component/Config/Definition/ArrayNode.php index 457e7a8c92e34..2ffa2a2137fa8 100644 --- a/src/Symfony/Component/Config/Definition/ArrayNode.php +++ b/src/Symfony/Component/Config/Definition/ArrayNode.php @@ -234,6 +234,10 @@ protected function finalizeValue($value) } 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()); diff --git a/src/Symfony/Component/Config/Definition/BaseNode.php b/src/Symfony/Component/Config/Definition/BaseNode.php index dbf36335b69e3..6e6ac1fdb47cf 100644 --- a/src/Symfony/Component/Config/Definition/BaseNode.php +++ b/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 @@ public function setRequired($boolean) $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 @@ public function isRequired() 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. * diff --git a/src/Symfony/Component/Config/Definition/Builder/NodeDefinition.php b/src/Symfony/Component/Config/Definition/Builder/NodeDefinition.php index 1b712a3150bc3..eb212caa44e00 100644 --- a/src/Symfony/Component/Config/Definition/Builder/NodeDefinition.php +++ b/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 @@ public function isRequired() 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. * diff --git a/src/Symfony/Component/Config/Definition/Builder/VariableNodeDefinition.php b/src/Symfony/Component/Config/Definition/Builder/VariableNodeDefinition.php index a46b7ea61ded0..26565e1771d84 100644 --- a/src/Symfony/Component/Config/Definition/Builder/VariableNodeDefinition.php +++ b/src/Symfony/Component/Config/Definition/Builder/VariableNodeDefinition.php @@ -54,6 +54,7 @@ protected function createNode() $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); diff --git a/src/Symfony/Component/Config/Definition/Dumper/XmlReferenceDumper.php b/src/Symfony/Component/Config/Definition/Dumper/XmlReferenceDumper.php index ec5460f2f53c7..44cc9ea9ab79b 100644 --- a/src/Symfony/Component/Config/Definition/Dumper/XmlReferenceDumper.php +++ b/src/Symfony/Component/Config/Definition/Dumper/XmlReferenceDumper.php @@ -153,6 +153,10 @@ private function writeNode(NodeInterface $node, $depth = 0, $root = false, $name $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())); } diff --git a/src/Symfony/Component/Config/Definition/Dumper/YamlReferenceDumper.php b/src/Symfony/Component/Config/Definition/Dumper/YamlReferenceDumper.php index 16076354db515..a470e5f9fba67 100644 --- a/src/Symfony/Component/Config/Definition/Dumper/YamlReferenceDumper.php +++ b/src/Symfony/Component/Config/Definition/Dumper/YamlReferenceDumper.php @@ -123,6 +123,11 @@ private function writeNode(NodeInterface $node, $depth = 0, $prototypedArray = f $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; diff --git a/src/Symfony/Component/Config/Tests/Definition/Dumper/XmlReferenceDumperTest.php b/src/Symfony/Component/Config/Tests/Definition/Dumper/XmlReferenceDumperTest.php index fd5f9c8cde841..3123c9740a24c 100644 --- a/src/Symfony/Component/Config/Tests/Definition/Dumper/XmlReferenceDumperTest.php +++ b/src/Symfony/Component/Config/Tests/Definition/Dumper/XmlReferenceDumperTest.php @@ -38,6 +38,8 @@ private function getConfigurationAsString() return str_replace("\n", PHP_EOL, <<<'EOL' + + 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()