CommentToPhpdocFixer - allow to ignore tags

PHP-CS-Fixer · Apr 22, 2019 · 0a46405 · 0a46405
1 parent c12abbc
commit 0a46405
Show file tree

Hide file tree

Showing 3 changed files with 116 additions and 3 deletions.
diff --git a/README.rst b/README.rst
@@ -404,6 +404,10 @@ Choose from the list of available rules:
 
   *Risky rule: risky as new docblocks might mean more, e.g. a Doctrine entity might have a new column in database.*
 
+  Configuration options:
+
+  - ``ignored_tags`` (``array``): list of ignored tags; defaults to ``[]``
+
 * **compact_nullable_typehint** [@PhpCsFixer]
 
   Remove extra spaces in a nullable typehint.

diff --git a/src/Fixer/Comment/CommentToPhpdocFixer.php b/src/Fixer/Comment/CommentToPhpdocFixer.php
@@ -13,7 +13,10 @@
 namespace PhpCsFixer\Fixer\Comment;
 
 use PhpCsFixer\AbstractFixer;
+use PhpCsFixer\Fixer\ConfigurationDefinitionFixerInterface;
 use PhpCsFixer\Fixer\WhitespacesAwareFixerInterface;
+use PhpCsFixer\FixerConfiguration\FixerConfigurationResolver;
+use PhpCsFixer\FixerConfiguration\FixerOptionBuilder;
 use PhpCsFixer\FixerDefinition\CodeSample;
 use PhpCsFixer\FixerDefinition\FixerDefinition;
 use PhpCsFixer\Preg;
@@ -25,8 +28,13 @@
 /**
  * @author Kuba Werłos <werlos@gmail.com>
  */
-final class CommentToPhpdocFixer extends AbstractFixer implements WhitespacesAwareFixerInterface
+final class CommentToPhpdocFixer extends AbstractFixer implements ConfigurationDefinitionFixerInterface, WhitespacesAwareFixerInterface
 {
+    /**
+     * @var string[]
+     */
+    private $ignoredTags = [];
+
     /**
      * {@inheritdoc}
      */
@@ -65,6 +73,34 @@ public function getDefinition()
         );
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function configure(array $configuration = null)
+    {
+        parent::configure($configuration);
+
+        $this->ignoredTags = array_map(
+            static function ($tag) {
+                return strtolower($tag);
+            },
+            $this->configuration['ignored_tags']
+        );
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    protected function createConfigurationDefinition()
+    {
+        return new FixerConfigurationResolver([
+            (new FixerOptionBuilder('ignored_tags', sprintf('List of ignored tags')))
+                ->setAllowedTypes(['array'])
+                ->setDefault([])
+                ->getOption(),
+        ]);
+    }
+
     /**
      * {@inheritdoc}
      */
@@ -108,7 +144,14 @@ private function isCommentCandidate(Tokens $tokens, array $indices)
         return array_reduce(
             $indices,
             function ($carry, $index) use ($tokens) {
-                return $carry || 1 === Preg::match('~(#|//|/\*+|\R(\s*\*)?)\s*\@[a-zA-Z0-9_\\\\-]+(?=\s|\(|$)~', $tokens[$index]->getContent());
+                if ($carry) {
+                    return true;
+                }
+                if (1 !== Preg::match('~(?:#|//|/\*+|\R(?:\s*\*)?)\s*\@([a-zA-Z0-9_\\\\-]+)(?=\s|\(|$)~', $tokens[$index]->getContent(), $matches)) {
+                    return false;
+                }
+
+                return !\in_array(strtolower($matches[1]), $this->ignoredTags, true);
             },
             false
         );

diff --git a/tests/Fixer/Comment/CommentToPhpdocFixerTest.php b/tests/Fixer/Comment/CommentToPhpdocFixerTest.php
@@ -26,11 +26,13 @@ final class CommentToPhpdocFixerTest extends AbstractFixerTestCase
     /**
      * @param string      $expected
      * @param null|string $input
+     * @param array       $config
      *
      * @dataProvider provideTestCases
      */
-    public function testFix($expected, $input = null)
+    public function testFix($expected, $input = null, array $config = [])
     {
+        $this->fixer->configure($config);
         $this->doTest($expected, $input);
     }
 
@@ -246,6 +248,70 @@ public function provideTestCases()
 EOT
                 ,
             ],
+            [
+                <<<'EOT'
+<?php /* header comment */ $foo = true;
+
+// @todo do something later
+$foo = 1;
+EOT
+                ,
+                null,
+                ['ignored_tags' => ['todo']],
+            ],
+            [
+                <<<'EOT'
+<?php /* header comment */ $foo = true;
+
+// @TODO do something later
+$foo = 1;
+EOT
+                ,
+                null,
+                ['ignored_tags' => ['todo']],
+            ],
+            [
+                <<<'EOT'
+<?php /* header comment */ $foo = true;
+
+/**
+ * @todo do something later
+ * @var int $foo
+ */
+$foo = 1;
+EOT
+                ,
+                <<<'EOT'
+<?php /* header comment */ $foo = true;
+
+// @todo do something later
+// @var int $foo
+$foo = 1;
+EOT
+                ,
+                ['ignored_tags' => ['todo']],
+            ],
+            [
+                <<<'EOT'
+<?php /* header comment */ $foo = true;
+
+/**
+ * @var int $foo
+ * @todo do something later
+ */
+$foo = 1;
+EOT
+                ,
+                <<<'EOT'
+<?php /* header comment */ $foo = true;
+
+// @var int $foo
+// @todo do something later
+$foo = 1;
+EOT
+                ,
+                ['ignored_tags' => ['todo']],
+            ],
         ];
     }
 }