[Config] Add NodeDefinition::docUrl()

alexandre-daubois · alexandre-daubois · commit a27e4aa788e4 · 2025-03-28T14:46:26.000+01:00
diff --git a/src/Symfony/Bundle/DebugBundle/DependencyInjection/Configuration.php b/src/Symfony/Bundle/DebugBundle/DependencyInjection/Configuration.php
@@ -26,7 +26,9 @@ public function getConfigTreeBuilder(): TreeBuilder
         $treeBuilder = new TreeBuilder('debug');
 
         $rootNode = $treeBuilder->getRootNode();
-        $rootNode->children()
+        $rootNode
+            ->docUrl('https://symfony.com/doc/{version:major}.{version:minor}/reference/configuration/debug.html', 'symfony/debug-bundle')
+            ->children()
                 ->integerNode('max_items')
                     ->info('Max number of displayed items past the first level, -1 means no limit.')
                     ->min(-1)
diff --git a/src/Symfony/Bundle/DebugBundle/composer.json b/src/Symfony/Bundle/DebugBundle/composer.json
@@ -18,13 +18,14 @@
     "require": {
         "php": ">=8.2",
         "ext-xml": "*",
+        "composer-runtime-api": ">=2.1",
         "symfony/dependency-injection": "^6.4|^7.0",
         "symfony/http-kernel": "^6.4|^7.0",
         "symfony/twig-bridge": "^6.4|^7.0",
         "symfony/var-dumper": "^6.4|^7.0"
     },
     "require-dev": {
-        "symfony/config": "^6.4|^7.0",
+        "symfony/config": "^7.3",
         "symfony/web-profiler-bundle": "^6.4|^7.0"
     },
     "conflict": {
diff --git a/src/Symfony/Bundle/FrameworkBundle/Command/ConfigDebugCommand.php b/src/Symfony/Bundle/FrameworkBundle/Command/ConfigDebugCommand.php
@@ -104,6 +104,8 @@ protected function execute(InputInterface $input, OutputInterface $output): int
                 $io->title(
                     \sprintf('Current configuration for %s', $name === $extensionAlias ? \sprintf('extension with alias "%s"', $extensionAlias) : \sprintf('"%s"', $name))
                 );
+
+                $io->comment(\sprintf('Documentation at %s', $this->getDocUrl($extension, $container)));
             }
 
             $io->writeln($this->convertToFormat([$extensionAlias => $config], $format));
@@ -269,4 +271,15 @@ private function getAvailableFormatOptions(): array
     {
         return ['txt', 'yaml', 'json'];
     }
+
+    private function getDocUrl(ExtensionInterface $extension, ContainerBuilder $container): ?string
+    {
+        $configuration = $extension instanceof ConfigurationInterface ? $extension : $extension->getConfiguration($container->getExtensionConfig($extension->getAlias()), $container);
+
+        return $configuration
+            ->getConfigTreeBuilder()
+            ->getRootNode()
+            ->getNode(true)
+            ->getAttribute('docUrl');
+    }
 }
diff --git a/src/Symfony/Bundle/FrameworkBundle/Command/ConfigDumpReferenceCommand.php b/src/Symfony/Bundle/FrameworkBundle/Command/ConfigDumpReferenceCommand.php
@@ -23,6 +23,7 @@
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
 use Symfony\Component\Console\Style\SymfonyStyle;
