Skip to content

Commit d9f0339

Browse files
authored
[docblocks] Add MergePhpstanDocTagIntoNativeRector to merge @phpstan-* doc tags into native tags (#8171)
1 parent d67958f commit d9f0339

9 files changed

Lines changed: 341 additions & 2 deletions

File tree

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
<?php
2+
3+
namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\Fixture;
4+
5+
final class MethodParamAndReturn
6+
{
7+
/**
8+
* @param array $values
9+
* @phpstan-param array<int, string> $values
10+
*
11+
* @return array
12+
* @phpstan-return array<int, string>
13+
*/
14+
public function process($values)
15+
{
16+
return $values;
17+
}
18+
}
19+
20+
?>
21+
-----
22+
<?php
23+
24+
namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\Fixture;
25+
26+
final class MethodParamAndReturn
27+
{
28+
/**
29+
* @param array<int, string> $values
30+
*
31+
* @return array<int, string>
32+
*/
33+
public function process($values)
34+
{
35+
return $values;
36+
}
37+
}
38+
39+
?>
Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
<?php
2+
3+
namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\Fixture;
4+
5+
final class PhpstanOnlyVar
6+
{
7+
/**
8+
* @phpstan-var Collection<int, string>
9+
*/
10+
private $items;
11+
}
12+
13+
?>
14+
-----
15+
<?php
16+
17+
namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\Fixture;
18+
19+
final class PhpstanOnlyVar
20+
{
21+
/**
22+
* @var Collection<int, string>
23+
*/
24+
private $items;
25+
}
26+
27+
?>
Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
<?php
2+
3+
namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\Fixture;
4+
5+
final class PropertyVar
6+
{
7+
/**
8+
* @var Collection
9+
*
10+
* @phpstan-var Collection<int, string>
11+
*/
12+
private $items;
13+
}
14+
15+
?>
16+
-----
17+
<?php
18+
19+
namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\Fixture;
20+
21+
final class PropertyVar
22+
{
23+
/**
24+
* @var Collection<int, string>
25+
*/
26+
private $items;
27+
}
28+
29+
?>
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<?php
2+
3+
namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\Fixture;
4+
5+
final class SkipNoPhpstanTag
6+
{
7+
/**
8+
* @var Collection
9+
*/
10+
private $items;
11+
}
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector;
6+
7+
use Iterator;
8+
use PHPUnit\Framework\Attributes\DataProvider;
9+
use Rector\Testing\PHPUnit\AbstractRectorTestCase;
10+
11+
final class MergePhpstanDocTagIntoNativeRectorTest extends AbstractRectorTestCase
12+
{
13+
#[DataProvider('provideData')]
14+
public function test(string $filePath): void
15+
{
16+
$this->doTestFile($filePath);
17+
}
18+
19+
public static function provideData(): Iterator
20+
{
21+
return self::yieldFilesFromDirectory(__DIR__ . '/Fixture');
22+
}
23+
24+
public function provideConfigFilePath(): string
25+
{
26+
return __DIR__ . '/config/configured_rule.php';
27+
}
28+
}
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
use Rector\Config\RectorConfig;
6+
use Rector\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector;
7+
8+
return RectorConfig::configure()
9+
->withRules([MergePhpstanDocTagIntoNativeRector::class]);
Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Rector\TypeDeclarationDocblocks\Rector\Property;
6+
7+
use PhpParser\Node;
8+
use PhpParser\Node\Param;
9+
use PhpParser\Node\Stmt\ClassConst;
10+
use PhpParser\Node\Stmt\ClassMethod;
11+
use PhpParser\Node\Stmt\Function_;
12+
use PhpParser\Node\Stmt\Property;
13+
use PHPStan\PhpDocParser\Ast\PhpDoc\ParamTagValueNode;
14+
use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTagNode;
15+
use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTextNode;
16+
use PHPStan\PhpDocParser\Ast\PhpDoc\ReturnTagValueNode;
17+
use PHPStan\PhpDocParser\Ast\PhpDoc\VarTagValueNode;
18+
use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfo;
19+
use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
20+
use Rector\Comments\NodeDocBlock\DocBlockUpdater;
21+
use Rector\Rector\AbstractRector;
22+
use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
23+
use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
24+
25+
/**
26+
* @see \Rector\Tests\TypeDeclarationDocblocks\Rector\Property\MergePhpstanDocTagIntoNativeRector\MergePhpstanDocTagIntoNativeRectorTest
27+
*/
28+
final class MergePhpstanDocTagIntoNativeRector extends AbstractRector
29+
{
30+
/**
31+
* @var array<string, string>
32+
*/
33+
private const array PHPSTAN_TAG_TO_NATIVE_TAG = [
34+
'@phpstan-var' => '@var',
35+
'@phpstan-param' => '@param',
36+
'@phpstan-return' => '@return',
37+
];
38+
39+
public function __construct(
40+
private readonly DocBlockUpdater $docBlockUpdater,
41+
private readonly PhpDocInfoFactory $phpDocInfoFactory,
42+
) {
43+
}
44+
45+
public function getRuleDefinition(): RuleDefinition
46+
{
47+
return new RuleDefinition(
48+
'Merge more precise @phpstan-var/@phpstan-param/@phpstan-return docblock tag into its native @var/@param/@return tag',
49+
[
50+
new CodeSample(
51+
<<<'CODE_SAMPLE'
52+
final class SomeClass
53+
{
54+
/**
55+
* @var Collection
56+
*
57+
* @phpstan-var Collection<int, string>
58+
*/
59+
private $items;
60+
}
61+
CODE_SAMPLE
62+
,
63+
<<<'CODE_SAMPLE'
64+
final class SomeClass
65+
{
66+
/**
67+
* @var Collection<int, string>
68+
*/
69+
private $items;
70+
}
71+
CODE_SAMPLE
72+
),
73+
]
74+
);
75+
}
76+
77+
/**
78+
* @return array<class-string<Node>>
79+
*/
80+
public function getNodeTypes(): array
81+
{
82+
return [Property::class, Param::class, ClassConst::class, ClassMethod::class, Function_::class];
83+
}
84+
85+
/**
86+
* @param Property|Param|ClassConst|ClassMethod|Function_ $node
87+
*/
88+
public function refactor(Node $node): ?Node
89+
{
90+
$phpDocInfo = $this->phpDocInfoFactory->createFromNode($node);
91+
if (! $phpDocInfo instanceof PhpDocInfo) {
92+
return null;
93+
}
94+
95+
$phpDocNode = $phpDocInfo->getPhpDocNode();
96+
97+
$phpstanParamNames = [];
98+
$phpstanVarNames = [];
99+
$hasPhpstanReturn = false;
100+
101+
foreach ($phpDocNode->children as $phpDocChildNode) {
102+
if (! $phpDocChildNode instanceof PhpDocTagNode) {
103+
continue;
104+
}
105+
106+
if ($phpDocChildNode->name === '@phpstan-param' && $phpDocChildNode->value instanceof ParamTagValueNode) {
107+
$phpstanParamNames[] = $phpDocChildNode->value->parameterName;
108+
} elseif ($phpDocChildNode->name === '@phpstan-var' && $phpDocChildNode->value instanceof VarTagValueNode) {
109+
$phpstanVarNames[] = $phpDocChildNode->value->variableName;
110+
} elseif ($phpDocChildNode->name === '@phpstan-return' && $phpDocChildNode->value instanceof ReturnTagValueNode) {
111+
$hasPhpstanReturn = true;
112+
}
113+
}
114+
115+
if ($phpstanParamNames === [] && $phpstanVarNames === [] && ! $hasPhpstanReturn) {
116+
return null;
117+
}
118+
119+
$hasChanged = false;
120+
121+
foreach ($phpDocNode->children as $key => $phpDocChildNode) {
122+
if (! $phpDocChildNode instanceof PhpDocTagNode) {
123+
continue;
124+
}
125+
126+
// drop the weaker native tag that the @phpstan-* variant overrules
127+
if ($this->isOverruledNativeTag(
128+
$phpDocChildNode,
129+
$phpstanParamNames,
130+
$phpstanVarNames,
131+
$hasPhpstanReturn
132+
)) {
133+
unset($phpDocNode->children[$key]);
134+
$hasChanged = true;
135+
continue;
136+
}
137+
138+
// promote the @phpstan-* tag to its native counterpart
139+
$nativeTagName = self::PHPSTAN_TAG_TO_NATIVE_TAG[$phpDocChildNode->name] ?? null;
140+
if ($nativeTagName !== null) {
141+
$phpDocNode->children[$key] = new PhpDocTagNode($nativeTagName, $phpDocChildNode->value);
142+
$hasChanged = true;
143+
}
144+
}
145+
146+
if (! $hasChanged) {
147+
return null;
148+
}
149+
150+
$phpDocNode->children = array_values($phpDocNode->children);
151+
152+
// drop a leading empty line left behind by a removed native tag
153+
while ($phpDocNode->children !== []) {
154+
$firstChildNode = $phpDocNode->children[0];
155+
if ($firstChildNode instanceof PhpDocTextNode && trim($firstChildNode->text) === '') {
156+
array_shift($phpDocNode->children);
157+
continue;
158+
}
159+
160+
break;
161+
}
162+
163+
$this->docBlockUpdater->updateRefactoredNodeWithPhpDocInfo($node);
164+
165+
return $node;
166+
}
167+
168+
/**
169+
* @param string[] $phpstanParamNames
170+
* @param string[] $phpstanVarNames
171+
*/
172+
private function isOverruledNativeTag(
173+
PhpDocTagNode $phpDocTagNode,
174+
array $phpstanParamNames,
175+
array $phpstanVarNames,
176+
bool $hasPhpstanReturn
177+
): bool {
178+
if ($phpDocTagNode->name === '@param' && $phpDocTagNode->value instanceof ParamTagValueNode) {
179+
return in_array($phpDocTagNode->value->parameterName, $phpstanParamNames, true);
180+
}
181+
182+
if ($phpDocTagNode->name === '@var' && $phpDocTagNode->value instanceof VarTagValueNode) {
183+
return in_array($phpDocTagNode->value->variableName, $phpstanVarNames, true);
184+
}
185+
186+
if ($phpDocTagNode->name === '@return' && $phpDocTagNode->value instanceof ReturnTagValueNode) {
187+
return $hasPhpstanReturn;
188+
}
189+
190+
return false;
191+
}
192+
}

‎scoper.php‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,11 @@ static function (array $ruleDefinitionMatch) use ($prefix): string {
126126
"#(<<<'?(?<label>CODE_SAMPLE|SAMPLE)'?\\R)(.*?)(\\R\\s*\\k<label>)#s",
127127
static function (array $codeSampleMatch) use ($prefix): string {
128128
$body = str_replace($prefix . '\\', '', $codeSampleMatch[3]);
129-
$body = Strings::replace($body, '#^[ \t]*namespace ' . preg_quote($prefix, '#') . ';\R\R?#m', '');
129+
$body = Strings::replace(
130+
$body,
131+
'#^[ \t]*namespace ' . preg_quote($prefix, '#') . ';\R\R?#m',
132+
''
133+
);
130134
$body = Strings::replace($body, '#\R[ \t]*\\\\class_alias\(.*?\);$#', '');
131135

132136
return $codeSampleMatch[1] . $body . $codeSampleMatch[4];

‎tests/Scoper/ScoperPatchersTest.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,10 @@
44

55
namespace Rector\Tests\Scoper;
66

7-
use Webmozart\Assert\Assert;
87
use Closure;
98
use PHPUnit\Framework\TestCase;
109
use Symfony\Component\Finder\Finder;
10+
use Webmozart\Assert\Assert;
1111

1212
final class ScoperPatchersTest extends TestCase
1313
{

0 commit comments

Comments
 (0)