From 6ad966b2d1efd70547bc623e7b3c95d2cc0abda7 Mon Sep 17 00:00:00 2001
From: Tomas Votruba <tomas.vot@gmail.com>
Date: Sat, 11 Jul 2026 09:27:27 +0200
Subject: [PATCH] Add MergePhpstanDocTagIntoNativeRector to merge @phpstan-*
 doc tags into native @var/@param/@return

---
 .../Fixture/method_param_and_return.php.inc   |  39 ++++
 .../Fixture/phpstan_only_var.php.inc          |  27 +++
 .../Fixture/property_var.php.inc              |  29 +++
 .../Fixture/skip_no_phpstan_tag.php.inc       |  11 +
 ...MergePhpstanDocTagIntoNativeRectorTest.php |  28 +++
 .../config/configured_rule.php                |   9 +
 .../MergePhpstanDocTagIntoNativeRector.php    | 192 ++++++++++++++++++
 scoper.php                                    |   6 +-
 tests/Scoper/ScoperPatchersTest.php           |   2 +-
 9 files changed, 341 insertions(+), 2 deletions(-)
 create mode 100644 rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/Fixture/method_param_and_return.php.inc
 create mode 100644 rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/Fixture/phpstan_only_var.php.inc
 create mode 100644 rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/Fixture/property_var.php.inc
 create mode 100644 rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/Fixture/skip_no_phpstan_tag.php.inc
 create mode 100644 rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/MergePhpstanDocTagIntoNativeRectorTest.php
 create mode 100644 rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/config/configured_rule.php
 create mode 100644 rules/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector.php

