Skip class name case check for type hints using explicit use ... as aliases

[phpstan-bot]

Summary

When a class is imported with an explicit alias via use Foo\MyClass as myclass, PHPStan incorrectly reported "Class Foo\MyClass referenced with incorrect case: Foo\myclass" on type hints using the alias. The alias name is intentionally chosen by the user and should not trigger a case sensitivity error.

Changes

• Added src/Parser/UseAliasVisitor.php — a new parser visitor that:
  • Tracks explicit use ... as aliases (both regular and group use statements)
  • Marks resolved Name nodes with an isExplicitUseAlias attribute when the original name matches an explicit alias case-sensitively
  • Resets alias tracking on namespace boundaries
• Modified src/Rules/FunctionDefinitionCheck.php to check the isExplicitUseAlias attribute in getOriginalClassNamePairsFromTypeNode() and skip the case sensitivity check for explicit aliases

Root cause

FunctionDefinitionCheck::getOriginalClassNamePairsFromTypeNode() reconstructs the "original case" class name by combining the namespace prefix from the resolved name with the original name parts. For use Foo\MyClass as myclass, the original name myclass was combined with prefix Foo to produce Foo\myclass. Since strtolower('Foo\myclass') === strtolower('Foo\MyClass'), the existing alias detection (which only catches aliases with entirely different names) did not fire, and the name was incorrectly flagged as a case mismatch.

The fix distinguishes explicit use ... as aliases from wrong-case references by tracking which aliases were explicitly defined via the as keyword in use statements.

Analogous cases probed

The following contexts were tested and confirmed to NOT be affected (they pass the fully-resolved class name to ClassCaseSensitivityCheck, bypassing the problematic reconstruction logic):

• new expressions (InstantiationRule)
• instanceof expressions (ExistingClassInInstanceOfRule)
• catch clauses (CaughtExceptionExistenceRule)
• Class constant access (ClassConstantRule)
• Static property access (AccessStaticPropertiesCheck)
• Static method calls (StaticMethodCallCheck)
• Class extends/implements/trait use declarations
• Property type declarations (ExistingClassesInPropertiesRule)
• PHPDoc types (@param, @return)

Test

Added tests/PHPStan/Rules/Methods/data/bug-14617.php with a regression test covering:

• Function return type with explicit alias
• Class method parameter type with explicit alias
• Class method return type with explicit alias
• new expression with explicit alias (via InstantiationRule, verified no error)

Fixes phpstan/phpstan#14617

[VincentLanglet]

The condition

if (strtolower($originalCaseClassName) !== strtolower($resolvedName)) {
				// use alias, not just a case difference
				return [];
			}

should not be needed anymore

[phpstan-bot]

Done. Removed the redundant strtolower alias detection heuristic in FunctionDefinitionCheck.php. The UseAliasVisitor now handles all explicit use ... as alias detection precisely via the isExplicitUseAlias attribute, making the old lowercase-comparison check unnecessary. All tests (12,075) and static analysis pass.

[VincentLanglet]

Shouldn't the fix be in the ClassCaseSensitivityCheck which already has the incomplete check

if (strtolower($realClassName) !== strtolower($className)) {
				continue; // skip class alias
			}

[phpstan-bot]

Done. Moved the isExplicitUseAlias attribute check from FunctionDefinitionCheck::getOriginalClassNamePairsFromTypeNode() to ClassCaseSensitivityCheck::checkClassNames(), as the reviewer suggested. This centralizes the explicit alias handling in the same class that already has the incomplete strtolower alias skip — right where the "referenced with incorrect case" error is generated. All 12,075 tests pass and make phpstan reports no errors.

[VincentLanglet]

Add more test case which wasn't fixed by the previous fix in FunctionDefinitionCheck

[VincentLanglet]

Should/Could this if be removed too ?

[phpstan-bot]

Here's a summary of what was done to address the review:

