Allow configuring custom PHPDoc tags that reference classes

src/BetterPhpDocParser/PhpDocParser/PhpDocTagGenericUsesDecorator.php

@@ -11,6 +11,8 @@
 use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTagNode;
 use Rector\BetterPhpDocParser\Contract\PhpDocParser\PhpDocNodeDecoratorInterface;
 use Rector\BetterPhpDocParser\ValueObject\PhpDocAttributeKey;
+use Rector\Configuration\Option;
+use Rector\Configuration\Parameter\SimpleParameterProvider;
 use Rector\PhpDocParser\PhpDocParser\PhpDocNodeTraverser;
 use Rector\StaticTypeMapper\Naming\NameScopeFactory;
 
@@ -46,7 +48,7 @@ public function decorate(PhpDocNode $phpDocNode, PhpNode $phpNode): void
                 return null;
             }
 
-            if (! in_array($node->name, ['@uses', '@used-by', '@see'], true)) {
+            if (! in_array($node->name, $this->resolveTagNames(), true)) {
                 return null;
             }
 
@@ -67,6 +69,24 @@ public function decorate(PhpDocNode $phpDocNode, PhpNode $phpNode): void
         });
     }
 
+    /**
+     * @return string[]
+     */
+    private function resolveTagNames(): array
+    {
+        $defaultTags = ['@uses', '@used-by', '@see'];
+
+        $additionalTags = SimpleParameterProvider::provideArrayParameter(
+            Option::PHPDOC_TAGS_WITH_CLASS_REFERENCE
+        );
+
+        if ($additionalTags === []) {
+            return $defaultTags;
+        }
+
+        return array_merge($defaultTags, $additionalTags);
+    }
+
     private function resolveFullyQualifiedClass(string $classValue, PhpNode $phpNode): string
     {
         $nameScope = $this->nameScopeFactory->createNameScopeFromNodeWithoutTemplateTypes($phpNode);

src/Config/RectorConfig.php

@@ -133,6 +133,14 @@ public function removeUnusedImports(bool $removeUnusedImports = true): void
         SimpleParameterProvider::setParameter(Option::REMOVE_UNUSED_IMPORTS, $removeUnusedImports);
     }
 
+    /**
+     * @param string[] $tags
+     */
+    public function phpDocTagsWithClassReference(array $tags): void
+    {
+        SimpleParameterProvider::addParameter(Option::PHPDOC_TAGS_WITH_CLASS_REFERENCE, $tags);
+    }
+
     public function importNames(bool $importNames = true, bool $importDocBlockNames = true): void
     {
         SimpleParameterProvider::setParameter(Option::AUTO_IMPORT_NAMES, $importNames);

src/Configuration/Option.php

@@ -260,4 +260,10 @@ final class Option
      * @internal to allow process file without extension if explicitly registered
      */
     public const string FILES_WITHOUT_EXTENSION = 'files_without_extension';
+
+    /**
+     * @internal Use @see \Rector\Config\RectorConfig::phpDocTagsWithClassReference() method
+     * @var string
+     */
+    public const string PHPDOC_TAGS_WITH_CLASS_REFERENCE = 'phpdoc_tags_with_class_reference';
 }

src/Configuration/RectorConfigBuilder.php

@@ -107,6 +107,11 @@ final class RectorConfigBuilder
 
     private bool $removeUnusedImports = false;
 
+    /**
+     * @var string[]
+     */
+    private array $phpDocTagsWithClassReference = [];
+
     private bool $noDiffs = false;
 
     private ?string $memoryLimit = null;
@@ -325,6 +330,10 @@ public function __invoke(RectorConfig $rectorConfig): void
             $rectorConfig->removeUnusedImports($this->removeUnusedImports);
         }
 
+        if ($this->phpDocTagsWithClassReference !== []) {
+            $rectorConfig->phpDocTagsWithClassReference($this->phpDocTagsWithClassReference);
+        }
+
         if ($this->noDiffs) {
             $rectorConfig->noDiffs();
         }
@@ -933,6 +942,15 @@ public function withImportNames(
         return $this;
     }
 
+    /**
+     * @param string[] $tags
+     */
+    public function withPhpDocTagsWithClassReference(array $tags): self
+    {
+        $this->phpDocTagsWithClassReference = $tags;
+        return $this;
+    }
+
     public function withNoDiffs(): self
     {
         $this->noDiffs = true;

src/Testing/PHPUnit/AbstractRectorTestCase.php

@@ -53,6 +53,7 @@ public static function tearDownAfterClass(): void
         SimpleParameterProvider::setParameter(Option::AUTO_IMPORT_NAMES, false);
         SimpleParameterProvider::setParameter(Option::AUTO_IMPORT_DOC_BLOCK_NAMES, false);
         SimpleParameterProvider::setParameter(Option::REMOVE_UNUSED_IMPORTS, false);
+        SimpleParameterProvider::setParameter(Option::PHPDOC_TAGS_WITH_CLASS_REFERENCE, []);
         SimpleParameterProvider::setParameter(Option::IMPORT_SHORT_CLASSES, true);
 
         SimpleParameterProvider::setParameter(Option::INDENT_CHAR, ' ');

tests/Issues/CustomPhpDocTagClassReference/CustomPhpDocTagClassReferenceTest.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\Issues\CustomPhpDocTagClassReference;
+
+use Iterator;
+use PHPUnit\Framework\Attributes\DataProvider;
+use Rector\Testing\PHPUnit\AbstractRectorTestCase;
+
+final class CustomPhpDocTagClassReferenceTest extends AbstractRectorTestCase
+{
+    #[DataProvider('provideData')]
+    public function test(string $filePath): void
+    {
+        $this->doTestFile($filePath);
+    }
+
+    public static function provideData(): Iterator
+    {
+        return self::yieldFilesFromDirectory(__DIR__ . '/Fixture');
+    }
+
+    public function provideConfigFilePath(): string
+    {
+        return __DIR__ . '/config/configured_rule.php';
+    }
+}

tests/Issues/CustomPhpDocTagClassReference/Fixture/skip_custom_tag_with_class_reference.php.inc

@@ -0,0 +1,12 @@
+<?php
+
+namespace Rector\Tests\Issues\CustomPhpDocTagClassReference\Fixture;
+
+use Rector\Tests\Issues\CustomPhpDocTagClassReference\Source\NotificationHandler;
+
+/**
+ * @throwable-from NotificationHandler::createPayload
+ */
+final class SkipCustomTagWithClassReference extends \Exception
+{
+}

tests/Issues/CustomPhpDocTagClassReference/Source/NotificationHandler.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\Issues\CustomPhpDocTagClassReference\Source;
+
+final class NotificationHandler
+{
+    public function createPayload(): void
+    {
+    }
+}

tests/Issues/CustomPhpDocTagClassReference/config/configured_rule.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+use Rector\Config\RectorConfig;
+
+return static function (RectorConfig $rectorConfig): void {
+    $rectorConfig->removeUnusedImports();
+    $rectorConfig->phpDocTagsWithClassReference(['@throwable-from']);
+};