diff --git a/rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/Fixture/method_param_and_return.php.inc b/rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/Fixture/method_param_and_return.php.inc
new file mode 100644
index 00000000000..12654e63416
--- /dev/null
+++ b/rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/Fixture/method_param_and_return.php.inc
@@ -0,0 +1,39 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\Fixture;
+
+final class MethodParamAndReturn
+{
+    /**
+     * @param array $values
+     * @phpstan-param array<int, string> $values
+     *
+     * @return array
+     * @phpstan-return array<int, string>
+     */
+    public function process($values)
+    {
+        return $values;
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\Fixture;
+
+final class MethodParamAndReturn
+{
+    /**
+     * @param array<int, string> $values
+     *
+     * @return array<int, string>
+     */
+    public function process($values)
+    {
+        return $values;
+    }
+}
+
+?>
diff --git a/rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/Fixture/phpstan_only_var.php.inc b/rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/Fixture/phpstan_only_var.php.inc
new file mode 100644
index 00000000000..fdbb8ee58d8
--- /dev/null
+++ b/rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/Fixture/phpstan_only_var.php.inc
@@ -0,0 +1,27 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\Fixture;
+
+final class PhpstanOnlyVar
+{
+    /**
+     * @phpstan-var Collection<int, string>
+     */
+    private $items;
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\Fixture;
+
+final class PhpstanOnlyVar
+{
+    /**
+     * @var Collection<int, string>
+     */
+    private $items;
+}
+
+?>
diff --git a/rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/Fixture/property_var.php.inc b/rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/Fixture/property_var.php.inc
new file mode 100644
index 00000000000..710c735f135
--- /dev/null
+++ b/rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/Fixture/property_var.php.inc
@@ -0,0 +1,29 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\Fixture;
+
+final class PropertyVar
+{
+    /**
+     * @var Collection
+     *
+     * @phpstan-var Collection<int, string>
+     */
+    private $items;
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\Fixture;
+
+final class PropertyVar
+{
+    /**
+     * @var Collection<int, string>
+     */
+    private $items;
+}
+
+?>
diff --git a/rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/Fixture/skip_no_phpstan_tag.php.inc b/rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/Fixture/skip_no_phpstan_tag.php.inc
new file mode 100644
index 00000000000..878f4c3f4d4
--- /dev/null
+++ b/rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/Fixture/skip_no_phpstan_tag.php.inc
@@ -0,0 +1,11 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\Fixture;
+
+final class SkipNoPhpstanTag
+{
+    /**
+     * @var Collection
+     */
+    private $items;
+}
diff --git a/rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/MergePhpstanDocTagIntoNativeRectorTest.php b/rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/MergePhpstanDocTagIntoNativeRectorTest.php
new file mode 100644
index 00000000000..427830e1a1d
--- /dev/null
+++ b/rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/MergePhpstanDocTagIntoNativeRectorTest.php
@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector;
+
+use Iterator;
+use PHPUnit\Framework\Attributes\DataProvider;
+use Rector\Testing\PHPUnit\AbstractRectorTestCase;
+
+final class MergePhpstanDocTagIntoNativeRectorTest 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';
+    }
+}
diff --git a/rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/config/configured_rule.php b/rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/config/configured_rule.php
new file mode 100644
index 00000000000..4481f085ac4
--- /dev/null
+++ b/rules-tests/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector/config/configured_rule.php
@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+use Rector\Config\RectorConfig;
+use Rector\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector;
+
+return RectorConfig::configure()
+    ->withRules([MergePhpstanDocTagIntoNativeRector::class]);
diff --git a/rules/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector.php b/rules/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector.php
new file mode 100644
index 00000000000..230aba71da5
--- /dev/null
+++ b/rules/TypeDeclarationDocblocks/Rector/Property/MergePhpstanDocTagIntoNativeRector.php
@@ -0,0 +1,192 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\TypeDeclarationDocblocks\Rector\Property;
+
+use PhpParser\Node;
+use PhpParser\Node\Param;
+use PhpParser\Node\Stmt\ClassConst;
+use PhpParser\Node\Stmt\ClassMethod;
+use PhpParser\Node\Stmt\Function_;
+use PhpParser\Node\Stmt\Property;
+use PHPStan\PhpDocParser\Ast\PhpDoc\ParamTagValueNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTagNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTextNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\ReturnTagValueNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\VarTagValueNode;
+use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfo;
+use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
+use Rector\Comments\NodeDocBlock\DocBlockUpdater;
+use Rector\Rector\AbstractRector;
+use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
+use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
+
+/**
+ * @see \Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\MergePhpstanDocTagIntoNativeRectorTest
+ */
+final class MergePhpstanDocTagIntoNativeRector extends AbstractRector
+{
+    /**
+     * @var array<string, string>
+     */
+    private const array PHPSTAN_TAG_TO_NATIVE_TAG = [
+        '@phpstan-var' => '@var',
+        '@phpstan-param' => '@param',
+        '@phpstan-return' => '@return',
+    ];
+
+    public function __construct(
+        private readonly DocBlockUpdater $docBlockUpdater,
+        private readonly PhpDocInfoFactory $phpDocInfoFactory,
+    ) {
+    }
+
+    public function getRuleDefinition(): RuleDefinition
+    {
+        return new RuleDefinition(
+            'Merge more precise @phpstan-var/@phpstan-param/@phpstan-return docblock tag into its native @var/@param/@return tag',
+            [
+                new CodeSample(
+                    <<<'CODE_SAMPLE'
+final class SomeClass
+{
+    /**
+     * @var Collection
+     *
+     * @phpstan-var Collection<int, string>
+     */
+    private $items;
+}
+CODE_SAMPLE
+                    ,
+                    <<<'CODE_SAMPLE'
+final class SomeClass
+{
+    /**
+     * @var Collection<int, string>
+     */
+    private $items;
+}
+CODE_SAMPLE
+                ),
+            ]
+        );
+    }
+
+    /**
+     * @return array<class-string<Node>>
+     */
+    public function getNodeTypes(): array
+    {
+        return [Property::class, Param::class, ClassConst::class, ClassMethod::class, Function_::class];
+    }
+
+    /**
+     * @param Property|Param|ClassConst|ClassMethod|Function_ $node
+     */
+    public function refactor(Node $node): ?Node
+    {
+        $phpDocInfo = $this->phpDocInfoFactory->createFromNode($node);
+        if (! $phpDocInfo instanceof PhpDocInfo) {
+            return null;
+        }
+
+        $phpDocNode = $phpDocInfo->getPhpDocNode();
+
+        $phpstanParamNames = [];
+        $phpstanVarNames = [];
+        $hasPhpstanReturn = false;
+
+        foreach ($phpDocNode->children as $phpDocChildNode) {
+            if (! $phpDocChildNode instanceof PhpDocTagNode) {
+                continue;
+            }
+
+            if ($phpDocChildNode->name === '@phpstan-param' && $phpDocChildNode->value instanceof ParamTagValueNode) {
+                $phpstanParamNames[] = $phpDocChildNode->value->parameterName;
+            } elseif ($phpDocChildNode->name === '@phpstan-var' && $phpDocChildNode->value instanceof VarTagValueNode) {
+                $phpstanVarNames[] = $phpDocChildNode->value->variableName;
+            } elseif ($phpDocChildNode->name === '@phpstan-return' && $phpDocChildNode->value instanceof ReturnTagValueNode) {
+                $hasPhpstanReturn = true;
+            }
+        }
+
+        if ($phpstanParamNames === [] && $phpstanVarNames === [] && ! $hasPhpstanReturn) {
+            return null;
+        }
+
+        $hasChanged = false;
+
+        foreach ($phpDocNode->children as $key => $phpDocChildNode) {
+            if (! $phpDocChildNode instanceof PhpDocTagNode) {
+                continue;
+            }
+
+            // drop the weaker native tag that the @phpstan-* variant overrules
+            if ($this->isOverruledNativeTag(
+                $phpDocChildNode,
+                $phpstanParamNames,
+                $phpstanVarNames,
+                $hasPhpstanReturn
+            )) {
+                unset($phpDocNode->children[$key]);
+                $hasChanged = true;
+                continue;
+            }
+
+            // promote the @phpstan-* tag to its native counterpart
+            $nativeTagName = self::PHPSTAN_TAG_TO_NATIVE_TAG[$phpDocChildNode->name] ?? null;
+            if ($nativeTagName !== null) {
+                $phpDocNode->children[$key] = new PhpDocTagNode($nativeTagName, $phpDocChildNode->value);
+                $hasChanged = true;
+            }
+        }
+
+        if (! $hasChanged) {
+            return null;
+        }
+
+        $phpDocNode->children = array_values($phpDocNode->children);
+
+        // drop a leading empty line left behind by a removed native tag
+        while ($phpDocNode->children !== []) {
+            $firstChildNode = $phpDocNode->children[0];
+            if ($firstChildNode instanceof PhpDocTextNode && trim($firstChildNode->text) === '') {
+                array_shift($phpDocNode->children);
+                continue;
+            }
+
+            break;
+        }
+
+        $this->docBlockUpdater->updateRefactoredNodeWithPhpDocInfo($node);
+
+        return $node;
+    }
+
+    /**
+     * @param string[] $phpstanParamNames
+     * @param string[] $phpstanVarNames
+     */
+    private function isOverruledNativeTag(
+        PhpDocTagNode $phpDocTagNode,
+        array $phpstanParamNames,
+        array $phpstanVarNames,
+        bool $hasPhpstanReturn
+    ): bool {
+        if ($phpDocTagNode->name === '@param' && $phpDocTagNode->value instanceof ParamTagValueNode) {
+            return in_array($phpDocTagNode->value->parameterName, $phpstanParamNames, true);
+        }
+
+        if ($phpDocTagNode->name === '@var' && $phpDocTagNode->value instanceof VarTagValueNode) {
+            return in_array($phpDocTagNode->value->variableName, $phpstanVarNames, true);
+        }
+
+        if ($phpDocTagNode->name === '@return' && $phpDocTagNode->value instanceof ReturnTagValueNode) {
+            return $hasPhpstanReturn;
+        }
+
+        return false;
+    }
+}
diff --git a/scoper.php b/scoper.php
index a744e529014..4bbfc32d8e7 100644
--- a/scoper.php
+++ b/scoper.php
@@ -126,7 +126,11 @@ static function (array $ruleDefinitionMatch) use ($prefix): string {
                         "#(<<<'?(?<label>CODE_SAMPLE|SAMPLE)'?\\R)(.*?)(\\R\\s*\\k<label>)#s",
                         static function (array $codeSampleMatch) use ($prefix): string {
                             $body = str_replace($prefix . '\\', '', $codeSampleMatch[3]);
-                            $body = Strings::replace($body, '#^[ \t]*namespace ' . preg_quote($prefix, '#') . ';\R\R?#m', '');
+                            $body = Strings::replace(
+                                $body,
+                                '#^[ \t]*namespace ' . preg_quote($prefix, '#') . ';\R\R?#m',
+                                ''
+                            );
                             $body = Strings::replace($body, '#\R[ \t]*\\\\class_alias\(.*?\);$#', '');
 
                             return $codeSampleMatch[1] . $body . $codeSampleMatch[4];
diff --git a/tests/Scoper/ScoperPatchersTest.php b/tests/Scoper/ScoperPatchersTest.php
index edc9b52ae74..ee305b39883 100644
--- a/tests/Scoper/ScoperPatchersTest.php
+++ b/tests/Scoper/ScoperPatchersTest.php
@@ -4,10 +4,10 @@
 
 namespace Rector\Tests\Scoper;
 
-use Webmozart\Assert\Assert;
 use Closure;
 use PHPUnit\Framework\TestCase;
 use Symfony\Component\Finder\Finder;
+use Webmozart\Assert\Assert;
 
 final class ScoperPatchersTest extends TestCase
 {