feature #59762 [Config] Add NodeDefinition::docUrl() (alexandre-daubois)

This PR was merged into the 7.3 branch.

Discussion
----------

[Config] Add `NodeDefinition::docUrl()`

| Q             | A
| ------------- | ---
| Branch?       | 7.3
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Issues        | -
| License       | MIT

Adding such information would allow extensions and bundles to provide even more info with a documentation "one click away".

The primary goal is to use this feature in conjunction with symfony/symfony#58771, allowing to dump a ``@see` https://symfony.com/doc/...` right next to the configuration array shape.

Commits
-------

3c7fce2e326 [Config] Add `NodeDefinition::docUrl()`

Author: fabpot

Command/ConfigDebugCommand.php

@@ -104,6 +104,10 @@ 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))
                 );
+
+                if ($docUrl = $this->getDocUrl($extension, $container)) {
+                    $io->comment(\sprintf('Documentation at %s', $docUrl));
+                }
             }
 
             $io->writeln($this->convertToFormat([$extensionAlias => $config], $format));
@@ -269,4 +273,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');
+    }
 }

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');
+    }
 }

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) {