The strtolower check cannot be removed. I verified this by temporarily removing it and running the full test suite — ExistingClassesInClosureTypehintsRuleTest::testExistingClassInTypehint fails because line 35 of closure-typehints.php uses \ReturnTypes\FooAliaS, which is a class_alias() for ReturnTypes\Foo. Without the strtolower check, PHPStan incorrectly reports "Class ReturnTypes\Foo referenced with incorrect case: ReturnTypes\FooAliaS" — a false positive because FooAliaS is a completely different name (a class_alias), not a case mismatch.

The UseAliasVisitor only tracks use ... as aliases in the parser. The strtolower check handles class_alias() scenarios where the reflection-resolved class name is entirely different from the written name.

Changes made:

• Clarified the comment on the strtolower check to explain it handles class_alias() specifically
• Added closure test coverage (bug-14617-closure.php + test in ExistingClassesInClosureTypehintsRuleTest)
• Added nullable and union type test cases to the existing bug-14617.php

All 12,076 tests pass and make phpstan reports no errors.

[phpstan-bot]

Done. Added test cases for explicit use ... as aliases in contexts that go through ClassCaseSensitivityCheck but not through FunctionDefinitionCheck:

• extends (ExistingClassInClassExtendsRuleTest)
• implements (ExistingClassesInClassImplementsRuleTest)
• instanceof (ExistingClassInInstanceOfRuleTest)
• property types (ExistingClassesInPropertiesRuleTest)

These contexts weren't covered by the previous strtolower heuristic in FunctionDefinitionCheck since they use separate rules. The shared test data file (tests/PHPStan/Rules/Classes/data/bug-14617.php) exercises all four cases with use Bug14617Classes\MyClass as myclass and use Bug14617Classes\MyInterface as myinterface. All 12,079 tests pass and make phpstan reports no errors.

[VincentLanglet]

Does it mean we don't avoid false positive with something like ?

class_alias('Foo', 'foo');

?

[VincentLanglet]

Do we already have test for the

if (strtolower($realClassName) !== strtolower($className)) {
				continue; // skip class_alias() where the alias is a completely different name
			}

case ?

[VincentLanglet]

Skip ExistingClassesInTypehintsRuleTest::testBug14617 for PHP < 8

[phpstan-bot]

Done. Added #[RequiresPhp('>= 8.0.0')] to ExistingClassesInTypehintsRuleTest::testBug14617 since the test data uses union types which require PHP 8.0+. All tests pass and make phpstan reports no errors.

[phpstan-bot]

All 12,081 tests pass (79,707 assertions). The commit has been pushed.

Summary: Added an explicit test (testClassAliasCaseSensitivity) that verifies the strtolower check in ClassCaseSensitivityCheck correctly skips class_alias() names that are completely different from the original class name. This was previously only implicitly covered by closure-typehints.php line 35. The strtolower check remains necessary for class_alias() scenarios (e.g., ReturnTypes\FooAlias → ReturnTypes\Foo) and cannot be removed.

[phpstan-bot]

The branch is already up to date with the remote — no new commits to push.

Summary: The reviewer asked whether class_alias('Foo', 'foo') avoids false positives. The answer is no — it's a pre-existing limitation that this PR neither introduces nor worsens. PHP's case-insensitive class resolution means (new ReflectionClass('foo'))->getName() returns 'Foo' identically whether class_alias('Foo', 'foo') was called or not, making it impossible to distinguish a case-only alias from a genuine case typo using PHP's reflection API. Fixing this would require tracking class_alias() calls explicitly (like the UseAliasVisitor does for use ... as), which is a separate concern.

[VincentLanglet]

Add back test case but just with

$callback = function (\ReturnTypes\FooAlias $a): \ReturnTypes\FooAlias {
	return $a;
};

and not the callback2

[phpstan-bot]

Done. Added back the class-alias-case-sensitivity.php test with only the correct-case FooAlias callback, omitting the wrong-case callback2 that locked in behavior the reviewer wants to keep open for future tightening. All 12,081 tests pass and make phpstan reports no errors.