[Config] Add Node::getDeprecationMessage() with full message

Author: GromNaN

src/Symfony/Component/Config/Builder/ConfigBuilderGenerator.php

@@ -446,7 +446,7 @@ private function getComment(BaseNode $node): string
         }
 
         if ($node->isDeprecated()) {
-            $comment .= '@deprecated '.$node->getDeprecation($node->getName(), $node->getParent()->getName())['message']."\n";
+            $comment .= '@deprecated '.$node->getDeprecationMessage()."\n";
         }
 
         return $comment ? ' * '.str_replace("\n", "\n * ", rtrim($comment, "\n"))."\n" : '';

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

@@ -16,6 +16,7 @@
 use Symfony\Component\Config\Definition\Exception\InvalidConfigurationException;
 use Symfony\Component\Config\Definition\Exception\InvalidTypeException;
 use Symfony\Component\Config\Definition\Exception\UnsetKeyException;
+use Symfony\Component\Config\Exception\LogicException;
 
 /**
  * The base node class.
@@ -258,16 +259,39 @@ public function isDeprecated(): bool
     /**
      * @param string $node The configuration node name
      * @param string $path The path of the node
+     *
+     * @return array{package: string, version: string, message: string}
      */
     public function getDeprecation(string $node, string $path): array
     {
+        if (!$this->deprecation) {
+            throw new LogicException(\sprintf('The node "%s" is not deprecated.', $this->getName()));
+        }
+
         return [
             'package' => $this->deprecation['package'],
             'version' => $this->deprecation['version'],
             'message' => strtr($this->deprecation['message'], ['%node%' => $node, '%path%' => $path]),
         ];
     }
 
