Skip to content

Narrow getName() and $name instead of invariant self<T&BackedEnum> in the PHP 8.4+ ReflectionEnum::isBacked() stub - #7109

Open
phpstan-bot wants to merge 4 commits into
phpstan:2.3.xfrom
phpstan-bot:create-pull-request/patch-09th3ho
Open

phpstan-bot wants to merge 4 commits into
phpstan:2.3.xfrom
phpstan-bot:create-pull-request/patch-09th3ho

Conversation

@phpstan-bot

Copy link
Copy Markdown
Collaborator

Summary

On PHP 8.4+, ReflectionEnum<T of UnitEnum>::isBacked() was reported as "will always evaluate to false", and $enum became *NEVER* inside if ($enum->isBacked()). This change replaces the PHP 8.4+ stub's self<T&BackedEnum> $this assertion with assertions on the enum's class name, which work even though T is invariant.

Changes

  • stubs/ReflectionEnumWithLazyObjects.stub: replaced @phpstan-assert-if-true self<T&BackedEnum> $this with @phpstan-assert-if-true class-string<T&BackedEnum> $this->name and ... $this->getName(). The !null $this->getBackingType() assertion is unchanged.
  • tests/PHPStan/Analyser/NodeScopeResolverTest.php, tests/PHPStan/Analyser/data/enum-reflection-backed.php: this test, which checks that getName() narrows to class-string<BackedEnum>, now also runs on PHP 8.4+. It had been limited to PHP < 8.4 because of this problem.
  • Checked the other stubs: none use a self<...> $this assertion on an invariant template. The PHP < 8.4 stub (ReflectionEnum.stub) keeps self<T&BackedEnum> because its T is @template-covariant, so the intersection works there.

Root cause

On PHP 8.4+ the lazy-objects ReflectionClass stub needs an invariant T, so ReflectionEnumWithLazyObjects.stub is invariant too. Narrowing $this from ReflectionEnum<T> to ReflectionEnum<T&BackedEnum> is an intersection of two invariant generic types with different type arguments. That intersection is never, so the impossible-check rule reported the call as always false. Asserting on class-string<T&BackedEnum> for $this->name and $this->getName() keeps the useful narrowing without depending on the variance of T. For a concrete unit enum (ReflectionEnum<UnitFoo>) it still resolves to never, so that case is still correctly reported as always false.

Test

  • tests/PHPStan/Rules/Comparison/data/bug-15165.php + ImpossibleCheckTypeMethodCallRuleTest::testBug15165: the reproducer from the issue (no errors expected for the template cases), plus concrete enums. ReflectionEnum<UnitFoo>::isBacked() is still reported and the backed one is not.
  • tests/PHPStan/Analyser/nsrt/bug-15165.php (PHP 8.4+): getName(), ->name and getBackingType() narrow after isBacked(), and a templated ReflectionEnum<T> stays as it is instead of becoming never.
  • Both tests fail without the stub change.

Fixes phpstan/phpstan#15165