+use Symfony\Component\DependencyInjection\Extension\ConfigurationExtensionInterface;
 use Symfony\Component\Yaml\Yaml;
 
 /**
@@ -123,6 +124,10 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             $message .= \sprintf(' at path "%s"', $path);
         }
 
+        if ($docUrl = $this->getExtensionDocUrl($extension)) {
+            $message .= \sprintf(' (see %s)', $docUrl);
+        }
+
         switch ($format) {
             case 'yaml':
                 $io->writeln(\sprintf('# %s', $message));
@@ -182,4 +187,18 @@ private function getAvailableFormatOptions(): array
     {
         return ['yaml', 'xml'];
     }
+
+    private function getExtensionDocUrl(ConfigurationInterface|ConfigurationExtensionInterface $extension): ?string
+    {
+        $kernel = $this->getApplication()->getKernel();
+        $container = $this->getContainerBuilder($kernel);
+
+        $configuration = $extension instanceof ConfigurationInterface ? $extension : $extension->getConfiguration($container->getExtensionConfig($extension->getAlias()), $container);
+
+        return $configuration
+            ->getConfigTreeBuilder()
+            ->getRootNode()
+            ->getNode(true)
+            ->getAttribute('docUrl');
+    }
 }
diff --git a/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Configuration.php b/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Configuration.php
@@ -75,6 +75,7 @@ public function getConfigTreeBuilder(): TreeBuilder
         $rootNode = $treeBuilder->getRootNode();
 
         $rootNode
+            ->docUrl('https://symfony.com/doc/{version:major}.{version:minor}/reference/configuration/framework.html', 'symfony/framework-bundle')
             ->beforeNormalization()
                 ->ifTrue(fn ($v) => !isset($v['assets']) && isset($v['templating']) && class_exists(Package::class))
                 ->then(function ($v) {
diff --git a/src/Symfony/Bundle/SecurityBundle/DependencyInjection/MainConfiguration.php b/src/Symfony/Bundle/SecurityBundle/DependencyInjection/MainConfiguration.php
@@ -55,6 +55,7 @@ public function getConfigTreeBuilder(): TreeBuilder
         $rootNode = $tb->getRootNode();
 
         $rootNode
+            ->docUrl('https://symfony.com/doc/{version:major}.{version:minor}/reference/configuration/security.html', 'symfony/security-bundle')
             ->beforeNormalization()
                 ->always()
                 ->then(function ($v) {
diff --git a/src/Symfony/Bundle/SecurityBundle/composer.json b/src/Symfony/Bundle/SecurityBundle/composer.json
@@ -20,7 +20,7 @@
         "composer-runtime-api": ">=2.1",
         "ext-xml": "*",
         "symfony/clock": "^6.4|^7.0",
-        "symfony/config": "^6.4|^7.0",
+        "symfony/config": "^7.3",
         "symfony/dependency-injection": "^6.4.11|^7.1.4",
         "symfony/event-dispatcher": "^6.4|^7.0",
         "symfony/http-kernel": "^6.4|^7.0",
diff --git a/src/Symfony/Bundle/TwigBundle/DependencyInjection/Configuration.php b/src/Symfony/Bundle/TwigBundle/DependencyInjection/Configuration.php
@@ -32,7 +32,9 @@ public function getConfigTreeBuilder(): TreeBuilder
         $treeBuilder = new TreeBuilder('twig');
         $rootNode = $treeBuilder->getRootNode();
 
-        $rootNode->beforeNormalization()
+        $rootNode
+            ->docUrl('https://symfony.com/doc/{version:major}.{version:minor}/reference/configuration/twig.html', 'symfony/twig-bundle')
+            ->beforeNormalization()
             ->ifTrue(fn ($v) => \is_array($v) && \array_key_exists('exception_controller', $v))
             ->then(function ($v) {
                 if (isset($v['exception_controller'])) {
diff --git a/src/Symfony/Bundle/TwigBundle/composer.json b/src/Symfony/Bundle/TwigBundle/composer.json
@@ -18,7 +18,7 @@
     "require": {
         "php": ">=8.2",
         "composer-runtime-api": ">=2.1",
-        "symfony/config": "^6.4|^7.0",
+        "symfony/config": "^7.3",
         "symfony/dependency-injection": "^6.4|^7.0",
         "symfony/twig-bridge": "^6.4|^7.0",
         "symfony/http-foundation": "^6.4|^7.0",
diff --git a/src/Symfony/Bundle/WebProfilerBundle/DependencyInjection/Configuration.php b/src/Symfony/Bundle/WebProfilerBundle/DependencyInjection/Configuration.php
@@ -31,7 +31,9 @@ public function getConfigTreeBuilder(): TreeBuilder
     {
         $treeBuilder = new TreeBuilder('web_profiler');
 
-        $treeBuilder->getRootNode()
+        $treeBuilder
+            ->getRootNode()
+            ->docUrl('https://symfony.com/doc/{version:major}.{version:minor}/reference/configuration/web_profiler.html', 'symfony/web-profiler-bundle')
             ->children()
                 ->arrayNode('toolbar')
                     ->info('Profiler toolbar configuration')
diff --git a/src/Symfony/Bundle/WebProfilerBundle/composer.json b/src/Symfony/Bundle/WebProfilerBundle/composer.json
@@ -17,7 +17,8 @@
     ],
     "require": {
         "php": ">=8.2",
-        "symfony/config": "^6.4|^7.0",
+        "composer-runtime-api": ">=2.1",
+        "symfony/config": "^7.3",
         "symfony/framework-bundle": "^6.4|^7.0",
         "symfony/http-kernel": "^6.4|^7.0",
         "symfony/routing": "^6.4|^7.0",
diff --git a/src/Symfony/Component/Config/CHANGELOG.md b/src/Symfony/Component/Config/CHANGELOG.md
@@ -7,6 +7,7 @@ CHANGELOG
  * Add `ExprBuilder::ifFalse()`
  * Add support for info on `ArrayNodeDefinition::canBeEnabled()` and `ArrayNodeDefinition::canBeDisabled()`
  * Allow using an enum FQCN with `EnumNode`
+ * Add `NodeDefinition::docUrl()`
 
 7.2
 ---
diff --git a/src/Symfony/Component/Config/Definition/Builder/NodeDefinition.php b/src/Symfony/Component/Config/Definition/Builder/NodeDefinition.php
@@ -11,6 +11,7 @@
 
 namespace Symfony\Component\Config\Definition\Builder;
 
+use Composer\InstalledVersions;
 use Symfony\Component\Config\Definition\BaseNode;
 use Symfony\Component\Config\Definition\Exception\InvalidDefinitionException;
 use Symfony\Component\Config\Definition\NodeInterface;
@@ -76,6 +77,26 @@ public function example(string|array $example): static
         return $this->attribute('example', $example);
     }
 
+    /**
+     * Sets the documentation URI, as usually put in the "@see" tag of a doc block. This
+     * can either be a URL or a file path. You can use the placeholders {package},
+     * {version:major} and {version:minor} in the URI.
+     *
+     * @return $this
+     */
+    public function docUrl(string $uri, ?string $package = null): static
+    {
+        if ($package) {
+            preg_match('/^(\d+)\.(\d+)\.(\d+)/', InstalledVersions::getVersion($package) ?? '', $m);
+        }
+
+        return $this->attribute('docUrl', strtr($uri, [
+            '{package}' => $package ?? '',
+            '{version:major}' => $m[1] ?? '',
+            '{version:minor}' => $m[2] ?? '',
+        ]));
+    }
+
     /**
      * Sets an attribute on the node.
      *
diff --git a/src/Symfony/Component/Config/Tests/Definition/Builder/NodeDefinitionTest.php b/src/Symfony/Component/Config/Tests/Definition/Builder/NodeDefinitionTest.php
@@ -35,4 +35,35 @@ public function testSetPathSeparatorChangesChildren()
 
         $parentNode->setPathSeparator('/');
     }
+
+    public function testDocUrl()
+    {
+        $node = new ArrayNodeDefinition('node');
+        $node->docUrl('https://example.com/doc/{package}/{version:major}.{version:minor}', 'phpunit/phpunit');
+
+        $r = new \ReflectionObject($node);
+        $p = $r->getProperty('attributes');
+
+        $this->assertMatchesRegularExpression('~^https://example.com/doc/phpunit/phpunit/\d+\.\d+$~', $p->getValue($node)['docUrl']);
+    }
+
+    public function testDocUrlWithoutPackage()
+    {
+        $node = new ArrayNodeDefinition('node');
+        $node->docUrl('https://example.com/doc/empty{version:major}.empty{version:minor}');
+
+        $r = new \ReflectionObject($node);
+        $p = $r->getProperty('attributes');
+
+        $this->assertSame('https://example.com/doc/empty.empty', $p->getValue($node)['docUrl']);
+    }
+
+    public function testUnknownPackageThrowsException()
+    {
+        $this->expectException(\OutOfBoundsException::class);
+        $this->expectExceptionMessage('Package "phpunit/invalid" is not installed');
+
+        $node = new ArrayNodeDefinition('node');
+        $node->docUrl('https://example.com/doc/{package}/{version:major}.{version:minor}', 'phpunit/invalid');
+    }
 }

Original file line number	Diff line number	Diff line change
`@@ -104,6 +104,8 @@ protected function execute(InputInterface $input, OutputInterface $output): int`
`104`	`104`	`$io->title(`
`105`	`105`	`\sprintf('Current configuration for %s', $name === $extensionAlias ? \sprintf('extension with alias "%s"', $extensionAlias) : \sprintf('"%s"', $name))`
`106`	`106`	`);`
	`107`	`+`
	`108`	`+ $io->comment(\sprintf('Documentation at %s', $this->getDocUrl($extension, $container)));`
`107`	`109`	`}`
`108`	`110`
`109`	`111`	`$io->writeln($this->convertToFormat([$extensionAlias => $config], $format));`
`@@ -269,4 +271,15 @@ private function getAvailableFormatOptions(): array`
`269`	`271`	`{`
`270`	`272`	`return ['txt', 'yaml', 'json'];`
`271`	`273`	`}`
	`274`	`+`
	`275`	`+ private function getDocUrl(ExtensionInterface $extension, ContainerBuilder $container): ?string`
	`276`	`+ {`
	`277`	`+ $configuration = $extension instanceof ConfigurationInterface ? $extension : $extension->getConfiguration($container->getExtensionConfig($extension->getAlias()), $container);`
	`278`	`+`
	`279`	`+ return $configuration`
	`280`	`+ ->getConfigTreeBuilder()`
	`281`	`+ ->getRootNode()`
	`282`	`+ ->getNode(true)`
	`283`	`+ ->getAttribute('docUrl');`
	`284`	`+ }`
`272`	`285`	`}`