Add PhpdocSelfAccessorFixer (#42)

Author: kubawerlos

CHANGELOG.md

@@ -1,5 +1,8 @@
 # CHANGELOG for PHP CS Fixer: custom fixers
 
+## [Unreleased]
+- Add PhpdocSelfAccessorFixer
+
 ## v1.7.0 - *2018-08-06*
 - Add NoReferenceInFunctionDefinitionFixer
 - Add NoImportFromGlobalNamespaceFixer

README.md

@@ -165,6 +165,18 @@ In your PHP CS Fixer configuration register fixers and use them:
  function a($foo, $bar) {}
 ```
 
+- **PhpdocSelfAccessorFixer** - in PHPDoc inside class or interface element `self` should be preferred over the class name itself.
+```diff
+ <?php
+ class Foo {
+     /**
+-     * @var Foo
++     * @var self
+      */
+      private $instance;
+ }
+```
+
 - **PhpdocSingleLineVarFixer** - `@var` annotation must be in single line when is the only content.
 ```diff
  <?php

src/Fixer/PhpdocSelfAccessorFixer.php

@@ -0,0 +1,103 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace PhpCsFixerCustomFixers\Fixer;
+
+use PhpCsFixer\DocBlock\DocBlock;
+use PhpCsFixer\FixerDefinition\CodeSample;
+use PhpCsFixer\FixerDefinition\FixerDefinition;
+use PhpCsFixer\Tokenizer\Analyzer\NamespacesAnalyzer;
+use PhpCsFixer\Tokenizer\Token;
+use PhpCsFixer\Tokenizer\Tokens;
+use PhpCsFixer\Tokenizer\TokensAnalyzer;
+
+final class PhpdocSelfAccessorFixer extends AbstractFixer
+{
+    public function getDefinition(): FixerDefinition
+    {
+        return new FixerDefinition(
+            'In PHPDoc inside class or interface element `self` should be preferred over the class name itself.',
+            [new CodeSample('<?php
+class Foo {
+    /**
+     * @var Foo
+     */
+     private $instance;
+}
+')]
+        );
+    }
+
+    public function isCandidate(Tokens $tokens): bool
+    {
+        return $tokens->isAnyTokenKindsFound([T_CLASS, T_INTERFACE]) && $tokens->isTokenKindFound(T_DOC_COMMENT);
+    }
+
+    public function isRisky(): bool
+    {
+        return false;
+    }
+
+    public function fix(\SplFileInfo $file, Tokens $tokens): void
+    {
+        $tokensAnalyzer = new TokensAnalyzer($tokens);
+
+        foreach ((new NamespacesAnalyzer())->getDeclarations($tokens) as $namespace) {
+            for ($index = $namespace->getScopeStartIndex(); $index < $namespace->getScopeEndIndex(); $index++) {
+                if (!$tokens[$index]->isGivenKind([T_CLASS, T_INTERFACE]) || $tokensAnalyzer->isAnonymousClass($index)) {
+                    continue;
+                }
+
+                $nameIndex  = $tokens->getNextTokenOfKind($index, [[T_STRING]]);
+                $startIndex = $tokens->getNextTokenOfKind($nameIndex, ['{']);
+                $endIndex   = $tokens->findBlockEnd(Tokens::BLOCK_TYPE_CURLY_BRACE, $startIndex);
+
+                $name = $tokens[$nameIndex]->getContent();
+
+                $this->replaceNameOccurrences($tokens, $namespace->getFullName(), $name, $startIndex, $endIndex);
+
+                $index = $endIndex;
+            }
+        }
+    }
+
+    public function getPriority(): int
+    {
+        return 0;
+    }
+
+    private function replaceNameOccurrences(Tokens $tokens, string $namespace, string $name, int $startIndex, int $endIndex): void
+    {
+        for ($index = $startIndex; $index < $endIndex; $index++) {
+            if (!$tokens[$index]->isGivenKind(T_DOC_COMMENT)) {
+                continue;
+            }
+
+            $docBlock = new DocBlock($tokens[$index]->getContent());
+
+            $fqcn = ($namespace !== '' ? '\\' . $namespace : '') . '\\' . $name;
+
+            foreach ($docBlock->getAnnotations() as $annotation) {
+                if (!$annotation->supportTypes()) {
+                    continue;
+                }
+
+                $types = [];
+                foreach ($annotation->getTypes() as $type) {
+                    $types[] = \preg_replace(
+                        \sprintf('/(?<![a-zA-Z0-9_\x7f-\xff\\\\])(%s|%s)\b(?!\\\\)/', $name, \preg_quote($fqcn, '/')),
+                        'self',
+                        $type
+                    );
+                }
+
+                if ($types === $annotation->getTypes()) {
+                    continue;
+                }
+                $annotation->setTypes($types);
+                $tokens[$index] = new Token([T_DOC_COMMENT, $docBlock->getContent()]);
+            }
+        }
+    }
+}

tests/Fixer/PhpdocSelfAccessorFixerTest.php

@@ -0,0 +1,158 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace Tests\Fixer;
+
+/**
+ * @internal
+ *
+ * @covers \PhpCsFixerCustomFixers\Fixer\PhpdocSelfAccessorFixer
+ */
+final class PhpdocSelfAccessorFixerTest extends AbstractFixerTestCase
+{
+    public function testPriority(): void
+    {
+        static::assertSame(0, $this->fixer->getPriority());
+    }
+
+    public function testIsRisky(): void
+    {
+        static::assertFalse($this->fixer->isRisky());
+    }
+
+    /**
+     * @param string      $expected
+     * @param string|null $input
+     *
+     * @dataProvider provideFixCases
+     */
+    public function testFix(string $expected, string $input = null): void
+    {
+        $this->doTest($expected, $input);
+    }
+
+    public function provideFixCases(): \Iterator
+    {
+        yield [ // no namespace - do not change
+            '<?php
+class Foo {
+    /**
+     * @var FooBar
+     */
+     private $instance;
+     
+     /**
+      * @param Foo\Bar $x
+      * @param Bar\Foo $x
+      * @param int $x count of Foo
+      * @see Foo documentation
+      */
+      public function bar(...$params) {}
+}',
+        ];
+
+        yield [ // no namespace - change
+            '<?php
+class Foo {
+    /**
+     * @var self
+     */
+     private $instance;
+     
+     /**
+      * @param self $x
+      * @param self $x
+      * @param bool|self $x
+      * @param self|int $x
+      * @param bool|self|int $x
+      * @param bool|self|int $x
+      * @param self[] $foos
+      * @param self[] $foos
+      * @param Array<int, self> $foos
+      * @param Array<self, int> $foos
+      *
+      * @return self
+      */
+      public function bar(...$params) {}
+}',
+            '<?php
+class Foo {
+    /**
+     * @var Foo
+     */
+     private $instance;
+     
+     /**
+      * @param Foo $x
+      * @param \Foo $x
+      * @param bool|Foo $x
+      * @param Foo|int $x
+      * @param bool|Foo|int $x
+      * @param bool|\Foo|int $x
+      * @param Foo[] $foos
+      * @param \Foo[] $foos
+      * @param Array<int, Foo> $foos
+      * @param Array<\Foo, int> $foos
+      *
+      * @return Foo
+      */
+      public function bar(...$params) {}
+}',
+        ];
+
+        yield [ // with namespace - do not change
+            '<?php
+namespace Some\Thing;
+class Foo {
+     /**
+      * @param \Foo $x
+      * @param Some\Foo $x
+      * @param Thing\Foo $x
+      * @param Some\Thing\Foo $x
+      * @param Foo\Some $x
+      * @param Foo\Some\Thing $x
+      * @param Foo\Some\Thing\Foo $x
+      * @param \Foo[] $foos
+      * @param Array<int, \Foo> $foos
+      */
+      public function bar(...$params) {}
+}',
+        ];
+
+        yield [ // with namespace - change
+            '<?php
+namespace Some\Thing;
+class Foo {
+     /**
+      * @param self $x
+      * @param self $x
+      * @param bool|self $x
+      * @param self|int $x
+      * @param bool|self|int $x
+      * @param self[] $foos
+      * @param self[] $foos
+      * @param Array<int, self> $foos
+      * @param Array<self, int> $foos
+      */
+      public function bar(...$params) {}
+}',
+            '<?php
+namespace Some\Thing;
+class Foo {
+     /**
+      * @param Foo $x
+      * @param \Some\Thing\Foo $x
+      * @param bool|\Some\Thing\Foo $x
+      * @param \Some\Thing\Foo|int $x
+      * @param bool|\Some\Thing\Foo|int $x
+      * @param Foo[] $foos
+      * @param \Some\Thing\Foo[] $foos
+      * @param Array<int, Foo> $foos
+      * @param Array<\Some\Thing\Foo, int> $foos
+      */
+      public function bar(...$params) {}
+}',
+        ];
+    }
+}