Skip to content

Commit b2bf1c3

Browse files
committed
rename rule to NarrowReturnToUnionParamRule, suggest explicit union return instead of generic
1 parent 5728452 commit b2bf1c3

7 files changed

Lines changed: 63 additions & 61 deletions

File tree

‎phpstan.neon‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ rules:
55
- Rector\Utils\PHPStan\Rule\RegisterRelatedPolyfillRectorRule
66
- Rector\Utils\PHPStan\Rule\NoScopeFetchBeforeCheapGuardRule
77
- Rector\Utils\PHPStan\Rule\PreferGenericTemplateOnSameUnionTypeRule
8-
- Rector\Utils\PHPStan\Rule\PreferGenericTemplateOnReturnedUnionParamRule
8+
- Rector\Utils\PHPStan\Rule\NarrowReturnToUnionParamRule
99

1010
parameters:
1111
level: 8

‎rules/Arguments/ArgumentDefaultValueReplacer.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,7 @@ private function processParams(
105105
private function processArgs(
106106
MethodCall|StaticCall|FuncCall|New_ $expr,
107107
ReplaceArgumentDefaultValueInterface $replaceArgumentDefaultValue
108-
): ?Expr {
108+
): MethodCall|StaticCall|FuncCall|New_|null {
109109
if ($expr->isFirstClassCallable()) {
110110
return null;
111111
}

utils/phpstan/src/Rule/PreferGenericTemplateOnReturnedUnionParamRule.php renamed to utils/phpstan/src/Rule/NarrowReturnToUnionParamRule.php

Lines changed: 26 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
namespace Rector\Utils\PHPStan\Rule;
66

7-
use PhpParser\Comment\Doc;
7+
use PhpParser\Node\IntersectionType;
88
use PhpParser\Node;
99
use PhpParser\Node\ComplexType;
1010
use PhpParser\Node\Expr\Variable;
@@ -22,15 +22,15 @@
2222

2323
/**
2424
* Flags a method that takes a class-type union param (A|B) but declares a broader single return type
25-
* (e.g. their shared parent Node), then returns that very param - a hidden generic.
26-
* A @template generic narrows the return to the passed type instead of the broad parent.
25+
* (e.g. their shared parent Node), then returns that very param.
26+
* The return type should be the explicit union the param carries, not the broad parent.
2727
*
2828
* @implements Rule<ClassMethod>
29-
* @see \Rector\Utils\PHPStan\Tests\Rule\PreferGenericTemplateOnReturnedUnionParamRule\PreferGenericTemplateOnReturnedUnionParamRuleTest
29+
* @see \Rector\Utils\PHPStan\Tests\Rule\NarrowReturnToUnionParamRule\NarrowReturnToUnionParamRuleTest
3030
*/
31-
final class PreferGenericTemplateOnReturnedUnionParamRule implements Rule
31+
final class NarrowReturnToUnionParamRule implements Rule
3232
{
33-
private const string ERROR_MESSAGE = 'Return type "%s" is broader than the returned union param "%s". Add a @template generic to narrow the return type to the passed one.';
33+
private const string ERROR_MESSAGE = 'Return type "%s" is too broad for a returned union param. Declare the explicit union return type "%s" instead.';
3434

3535
public function getNodeType(): string
3636
{
@@ -43,11 +43,6 @@ public function getNodeType(): string
4343
*/
4444
public function processNode(Node $node, Scope $scope): array
4545
{
46-
$docComment = $node->getDocComment();
47-
if ($docComment instanceof Doc && str_contains($docComment->getText(), '@template')) {
48-
return [];
49-
}
50-
5146
$returnName = $this->resolveSingleClassReturnName($node->returnType);
5247
if ($returnName === null) {
5348
return [];
@@ -59,7 +54,7 @@ public function processNode(Node $node, Scope $scope): array
5954
continue;
6055
}
6156

62-
// return type is one of the union members, not a broad shared parent - a generic does not apply
57+
// return type is one of the union members, not a broad shared parent - already narrow enough
6358
if (in_array($returnName, $paramNames, true)) {
6459
continue;
6560
}
@@ -77,9 +72,13 @@ public function processNode(Node $node, Scope $scope): array
7772
return end($parts);
7873
}, $paramNames);
7974

75+
if ($this->isNullableReturnType($node->returnType)) {
76+
$shortNames[] = 'null';
77+
}
78+
8079
return [
8180
RuleErrorBuilder::message(sprintf(self::ERROR_MESSAGE, $returnName, implode('|', $shortNames)))
82-
->identifier('rector.genericTemplateOverBroadReturn')
81+
->identifier('rector.explicitUnionReturnType')
8382
->line($node->getStartLine())
8483
->build(),
8584
];
@@ -104,9 +103,22 @@ private function methodReturnsVariable(ClassMethod $classMethod, string $variabl
104103
return $foundReturn instanceof Return_;
105104
}
106105

106+
private function isNullableReturnType(null|Identifier|Name|ComplexType $type): bool
107+
{
108+
if ($type instanceof NullableType) {
109+
return true;
110+
}
111+
112+
if (! $type instanceof UnionType) {
113+
return false;
114+
}
115+
116+
return array_any($type->types, fn(Identifier|Name|IntersectionType $memberType): bool => $memberType instanceof Identifier && $memberType->toLowerString() === 'null');
117+
}
118+
107119
/**
108120
* Returns the single class return type name (nullable allowed), or null when the return type is
109-
* missing, scalar, or a union of 2+ class types - the latter is covered by the same-union rule.
121+
* missing, scalar, or a union of 2+ class types - the latter is already an explicit union.
110122
*/
111123
private function resolveSingleClassReturnName(null|Identifier|Name|ComplexType $type): ?string
112124
{
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Rector\Utils\PHPStan\Tests\Rule\NarrowReturnToUnionParamRule;
6+
7+
use PHPStan\Rules\Rule;
8+
use PHPStan\Testing\RuleTestCase;
9+
use Rector\Utils\PHPStan\Rule\NarrowReturnToUnionParamRule;
10+
11+
/**
12+
* @extends RuleTestCase<NarrowReturnToUnionParamRule>
13+
*/
14+
final class NarrowReturnToUnionParamRuleTest extends RuleTestCase
15+
{
16+
public function testBroadReturnOfUnionParam(): void
17+
{
18+
$expectedErrorMessage = 'Return type "PhpParser\Node" is too broad for a returned union param. Declare the explicit union return type "MethodCall|New_|null" instead.';
19+
20+
$this->analyse([__DIR__ . '/Source/BroadReturnOfUnionParam.php'], [[$expectedErrorMessage, 13]]);
21+
}
22+
23+
public function testSkip(): void
24+
{
25+
$this->analyse([__DIR__ . '/Source/SkipBroadReturn.php'], []);
26+
}
27+
28+
protected function getRule(): Rule
29+
{
30+
return new NarrowReturnToUnionParamRule();
31+
}
32+
}

utils/phpstan/tests/Rule/PreferGenericTemplateOnReturnedUnionParamRule/Source/BroadReturnOfUnionParam.php renamed to utils/phpstan/tests/Rule/NarrowReturnToUnionParamRule/Source/BroadReturnOfUnionParam.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
declare(strict_types=1);
44

5-
namespace Rector\Utils\PHPStan\Tests\Rule\PreferGenericTemplateOnReturnedUnionParamRule\Source;
5+
namespace Rector\Utils\PHPStan\Tests\Rule\NarrowReturnToUnionParamRule\Source;
66

77
use PhpParser\Node;
88
use PhpParser\Node\Expr\MethodCall;

utils/phpstan/tests/Rule/PreferGenericTemplateOnReturnedUnionParamRule/Source/SkipBroadReturn.php renamed to utils/phpstan/tests/Rule/NarrowReturnToUnionParamRule/Source/SkipBroadReturn.php

Lines changed: 2 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
declare(strict_types=1);
44

5-
namespace Rector\Utils\PHPStan\Tests\Rule\PreferGenericTemplateOnReturnedUnionParamRule\Source;
5+
namespace Rector\Utils\PHPStan\Tests\Rule\NarrowReturnToUnionParamRule\Source;
66

77
use PhpParser\Node;
88
use PhpParser\Node\Expr\ArrayDimFetch;
@@ -12,16 +12,6 @@
1212

1313
final class SkipBroadReturn
1414
{
15-
/**
16-
* @template TNode of New_|MethodCall
17-
* @param TNode $node
18-
* @return TNode
19-
*/
20-
public function alreadyGeneric(New_|MethodCall $node): Node
21-
{
22-
return $node;
23-
}
24-
2515
public function doesNotReturnParam(New_|MethodCall $node): ?Node
2616
{
2717
if ($node instanceof New_) {
@@ -41,7 +31,7 @@ public function singleClassParam(New_ $node): ?Node
4131
return $node;
4232
}
4333

44-
public function unionReturn(New_|MethodCall $node): New_|MethodCall|null
34+
public function alreadyExplicitUnionReturn(New_|MethodCall $node): New_|MethodCall|null
4535
{
4636
return $node;
4737
}

‎utils/phpstan/tests/Rule/PreferGenericTemplateOnReturnedUnionParamRule/PreferGenericTemplateOnReturnedUnionParamRuleTest.php‎

Lines changed: 0 additions & 32 deletions
This file was deleted.

0 commit comments

Comments
 (0)