Make phpdoc_align configurable

ntzm · ntzm · commit 085640ad9bc8 · 2017-05-04T18:55:51.000+01:00
diff --git a/README.rst b/README.rst
@@ -845,8 +845,12 @@ Choose from the list of available rules:
 
 * **phpdoc_align** [@Symfony]
 
-  All items of the @param, @throws, @return, @var, and @type phpdoc tags
-  must be aligned vertically.
+  All items of the given phpdoc tags must be aligned vertically.
+
+  Configuration options:
+
+  - ``tags`` (``array``): the tags that should be aligned; defaults to ``['param',
+    'return', 'throws', 'type', 'var']``
 
 * **phpdoc_annotation_without_dot** [@Symfony]
 
diff --git a/src/Fixer/Phpdoc/PhpdocAlignFixer.php b/src/Fixer/Phpdoc/PhpdocAlignFixer.php
@@ -13,7 +13,11 @@
 namespace PhpCsFixer\Fixer\Phpdoc;
 
 use PhpCsFixer\AbstractFixer;
+use PhpCsFixer\Fixer\ConfigurationDefinitionFixerInterface;
 use PhpCsFixer\Fixer\WhitespacesAwareFixerInterface;
+use PhpCsFixer\FixerConfiguration\FixerConfigurationResolver;
+use PhpCsFixer\FixerConfiguration\FixerOptionBuilder;
+use PhpCsFixer\FixerConfiguration\FixerOptionValidatorGenerator;
 use PhpCsFixer\FixerDefinition\CodeSample;
 use PhpCsFixer\FixerDefinition\FixerDefinition;
 use PhpCsFixer\Tokenizer\Tokens;
@@ -26,24 +30,44 @@
  * @author Graham Campbell <graham@alt-three.com>
  * @author Dariusz Rumiński <dariusz.ruminski@gmail.com>
  */
-final class PhpdocAlignFixer extends AbstractFixer implements WhitespacesAwareFixerInterface
+final class PhpdocAlignFixer extends AbstractFixer implements ConfigurationDefinitionFixerInterface, WhitespacesAwareFixerInterface
 {
     private $regex;
     private $regexCommentLine;
 
-    public function __construct()
+    private static $alignableTags = [
+        'param',
+        'property',
+        'return',
+        'throws',
+        'type',
+        'var',
+    ];
+
+    private static $tagsWithName = [
+        'param',
+        'property',
+    ];
+
+    /**
+     * {@inheritdoc}
+     */
+    public function configure(array $configuration = null)
     {
-        parent::__construct();
+        parent::configure($configuration);
+
+        $tagsWithNameToAlign = array_intersect($this->configuration['tags'], self::$tagsWithName);
+        $tagsWithoutNameToAlign = array_diff($this->configuration['tags'], $tagsWithNameToAlign);
 
         $indent = '(?P<indent>(?: {2}|\t)*)';
         // e.g. @param <hint> <$var>
-        $paramTag = '(?P<tag>param)\s+(?P<hint>[^$]+?)\s+(?P<var>(?:&|\.{3})?\$[^\s]+)';
+        $tagsWithName = '(?P<tag>'.implode('|', $tagsWithNameToAlign).')\s+(?P<hint>[^$]+?)\s+(?P<var>(?:&|\.{3})?\$[^\s]+)';
         // e.g. @return <hint>
-        $otherTags = '(?P<tag2>return|throws|var|type)\s+(?P<hint2>[^\s]+?)';
+        $tagsWithoutName = '(?P<tag2>'.implode('|', $tagsWithoutNameToAlign).')\s+(?P<hint2>[^\s]+?)';
         // optional <desc>
         $desc = '(?:\s+(?P<desc>\V*))';
 
-        $this->regex = '/^'.$indent.' \* @(?:'.$paramTag.'|'.$otherTags.')'.$desc.'\s*$/u';
+        $this->regex = '/^'.$indent.' \* @(?:'.$tagsWithName.'|'.$tagsWithoutName.')'.$desc.'\s*$/u';
         $this->regexCommentLine = '/^'.$indent.' \*(?! @)(?:\s+(?P<desc>\V+))(?<!\*\/)$/u';
     }
 
@@ -53,7 +77,7 @@ public function __construct()
     public function getDefinition()
     {
         return new FixerDefinition(
-            'All items of the @param, @throws, @return, @var, and @type phpdoc tags must be aligned vertically.',
+            'All items of the given phpdoc tags must be aligned vertically.',
             [new CodeSample('<?php
 /**
  * @param  EngineInterface $templating
@@ -101,6 +125,32 @@ protected function applyFix(\SplFileInfo $file, Tokens $tokens)
         }
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    protected function createConfigurationDefinition()
+    {
+        $generator = new FixerOptionValidatorGenerator();
+
+        $tags = new FixerOptionBuilder('tags', 'The tags that should be aligned.');
+        $tags
+            ->setAllowedTypes(['array'])
+            ->setAllowedValues([
+                $generator->allowedValueIsSubsetOf(self::$alignableTags),
+            ])
+            // By default, all tags apart from @property will be aligned for backwards compatibility
+            ->setDefault([
+                'param',
+                'return',
+                'throws',
+                'type',
+                'var',
+            ])
+        ;
+
+        return new FixerConfigurationResolver([$tags->getOption()]);
+    }
+
     /**
      * Fix a given docblock.
      *
@@ -168,7 +218,10 @@ private function fixDocBlock($content)
                     $line =
                         $item['indent']
                         .' *  '
-                        .str_repeat(' ', $tagMax + $hintMax + $varMax + ('param' === $currTag ? 3 : 2))
+                        .str_repeat(
+                            ' ',
+                            $tagMax + $hintMax + $varMax + (in_array($currTag, self::$tagsWithName, true) ? 3 : 2)
+                        )
                         .$item['desc']
                         .$lineEnding;
 
diff --git a/tests/Fixer/Phpdoc/PhpdocAlignFixerTest.php b/tests/Fixer/Phpdoc/PhpdocAlignFixerTest.php
