symfony · maidmaid · Dec 28, 2016 · Feb 22, 2017 · Feb 22, 2017
diff --git a/src/Symfony/Bundle/FrameworkBundle/Command/ConfigDumpReferenceCommand.php b/src/Symfony/Bundle/FrameworkBundle/Command/ConfigDumpReferenceCommand.php
@@ -39,6 +39,7 @@ protected function configure()
                new InputArgument('name', InputArgument::OPTIONAL, 'The Bundle name or the extension alias'),
                new InputArgument('path', InputArgument::OPTIONAL, 'The configuration option path'),
                new InputOption('format', null, InputOption::VALUE_REQUIRED, 'The output format (yaml or xml)', 'yaml'),
+                new InputOption('with-doc', null, InputOption::VALUE_NONE, 'Show documentation link'),
            ))
            ->setDescription('Dumps the default configuration for an extension')
            ->setHelp(<<<'EOF'
@@ -60,6 +61,10 @@ protected function configure()

  <info>php %command.full_name% framework profiler.matcher</info>

+The <info>--with-doc</info> option dumps nodes with documentation URL.
+
+  <info>php %command.full_name% FrameworkBundle --with-doc</info>
+
 EOF
            )
        ;
@@ -110,14 +115,15 @@ protected function execute(InputInterface $input, OutputInterface $output)
            $message .= sprintf(' at path "%s"', $path);
        }

+        $withDoc = $input->getOption('with-doc');
        switch ($format) {
            case 'yaml':
                $io->writeln(sprintf('# %s', $message));
-                $dumper = new YamlReferenceDumper();
+                $dumper = new YamlReferenceDumper($withDoc);
                break;
            case 'xml':
                $io->writeln(sprintf('<!-- %s -->', $message));
-                $dumper = new XmlReferenceDumper();
+                $dumper = new XmlReferenceDumper($withDoc);
                break;
            default:
                $io->writeln($message);

diff --git a/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Configuration.php b/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Configuration.php
diff --git a/src/Symfony/Component/Config/Definition/BaseNode.php b/src/Symfony/Component/Config/Definition/BaseNode.php
@@ -207,6 +207,26 @@ public function getPath()
        return $path;
    }

+    /**
+     * Sets an documentation URL.
+     *
+     * @param string $doc The documentation URL
+     */
+    public function setDoc($doc)
+    {
+        $this->setAttribute('doc', $doc);
+    }
+
+    /**
+     * Retrieves the documentation URL configuration for this node.
+     *
+     * @return string The documentation URL
+     */
+    public function getDoc()
+    {
+        return $this->getAttribute('doc');
+    }
+
    /**
     * Merges two values together.
     *

diff --git a/src/Symfony/Component/Config/Definition/Builder/NodeDefinition.php b/src/Symfony/Component/Config/Definition/Builder/NodeDefinition.php
@@ -13,6 +13,7 @@

 use Symfony\Component\Config\Definition\NodeInterface;
 use Symfony\Component\Config\Definition\Exception\InvalidDefinitionException;
+use Symfony\Component\HttpKernel\Kernel;

 /**
 * This class provides a fluent interface for defining a node.
@@ -340,4 +341,25 @@ protected function normalization()
     * @throws InvalidDefinitionException When the definition is invalid
     */
    abstract protected function createNode();
+
+    /**
+     * Sets doc configuration.
+     *
+     * @param string $doc
+     *
+     * @return NodeDefinition|$this
+     */
+    public function doc($doc)
+    {
+        if (false === filter_var($doc, FILTER_VALIDATE_URL)) {
+            throw new \InvalidArgumentException(sprintf('The "%s" is not a valid documentation URL.', $doc));
+        }
+
+        // Adds sf version
+        if (false !== strpos($doc, 'https://symfony.com/doc/')) {
+            $doc = sprintf($doc, Kernel::MAJOR_VERSION.'.'.Kernel::MINOR_VERSION);
+        }
+
+        return $this->attribute('doc', $doc);
+    }
 }
diff --git a/src/Symfony/Component/Config/Definition/Dumper/ReferenceDumper.php b/src/Symfony/Component/Config/Definition/Dumper/ReferenceDumper.php
@@ -0,0 +1,32 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Config\Definition\Dumper;
+
+use Symfony\Component\Config\Definition\ConfigurationInterface;
+
+/**
+ * Dumps a reference configuration for the given configuration/node instance.
+ *
+ * @author Dany Maillard <danymaillard93b@gmail.com>
+ */
+abstract class ReferenceDumper
+{
+    protected $reference;
+    protected $withDoc;
+
+    public function __construct($withDoc = false)
+    {
+        $this->withDoc = $withDoc;
+    }
+
+    abstract public function dump(ConfigurationInterface $configuration, $namespace = null);
+}
diff --git a/src/Symfony/Component/Config/Definition/Dumper/XmlReferenceDumper.php b/src/Symfony/Component/Config/Definition/Dumper/XmlReferenceDumper.php
@@ -22,10 +22,8 @@
 *
 * @author Wouter J <waldio.webdesign@gmail.com>
 */
-class XmlReferenceDumper
+class XmlReferenceDumper extends ReferenceDumper
 {
-    private $reference;
-
    public function dump(ConfigurationInterface $configuration, $namespace = null)
    {
        return $this->dumpNode($configuration->getConfigTreeBuilder()->buildTree(), $namespace);
@@ -149,6 +147,11 @@ private function writeNode(NodeInterface $node, $depth = 0, $root = false, $name
                        $comments[] = 'Example: '.$example;
                    }

+                    // doc
+                    if ($this->withDoc && $doc = $child->getDoc()) {
+                        $comments[] = 'Doc: '.$doc;
+                    }
+
                    if ($child->isRequired()) {
                        $comments[] = 'Required';
                    }

diff --git a/src/Symfony/Component/Config/Definition/Dumper/YamlReferenceDumper.php b/src/Symfony/Component/Config/Definition/Dumper/YamlReferenceDumper.php
@@ -24,11 +24,9 @@
 *
 * @author Kevin Bond <kevinbond@gmail.com>
 */
-class YamlReferenceDumper
+class YamlReferenceDumper extends ReferenceDumper
 {
-    private $reference;
-
-    public function dump(ConfigurationInterface $configuration)
+    public function dump(ConfigurationInterface $configuration, $namespace = null)
    {
        return $this->dumpNode($configuration->getConfigTreeBuilder()->buildTree());
    }
@@ -128,6 +126,11 @@ private function writeNode(NodeInterface $node, $depth = 0, $prototypedArray = f
            $comments[] = 'Example: '.$example;
        }

+        // doc
+        if ($this->withDoc && $doc = $node->getDoc()) {
+            $comments[] = 'Doc: '.$doc;
+        }
+
        $default = (string) $default != '' ? ' '.$default : '';
        $comments = count($comments) ? '# '.implode(', ', $comments) : '';


diff --git a/src/Symfony/Component/Config/Definition/NodeInterface.php b/src/Symfony/Component/Config/Definition/NodeInterface.php
@@ -58,6 +58,13 @@ public function hasDefaultValue();
     */
    public function getDefaultValue();

+    /**
+     * Returns the documentation URL of the node.
+     *
+     * @return string The documentation URL
+     */
+    public function getDoc();
+
    /**
     * Normalizes the supplied value.
     *