UsedNamesRule: reset imported names at every namespace declaration instead of keying them by namespace name

[phpstan-bot]

Summary

A namespace declaration starts a brand new import scope in PHP, even when the namespace name was already declared earlier in the same file (3v4l). UsedNamesRule instead accumulated every use alias it had ever seen into one list per namespace name, valid for the whole file. Repeating a namespace declaration therefore produced false positives:

<?php

namespace X;

use stdClass;

namespace X;

use stdClass; // Cannot use stdClass as stdClass because the name is already in use.

The rule now tracks imports per namespace declaration, while still tracking class-like declarations for the whole file so that genuine redeclarations keep being reported.

Changes

• src/Rules/Names/UsedNamesRule.php
  • processNode() starts a fresh $namespaceScopeNames list for every Namespace_ node (and keeps one $fileScopeNames list for files whose statements are not wrapped in a namespace declaration).
  • The single $usedNames map keyed by lowercased namespace name is replaced by two structures: $currentScopeNames — names taken in the namespace declaration currently being walked (its imports plus its class-like declarations) — and $declaredNames — class-like names declared anywhere in the file, grouped by namespace.
  • findErrorsInUses() checks an alias only against $currentScopeNames, so imports no longer leak between namespace declarations. It no longer needs the namespace at all.
  • The ClassLike branch checks against $currentScopeNames or $declaredNames[$namespace], and records the name in both, so a class-like still conflicts with an import in the same declaration and with a class-like declared in any earlier block of the same namespace.
• tests/PHPStan/Rules/Names/UsedNamesRuleTest.php, tests/PHPStan/Rules/Names/data/repeated-namespaces.php, tests/PHPStan/Rules/Names/data/repeated-braced-namespaces.php — new regression tests.
• build/collision-detector.json — the two new fixtures intentionally declare the same class twice, like the existing multiple-namespaces.php and no-namespace.php fixtures.

Analogous cases

Every construct on the "names imported into a namespace" axis was checked against real PHP behaviour (php -l / running the file) and against PHPStan before and after the change:

Case	PHP	PHPStan before	PHPStan after
use A\Foo; … namespace X; … use B\Foo;	ok	❌ error	✅ ok
group use repeated across declarations	ok	❌ error	✅ ok
aliased use ... as Y repeated across declarations	ok	❌ error	✅ ok
class Foo {} … namespace X; … use A\Foo;	ok	❌ error	✅ ok
use A\Foo; … namespace X; … class Foo {}	ok	❌ error	✅ ok
use A\Foo; + class Foo {} in the same declaration	fatal	✅ error	✅ error
class Foo {} + use A\Foo; in the same declaration	fatal	✅ error	✅ error
class Foo {} in two namespace X; declarations	fatal	✅ error	✅ error
braced namespace X { } namespace X { } — all of the above	—	❌ same false positives	✅ matches PHP
namespace X; … namespace Y; … namespace X;	ok	❌ error	✅ ok

The other places in the codebase that accumulate imports while walking a file were probed and are already correct, so no change was needed there:

• src/Dependency/ExportedNameScopeTracker.php — clears uses/constUses when entering a Namespace_ node, which is exactly the per-declaration semantics.
• src/Parser/UseAliasVisitor.php — clears explicitAliases when entering a Namespace_ node; verified that an alias in one declaration no longer suppresses the incorrect-case error in a later declaration.
• php-parser's NameContext (driven by NameResolver in RichParser/SimpleParser/StubParser) already resets aliases per declaration and already reports duplicate imports — including use function and use const, which UsedNamesRule deliberately ignores — so those are correct too.
• Name resolution of PHPDoc types inside classes, methods, functions and properties was verified to use the right namespace in a repeated namespace X; block.

One related pre-existing limitation was found and left alone: FileTypeMapper::getNameScopeKey() derives a single file-level key (md5($file)) for statements that are neither in a class nor in a function, so a /** @var */ or /** @throws */ on a top-level statement in the second namespace block of a file gets the first block's name scope. That is not specific to imports — the namespace itself is wrong too, even when the two blocks declare different namespaces — and fixing it needs a way for callers of the @api method FileTypeMapper::getResolvedPhpDoc() to say which namespace declaration a doc block belongs to, which is out of scope here.

Root cause

UsedNamesRule modelled the import scope as "the file, partitioned by namespace name". PHP models it as "one namespace declaration", i.e. the compiler resets FC(imports) and the seen-symbol table every time it compiles a namespace statement, whether or not the name repeats. Because the rule's $usedNames was keyed by strtolower($namespace) and never cleared, both directions of the "name already in use" check leaked across declaration boundaries: an alias imported in one block made a later import or class declaration of the same name look like a conflict, and a class declared in one block made a later import look like a conflict.

The fix separates the two lifetimes that were conflated in $usedNames: imports and same-block declarations live for one namespace declaration, while class-like declarations additionally live for the whole file (a file cannot declare X\Foo twice regardless of how its namespace declarations are arranged — PHP fatals at runtime with Cannot redeclare class X\Foo).

Test

• UsedNamesRuleTest::testRepeatedNamespaces() with data/repeated-namespaces.php — the reported unbraced shape, covering a repeated plain use, a repeated group use, a repeated aliased use, importing a name that was declared as a class in an earlier declaration, a class conflicting with an import in its own declaration (error, line 23), and a class conflicting with a class declared in an earlier declaration of the same namespace (error, line 29). Before the fix this file reported 7 errors; 5 of them were false positives.
• UsedNamesRuleTest::testRepeatedBracedNamespaces() with data/repeated-braced-namespaces.php — the same situations in the braced namespace X { } form, plus a trailing namespace { } block confirming the global namespace gets its own import scope. Before the fix this file reported 3 errors; 1 was a false positive.
• Both were confirmed to fail for the right reason with the rule change stashed, and the expected errors were cross-checked against what PHP itself accepts and rejects.
• Existing UsedNamesRuleTest cases (including multiple-namespaces.php, which relies on file-wide class redeclaration detection across braced blocks) still pass unchanged.
• Full make tests (21347 tests) and make phpstan are green.

Fixes phpstan/phpstan#15215

[ondrejmirtes]

The PR doesn't have the exact regression test for the failing code snippet from the issue.

[phpstan-bot]

Addressed the review: added the exact reproducer from the issue as a regression test.

tests/PHPStan/Rules/Names/data/bug-15215.php — verbatim from the playground link in the issue (fetched from the playground API, including the leading-backslash use \stdClass; form):

<?php

namespace X;

use \stdClass;

namespace X;

use \stdClass;

UsedNamesRuleTest::testBug15215() — expects no errors.

Verification:

• With src/Rules/Names/UsedNamesRule.php reverted to its pre-fix version, the test fails with exactly the error from the issue: 09: Cannot use stdClass as stdClass because the name is already in use.
• With the fix in place, it passes.
• make tests: 21349 tests, 96484 assertions, 97 skipped, OK.
• make phpstan: no errors.

Pushed as 72d3a5203 to create-pull-request/patch-69zky9r.