…m>` in the PHP 8.4+ `ReflectionEnum::isBacked()` stub

- On PHP 8.4+ `ReflectionEnumWithLazyObjects.stub` declares `T` invariant (it has to,
  because the lazy-object `ReflectionClass<T>` parent is invariant). The
  `@phpstan-assert-if-true self<T&BackedEnum> $this` assertion intersected
  `ReflectionEnum<T>` with `ReflectionEnum<T&BackedEnum>`. Under invariance that is
  always `never`, so every `isBacked()` call on a non-concrete enum was reported
  as always false, and `$this` became `*NEVER*` in the truthy branch.
- Replace it with `class-string<T&BackedEnum>` assertions on `$this->name` and
  `$this->getName()`. These narrow the class name without depending on the variance
  of `T`. Calls on a concrete unit enum (`ReflectionEnum<UnitFoo>`) are still
  reported as always false.
- Enable `enum-reflection-backed.php` on PHP 8.4+ again. It was limited to < 8.4
  because of this problem.
- Checked the other stubs: none use a `self<...> $this` assertion on an
  invariant template.

@VincentLanglet VincentLanglet left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does a check on isBacked still narrow getCases and getCase ?

… stub

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@phpstan-bot

Copy link
Copy Markdown
Collaborator Author

getCases() is narrowed again after isBacked() on PHP 8.4+, but getCase($name) isn't. Before this PR neither one worked there: $this became never, so both resolved to *ERROR*.

What I changed: I added @phpstan-assert-if-true array<ReflectionEnumBackedCase> $this->getCases() to stubs/ReflectionEnumWithLazyObjects.stub. Inside if ($r->isBacked()), getCases() is now array<ReflectionEnumBackedCase>, for both ReflectionEnum<UnitEnum> and a templated ReflectionEnum<T of UnitEnum>. I added assertions for this to tests/PHPStan/Analyser/nsrt/bug-15165.php. They fail without the stub change (they get array<ReflectionEnumUnitCase>) and pass with it. make tests and make phpstan both pass. This is committed separately and not pushed.

What still doesn't work: getCase($name) stays ReflectionEnumUnitCase after isBacked(). An assertion only applies to the exact expression it names, arguments included. I tried @phpstan-assert-if-true ReflectionEnumBackedCase $this->getCase() and it had no effect on $r->getCase($n). The return type of getCase() depends on T is BackedEnum, and with T invariant, T itself can't be narrowed. Two ways to fix it fully:

  • a dynamic return type extension for ReflectionEnum::getCase() that checks whether getBackingType() has been narrowed to non-null in the current scope;
  • teaching TypeCombinator::intersect() that intersecting C<T> and C<T&X> for an invariant T can give C<T&X>. That is a broader type-system change.

I'd leave either for a follow-up unless you want it in this PR. The PHP < 8.4 stub is unchanged; it narrows $this itself (its T is covariant), so both methods already narrow there.

@VincentLanglet VincentLanglet left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tests fails between 8.1 and 8.3

…on PHP < 8.4

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@phpstan-bot

Copy link
Copy Markdown
Collaborator Author

I've fixed the test that failed on PHP 8.1–8.3. Only ImpossibleCheckTypeMethodCallRuleTest::testBug15165 was failing, and the only difference was the tip on the error.

What went wrong: on PHP < 8.4 PHPStan uses the older ReflectionEnum.stub, which this PR doesn't change. There, the "ReflectionEnum<Bug15165\UnitFoo>::isBacked() will always evaluate to false" error at line 58 comes without the "Because the type is coming from a PHPDoc…" tip. The test expected the tip on every version, but only the PHP 8.4+ stub adds it. The error message itself and the line were the same everywhere.

Fix: the test now expects the tip only on PHP 8.4+ and no tip on older versions (PHP_VERSION_ID >= 80400 ? '…' : null). It's in a separate commit, which isn't pushed.

Testing:

  • This machine only has PHP 8.4, so I ran PHP 8.3 in Docker. ImpossibleCheckTypeMethodCallRuleTest and NodeScopeResolverTest both pass there. That includes enum-reflection-backed.php, which this PR now also runs on 8.1+.
  • I couldn't run PHP 8.1: this PHPUnit version needs PHP 8.2 or newer. 8.1 and 8.2 use the same older stub as 8.3, so they should behave the same, but CI will be the first real check there.
  • On PHP 8.4, make tests and make phpstan both pass.

@VincentLanglet VincentLanglet left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why the tips is only added on PHP 8.4+ ?

@phpstan-bot

Copy link
Copy Markdown
Collaborator Author

The tip shows up only on PHP 8.4+ because the two versions use different stubs. On PHP 8.4+ the call is "always false" only because of PHPDoc types. On PHP < 8.4 a quirk in how assertions are resolved makes the native-types check give the same verdict. I didn't change any code because nothing needed fixing, so there are no commits for this review.

How the tip is decided. In ImpossibleCheckTypeMethodCallRule, the tip is added only when a second check that uses native types alone can't decide the outcome. If native types alone also say "always false", there's no tip.

In testConcrete(), $unit = new ReflectionEnum(UnitFoo::class) has the PHPDoc type ReflectionEnum<UnitFoo> but the native type ReflectionEnum<UnitEnum>, on both 8.3 and 8.4. So UnitFoo can't be backed only according to the PHPDoc type.

PHP 8.4+ (ReflectionEnumWithLazyObjects.stub, changed in this PR). The assertions now target $this->name, $this->getName(), $this->getCases() and $this->getBackingType(). In the native-only check, those are string, string, array and ?ReflectionNamedType. Each of them could still match its assertion. For example, a string could be a class-string<UnitFoo&BackedEnum>, so the answer is "maybe".

  • I removed all but one assertion at a time, with treatPhpDocTypesAsCertain: false. No version of the stub reported the error.
  • So the error comes only from PHPDoc types, and the tip is correct.

PHP < 8.4 (ReflectionEnum.stub, unchanged). The assertion is self<T&BackedEnum> $this, so it applies to $unit itself. MethodCallHandler::specifyTypes() resolves T from the PHPDoc type even during the native-only check (see the comment around line 547). That's on purpose: an assertion is a PHPDoc claim either way.

  • So even in the native-only check, the assertion becomes ReflectionEnum<UnitFoo&BackedEnum>, which is ReflectionEnum<never>.
  • No ReflectionEnum<UnitEnum> can match that, so the native-only check also says "always false" and no tip is added.
  • I confirmed this on PHP 8.3 in Docker: the error is still reported with treatPhpDocTypesAsCertain: false.

On both versions the only evidence that UnitFoo isn't backed is the PHPDoc-inferred T, so the tip is arguably correct on all versions. On PHP < 8.4 it's missing because the asserted type borrows T from the PHPDoc type. That's existing behaviour and this PR doesn't change it. Adding the tip there would mean changing how assertions on $this are resolved in the native-only check. That's a broader change, and I'd rather leave it out of this PR. The test therefore expects the tip only on PHP 8.4+, which matches what each stub actually does.

assertType('ReflectionNamedType|null', $r->getBackingType());
assertType('array<ReflectionEnumUnitCase>', $r->getCases());
if ($r->isBacked()) {
assertType('array<ReflectionEnumBackedCase>', $r->getCases());

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we should in addition assert the type for $r->getCase(), before and after $r->isBacked()

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added the getCase() assertions to the test, before and after isBacked(). To make the "after" case come out right, I also added a small extension so getCase() now actually narrows. Both are in one local commit, not pushed. make tests and make phpstan both pass.

Tests (tests/PHPStan/Analyser/nsrt/bug-15165.php):

  • ReflectionEnum<UnitEnum>: getCase('A') is ReflectionEnumUnitCase before isBacked() and ReflectionEnumBackedCase inside if ($r->isBacked()).
  • Templated ReflectionEnum<T of UnitEnum>: the same two types, before and after.

The extension: before this, getCase() stayed ReflectionEnumUnitCase after isBacked(), so the "after" check would only have recorded a wrong result. A docblock assertion can't fix this, because it doesn't apply to getCase($name) calls that pass an argument. So I added src/Type/Php/ReflectionEnumGetCaseDynamicReturnTypeExtension.php. When the current scope already knows that getBackingType() on the same enum isn't null (which is what isBacked() returning true tells it), getCase() returns ReflectionEnumBackedCase. Otherwise it changes nothing. The new "after isBacked()" checks fail without the extension (they get ReflectionEnumUnitCase) and pass with it.

The extension also runs on PHP < 8.4. There the older stub already narrows getCase(), and the extension gives the same answer, so nothing should change. I only ran the tests on PHP 8.4, though, and the new test file only runs on 8.4+, so CI will be the first check on 8.1–8.3.

If you'd rather keep the extension out of this PR, I can drop it and only assert the current type, ReflectionEnumUnitCase.

…Backed()

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

ReflectionEnum::isBacked() incorrectly reported as always returning false

3 participants