+    /**
+     * @internal
+     */
+    public function getDeprecationMessage(?NodeInterface $parent = null): string
+    {
+        if (!$this->deprecation) {
+            throw new LogicException(\sprintf('The node "%s" is not deprecated.', $this->getName()));
+        }
+
+        $message = strtr($this->deprecation['message'], ['%node%' => $this->getName(), '%path%' => ($parent ?? $this->parent ?? $this)->getPath()]);
+        if ($this->deprecation['package'] || $this->deprecation['version']) {
+            $message = \sprintf('Since %s %s: ', $this->deprecation['package'], $this->deprecation['version']).$message;
+        }
+
+        return $message;
+    }
+
     public function getName(): string
     {
         return $this->name;

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

@@ -144,8 +144,7 @@ private function writeNode(NodeInterface $node, int $depth = 0, bool $root = fal
                 }
 
                 if ($child instanceof BaseNode && $child->isDeprecated()) {
-                    $deprecation = $child->getDeprecation($child->getName(), $node->getPath());
-                    $comments[] = \sprintf('Deprecated (%s)', ($deprecation['package'] || $deprecation['version'] ? "Since {$deprecation['package']} {$deprecation['version']}: " : '').$deprecation['message']);
+                    $comments[] = \sprintf('Deprecated (%s)', $child->getDeprecationMessage($node));
                 }
 
                 if ($child instanceof EnumNode) {

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

@@ -120,8 +120,7 @@ private function writeNode(NodeInterface $node, ?NodeInterface $parentNode = nul
 
         // deprecated?
         if ($node instanceof BaseNode && $node->isDeprecated()) {
-            $deprecation = $node->getDeprecation($node->getName(), $parentNode ? $parentNode->getPath() : $node->getPath());
-            $comments[] = \sprintf('Deprecated (%s)', ($deprecation['package'] || $deprecation['version'] ? "Since {$deprecation['package']} {$deprecation['version']}: " : '').$deprecation['message']);
+            $comments[] = \sprintf('Deprecated (%s)', $node->getDeprecationMessage($parentNode));
         }
 
         // example

src/Symfony/Component/Config/Tests/Builder/Fixtures/AddToList/Symfony/Config/AddToList/TranslatorConfig.php

@@ -43,7 +43,7 @@ public function source(string $source_class, mixed $value): static
 
     /**
      * looks for translation in old fashion way
-     * @deprecated The child node "books" at path "translator" is deprecated.
+     * @deprecated Since symfony/config 6.0: The child node "books" at path "add_to_list.translator" is deprecated.
     */
     public function books(array $value = []): \Symfony\Config\AddToList\Translator\BooksConfig
     {

src/Symfony/Component/Config/Tests/Definition/ArrayNodeTest.php

@@ -239,6 +239,7 @@ public function testSetDeprecated()
         $this->assertSame('"foo" is deprecated', $deprecation['message']);
         $this->assertSame('vendor/package', $deprecation['package']);
         $this->assertSame('1.1', $deprecation['version']);
+        $this->assertSame('Since vendor/package 1.1: "foo" is deprecated', $childNode->getDeprecationMessage());
 
         $node = new ArrayNode('root');
         $node->addChild($childNode);

src/Symfony/Component/Config/Tests/Definition/Builder/BooleanNodeDefinitionTest.php

@@ -61,5 +61,6 @@ public function testSetDeprecated()
         $this->assertSame('The "foo" node is deprecated.', $deprecation['message']);
         $this->assertSame('vendor/package', $deprecation['package']);
         $this->assertSame('1.1', $deprecation['version']);
+        $this->assertSame('Since vendor/package 1.1: The "foo" node is deprecated.', $node->getDeprecationMessage());
     }
 }

src/Symfony/Component/Config/Tests/Definition/Builder/EnumNodeDefinitionTest.php

@@ -81,10 +81,11 @@ public function testSetDeprecated()
         $node = $def->getNode();
 
         $this->assertTrue($node->isDeprecated());
-        $deprecation = $def->getNode()->getDeprecation($node->getName(), $node->getPath());
+        $deprecation = $node->getDeprecation($node->getName(), $node->getPath());
         $this->assertSame('The "foo" node is deprecated.', $deprecation['message']);
         $this->assertSame('vendor/package', $deprecation['package']);
         $this->assertSame('1.1', $deprecation['version']);
+        $this->assertSame('Since vendor/package 1.1: The "foo" node is deprecated.', $node->getDeprecationMessage());
     }
 
     public function testSameStringCoercedValuesAreDifferent()

src/Symfony/Component/Config/Tests/Definition/ScalarNodeTest.php

@@ -17,6 +17,7 @@
 use Symfony\Component\Config\Definition\Exception\InvalidConfigurationException;
 use Symfony\Component\Config\Definition\Exception\InvalidTypeException;
 use Symfony\Component\Config\Definition\ScalarNode;
+use Symfony\Component\Config\Exception\LogicException;
 
 class ScalarNodeTest extends TestCase
 {
@@ -52,6 +53,7 @@ public function testSetDeprecated()
         $this->assertSame('"foo" is deprecated', $deprecation['message']);
         $this->assertSame('vendor/package', $deprecation['package']);
         $this->assertSame('1.1', $deprecation['version']);
+        $this->assertSame('Since vendor/package 1.1: "foo" is deprecated', $childNode->getDeprecationMessage());
 
         $node = new ArrayNode('root');
         $node->addChild($childNode);
@@ -82,6 +84,16 @@ public function testSetDeprecated()
         $this->assertSame(1, $deprecationTriggered, '->finalize() should trigger if the deprecated node is set');
     }
 
+    public function testNotDeprecatedException()
+    {
+        $childNode = new ScalarNode('foo');
+
+        $this->assertFalse($childNode->isDeprecated());
+        $this->expectException(LogicException::class);
+        $this->expectExceptionMessage('The node "foo" is not deprecated.');
+        $childNode->getDeprecation('node', 'path');
+    }
+
     #[DataProvider('getInvalidValues')]
     public function testNormalizeThrowsExceptionOnInvalidValues($value)
     {