Erase generic type arguments when comparing a class-string against a constant class-string

[phpstan-bot]

Summary

A union of parameterized class-string types was not narrowed after a class name was excluded with !==: class-string<X<int>>|class-string<Y<int>> stayed unchanged instead of narrowing to class-string<Y<int>>, while the equivalent union of raw class-string<X>|class-string<Y> narrowed correctly. Star-projected class-string<X<*>> was affected the same way.

The fix erases generic type arguments before a class-string is compared against a constant class-string, because a class-string value only ever carries a class name.

Changes

• src/Type/Generic/GenericClassStringType.php
  • New @internal static isValueOfGenericType(Type $genericType, string $className): IsSuperTypeOfResult holding the "can a class named $className be the value behind class-string<$genericType>" check that was previously duplicated in two places.
  • New private eraseTypeArguments() which maps every GenericObjectType inside the generic type to its unparameterized ObjectType counterpart (keeping the subtracted type) via TypeTraverser.
  • isSuperTypeOf() now delegates its ConstantStringType branch to the new helper.
• src/Type/Constant/ConstantStringType.php
  • The GenericClassStringType branch of isSuperTypeOf() delegates to the same helper instead of repeating the StaticType/TemplateType/ObjectType dance.

Analogous cases that were broken by the same root cause and are fixed by this change (each covered by a new assertion):

• star projections — class-string<X<*>>|class-string<Y<*>>
• a union nested inside one class-string — class-string<X<int>|Y<int>>
• === narrowing, which used to produce a stray 'X'&class-string<X<int>> intersection instead of 'X'
• switch / default arm narrowing
• in_array($class, [X::class], true) narrowing
• match exhaustiveness: "Match expression does not handle remaining values" false positive
• constant-array offset access keyed by class names: $map[$class] reported "Offset ... does not exist" and produced *ERROR*, now 1|2 and "might not exist" (same as for raw class-string<X>)
• TypeCombinator::union() now absorbs 'X' into class-string<X<int>>
• class-string<X<int>>&literal-string now subtracts to *NEVER* like its raw counterpart

Probed and found already correct, so no change and no test kept: GenericClassStringType::accepts() (an accepts context already treats an unparameterized class name as compatible with any parameterization), is_a() / is_subclass_of() narrowing, instanceof $class, and template type inference from X::class.

Root cause

ConstantStringType::isSuperTypeOf() and GenericClassStringType::isSuperTypeOf() both answered "is C::class a possible value of class-string<G>?" by turning the constant into new ObjectType(C) and requiring G->isSuperTypeOf(ObjectType(C)) to be a definite Yes. The Yes requirement is deliberate — it filters out the uncertainty that ObjectType(C) could really be a subclass of C.

But when G is parameterized, GenericObjectType::isSuperTypeOf() can never return Yes for an unparameterized ObjectType(C): it looks up C's ancestor with the same class name, finds a plain ObjectType, and downgrades the result to Maybe because the type arguments are unknown. So the check collapsed to No, TypeCombinator::remove() bailed out at its isSuperType->no() early return and never reached GenericClassStringType::tryRemove(), and no narrowing happened.

A class-string value is just a class name and cannot carry type arguments, so that particular uncertainty must not count against the match. The fix erases the type arguments from the generic type before the comparison, which makes class-string<X<int>> and class-string<X<*>> behave exactly like class-string<X> in this comparison. Erasure — rather than switching to an accepts context — is what keeps the existing precision for subtracted object types such as class-string<Type~(ConstantIntegerType|IntegerRangeType)>, where the Maybe genuinely comes from the subtraction and not from type arguments.

Test

• tests/PHPStan/Analyser/nsrt/bug-15266.php — the playground reproducer verbatim (parameterized, star-projected and raw unions), plus one function per analogous case listed above. All 11 new assertions fail without the source change.
• tests/PHPStan/Rules/Comparison/data/bug-15266.php and MatchExpressionRuleTest::testBug15266() — a match over a parameterized/star-projected class-string union is expected to report nothing; without the fix it reports "Match expression does not handle remaining values" twice.

Fixes phpstan/phpstan#15266
Fixes phpstan/phpstan#10498

[staabm]

lgtm - issue bot reports more stuff,.. not sure its related or an outdated result list

[VincentLanglet]

Add non regression test for

• phpstan/phpstan#10498

[VincentLanglet]

Fix the parity in the Turbo extension files .cpp

[phpstan-bot]

Done. The review asked for turbo-ext parity, and both classes this PR touched (ConstantStringType, GenericClassStringType) are #[ShadowedByTurboExtension] — with the extension loaded, the fix had no effect because the native mirrors still ran the old comparison.

740aaebd5 — Mirror the class-string type argument erasure in the native Type classes

• turbo-ext/src/GenericClassStringType.cpp — native static isValueOfGenericType(), registered under the twin's generated signature so a self:: call from PHP reaches it. The erasure is a stateless native TypeTraverser::map() callback: a GenericObjectType becomes the ObjectType of the class it names, keeping the subtracted type (slot reads when the object is exactly the native class, getClassName()/getSubtractedType() otherwise, since a subclass may override them). isSuperTypeOf() delegates to it.
• turbo-ext/src/ConstantStringType.cpp — its GenericClassStringType branch reaches the same body via the new pt_generic_class_string_is_value_of_generic_type() entry point declared in TypeTraits.h.
• turbo-ext/src/generated/GenericClassStringType.h — regenerated for the new method.
• turbo-ext/tests/type-family.php — differential coverage: isValueOfGenericType() directly over an object / parameterized / star-projected / subtracted / union generic type, a StaticType and a TemplateType; plus parameterized, star-projected, bare and union class-strings as string-family subjects and comparison targets.

One deliberate deviation from the twin's statement order: the ObjectType of the compared class name is built before the traversal. PHP takes $className by value; the native borrows it from a property slot that the intervening calls must not outlive. Nothing observable depends on the order — the constructor only stores the name.

18003c71c — Bump expected turbo version (make bump-turbo, 3ff623f → 740aaeb).

Verification: strict build clean under the CI warning set; smoke.php ALL OK; side-by-side.php method parity clean; signature-parity.php OK (14059 methods); make tests 22171 tests / 97813 assertions OK; the same suite with the extension loaded gives identical counts; make phpstan no errors; analysis output over src/Type/Generic, src/Type/Constant and the reproducer is byte-identical with the extension on and off; and the issue's narrowing (class-string<X<int>>|class-string<Y<int>> minus X::class → class-string<Y<int>>) is identical either way.

Two things I could not run here:

• make lint-turbo pins clang-tidy 21; only 18 is installed on this machine and the target refuses a mismatched major. CI covers it.
• side-by-side.php reports 52 generated headers as stale, all pre-existing and untouched by this PR — this machine's PHP emits self where the committed headers carry resolved class names, so I regenerated and kept only GenericClassStringType.h (whose added lines use fully-qualified names and are identical under either PHP).