Skip to content

Commit 486821c

Browse files
SanderMullerclaude
authored andcommitted
Respect @api on class constants and traits in the API rules
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
1 parent cc9fa5b commit 486821c

7 files changed

Lines changed: 62 additions & 3 deletions

File tree

‎src/Rules/Api/ApiClassConstFetchRule.php‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
use PhpParser\Node;
66
use PHPStan\Analyser\Scope;
77
use PHPStan\DependencyInjection\RegisteredRule;
8+
use PHPStan\Reflection\ClassConstantReflection;
89
use PHPStan\Reflection\ReflectionProvider;
910
use PHPStan\Rules\Rule;
1011
use PHPStan\Rules\RuleErrorBuilder;
@@ -60,6 +61,12 @@ public function processNode(Node $node, Scope $scope): array
6061
'https://github.com/phpstan/phpstan/discussions',
6162
))->build();
6263

64+
if ($node->name->toLowerString() !== 'class' && $classReflection->hasConstant($node->name->toString())) {
65+
if ($this->isConstantCovered($classReflection->getConstant($node->name->toString()))) {
66+
return [];
67+
}
68+
}
69+
6370
$docBlock = $classReflection->getResolvedPhpDoc();
6471
if ($docBlock !== null) {
6572
foreach ($docBlock->getPhpDocNodes() as $phpDocNode) {
@@ -88,4 +95,24 @@ public function processNode(Node $node, Scope $scope): array
8895
return [$ruleError];
8996
}
9097

98+
private function isConstantCovered(ClassConstantReflection $constantReflection): bool
99+
{
100+
$classDocBlock = $constantReflection->getDeclaringClass()->getResolvedPhpDoc();
101+
if ($classDocBlock !== null) {
102+
foreach ($classDocBlock->getPhpDocNodes() as $phpDocNode) {
103+
$apiTags = $phpDocNode->getTagsByName('@api');
104+
if (count($apiTags) > 0) {
105+
return true;
106+
}
107+
}
108+
}
109+
110+
$constantDocComment = $constantReflection->getDocComment();
111+
if ($constantDocComment === null) {
112+
return false;
113+
}
114+
115+
return str_contains($constantDocComment, '@api');
116+
}
117+
91118
}

‎src/Rules/Api/ApiTraitUseRule.php‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
use PHPStan\Reflection\ReflectionProvider;
99
use PHPStan\Rules\Rule;
1010
use PHPStan\Rules\RuleErrorBuilder;
11+
use function count;
1112
use function sprintf;
1213

1314
/**
@@ -47,6 +48,15 @@ public function processNode(Node $node, Scope $scope): array
4748
continue;
4849
}
4950

51+
$docBlock = $traitReflection->getResolvedPhpDoc();
52+
if ($docBlock !== null) {
53+
foreach ($docBlock->getPhpDocNodes() as $phpDocNode) {
54+
if (count($phpDocNode->getTagsByName('@api')) > 0) {
55+
continue 2;
56+
}
57+
}
58+
}
59+
5060
$errors[] = RuleErrorBuilder::message(sprintf(
5161
'Using %s is not covered by backward compatibility promise. The trait might change in a minor PHPStan version.',
5262
$traitReflection->getDisplayName(),

‎src/Type/Traits/LateResolvableTypeTrait.php‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
use PHPStan\Type\NeverType;
2323
use PHPStan\Type\Type;
2424

25+
/** @api */
2526
trait LateResolvableTypeTrait
2627
{
2728

‎tests/PHPStan/Rules/Api/ApiClassConstFetchRuleTest.php‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,12 +32,17 @@ public function testRuleOutOfPhpStan(): void
3232
$this->analyse([__DIR__ . '/data/class-const-fetch-out-of-phpstan.php'], [
3333
[
3434
'Accessing PHPStan\Command\AnalyseCommand::class is not covered by backward compatibility promise. The class might change in a minor PHPStan version.',
35-
16,
35+
19,
3636
$tip,
3737
],
3838
[
3939
'Accessing PHPStan\Analyser\NodeScopeResolver::FOO is not covered by backward compatibility promise. The class might change in a minor PHPStan version.',
40-
20,
40+
23,
41+
$tip,
42+
],
43+
[
44+
'Accessing PHPStan\Turbo\TurboExtensionSelector::MINIMUM_PHP_VERSION_ID is not covered by backward compatibility promise. The class might change in a minor PHPStan version.',
45+
28,
4146
$tip,
4247
],
4348
]);

‎tests/PHPStan/Rules/Api/ApiTraitUseRuleTest.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ public function testRuleOutOfPhpStan(): void
3232
$this->analyse([__DIR__ . '/data/trait-use-out-of-phpstan.php'], [
3333
[
3434
'Using PHPStan\Type\JustNullableTypeTrait is not covered by backward compatibility promise. The trait might change in a minor PHPStan version.',
35-
15,
35+
16,
3636
$tip,
3737
],
3838
]);

‎tests/PHPStan/Rules/Api/data/class-const-fetch-out-of-phpstan.php‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,13 @@
22

33
namespace App\ClassConstFetch;
44

5+
use PHPStan\Analyser\MutatingScope;
56
use PHPStan\Analyser\NodeScopeResolver;
7+
use PHPStan\Analyser\Scope;
68
use PHPStan\Analyser\ScopeFactory;
79
use PHPStan\Command\AnalyseCommand;
810
use PHPStan\Reflection\ClassReflection;
11+
use PHPStan\Turbo\TurboExtensionSelector;
912

1013
class Foo
1114
{
@@ -18,6 +21,11 @@ public function doFoo()
1821
echo ScopeFactory::class;
1922

2023
echo NodeScopeResolver::FOO;
24+
25+
echo Scope::SUPERGLOBAL_VARIABLES;
26+
echo MutatingScope::SUPERGLOBAL_VARIABLES;
27+
echo TurboExtensionSelector::EXTENSION_PATH_INI;
28+
echo TurboExtensionSelector::MINIMUM_PHP_VERSION_ID;
2129
}
2230

2331
}

‎tests/PHPStan/Rules/Api/data/trait-use-out-of-phpstan.php‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
namespace App\TraitUse;
44

55
use PHPStan\Type\JustNullableTypeTrait;
6+
use PHPStan\Type\Traits\LateResolvableTypeTrait;
67

78
trait FooTrait
89
{
@@ -16,3 +17,10 @@ class Foo
1617
use FooTrait;
1718

1819
}
20+
21+
class Bar
22+
{
23+
24+
use LateResolvableTypeTrait;
25+
26+
}

0 commit comments

Comments
 (0)