Drop the memoized TypeCombinator results whenever the process-wide reflection provider, PHP version or feature toggles change

[phpstan-bot]

Summary

With the turbo extension active, class-level @method/@property PHPDoc and other type information could be silently wrong in worker processes: types resolved while PHPStan had a throwaway reflection provider installed were memoized by TypeCombinatorCache and then handed back to the real analysis, producing false method.notFound / staticMethod.notFound / property.notFound / class.notFound errors.

The memo only exists when the extension is active, which is why PHPSTAN_TURBO=0 and --debug (single process, and in phar installs the main process runs without the extension) were clean while parallel worker runs were not.

Changes

• src/DependencyInjection/ValidateIgnoredErrorsExtension.php — clear the memo in the finally that restores the process-wide accessors.
• src/Reflection/ReflectionProviderStaticAccessor.php — registerInstance() clears the memo.
• src/Reflection/PhpVersionStaticAccessor.php — registerInstance() clears the memo.
• src/DependencyInjection/BleedingEdgeToggle.php — setBleedingEdge() clears the memo; withBleedingEdge() routes both the set and the restore through it instead of assigning the static directly.
• src/DependencyInjection/ReportUnsafeArrayStringKeyCastingToggle.php — setLevel() clears the memo.
• Probed and found already correct: ContainerFactory::postInitializeContainer() (clears explicitly, deliberately last), StubValidator (re-runs postInitializeContainer() in its finally), BetterReflection::populate() (no caller outside postInitializeContainer()).

Root cause

TypeCombinator::union()/intersect()/remove() route through TypeCombinatorCache, which the turbo extension shadows with a memo keyed on a structural hash of the arguments. ContainerFactory::postInitializeContainer() already documents the invariant:

Type operations read global state — the toggles above, the reflection provider, the PHP version — so a memoized result is only valid for the state it was computed under.

ValidateIgnoredErrorsExtension::loadConfiguration() is the second place that mutates exactly that state. It registers a DummyReflectionProvider and a runtime PhpVersion, resolves the types named in the ignoreErrors patterns through TypeStringResolver/TypeNodeResolver (which performs unions and intersections), then restores the accessors and calls ObjectType::resetCaches() — the sibling cache with the same invalidation trigger — but never TypeCombinator::clearCache().

The DummyReflectionProvider knows no class hierarchy, so e.g. union(Exception, RuntimeException) does not collapse to Exception under it. That non-collapsing result stays in the memo under a key that the real analysis produces again, and is returned verbatim afterwards. Types the analysis then works with are wider or otherwise wrong, and members resolved through them go missing — the reported symptom class. Because the memo borrows its results, only entries whose result object is still referenced survive, which is why the failure looked intermittent and input-dependent.

The pattern is "global state that type operations read is mutated without invalidating the memo". Rather than fix the one call site, the invalidation now lives in each mutator of that state — the reflection provider accessor, the PHP version accessor, and the two feature toggles — so a future swap cannot reintroduce it. The explicit clear stays in ValidateIgnoredErrorsExtension because when it runs for the first container of a process there is no original accessor instance to restore, and the restores are skipped.

Test

tests/PHPStan/Type/GlobalStateCacheInvalidationTest.php performs the same swap/restore sequence the extension does: it registers a DummyReflectionProvider, memoizes union(Exception, RuntimeException) under it while retaining the result (the memo tombstones entries whose result died, so an unretained one cannot leak), restores the real provider and asserts the union collapses to Exception again. Before the fix the assertion sees Exception|RuntimeException; the test is a no-op without the extension, which is exactly the mode in which the bug does not exist.

Verified with the extension loaded through php.ini: make tests (17798 tests) and make phpstan green with and without PHPSTAN_TURBO=0, on glibc/PHP 8.4 and on Alpine/musl/PHP 8.3 with a locally built phpstan_turbo.so; turbo-ext/bin/side-by-side.php, smoke.php, signature-parity.php, arena-smoke.php and parser-corpus.php all pass.

Fixes phpstan/phpstan#15037

[ondrejmirtes]

1. So what was the order of events that lead to wrong TypeCombinator results? And why only in turbo mode?
2. E2E test in e2e-tests.yml (+ probably ran with turbo extension in the same workflow as make tests and make phpstan run after Turbo is compiled) would be better than this PHPUnit test.
3. Would be nicer to clear the cache in postInitializeContainer.

[phpstan-bot]

Pushed as 1870b3715.

1) The order of events — there isn't one. The premise was wrong.

I built phpstan_turbo.so locally (1ecf6e0, glibc/PHP 8.4) and loaded it through php.ini so the workers inherit it — phpstan diagnose confirms Turbo extension: enabled / Turbo worker binary: loaded via php.ini, workers inherit it. Then I ran the issue's reproducer with the patch reverted, as a single file and fanned out to 60 files so the run actually goes parallel:

[OK] No errors                     # single file
Found 1 error                      # 60 files — only the deliberately-unmatched ignoreErrors pattern

No method.notFound / staticMethod.notFound either way. The reason is the sequence in ContainerFactory::create():

$container = $configurator->createContainer()->getByType(Container::class);   // ← compiles: ValidateIgnoredErrorsExtension runs here
$this->validateParameters(...);
self::postInitializeContainer($container);                                    // ← ends with TypeCombinator::clearCache()

ValidateIgnoredErrorsExtension::loadConfiguration() is a compiler extension — it only ever runs while the container is being compiled, and postInitializeContainer() is the next thing create() does. I traced both to be sure:

TRACE: ValidateIgnoredErrorsExtension::loadConfiguration ran
TRACE: postInitializeContainer clearCache

Everything memoized under the DummyReflectionProvider is dropped before the container reaches anything that analyses code. Every container in the process goes through create() (DerivativeContainerFactory included), so there is no path that skips it.

The PHPUnit test did fail before the patch — but it hand-builds the swap by calling registerInstance() directly, bypassing the container lifecycle. It proved the hazard is real, not that any production path reaches it. So #15037 is not explained by this, and the fix does not fix it.

2) & 3) What I pushed

Since there is no reachable failure, an e2e test would pass with and without the patch — a green test that can never fail is worse than none. So instead of writing one:

• a94ca66d0 — reverts the whole commit (the four mutator clears, the ValidateIgnoredErrorsExtension clear, and the PHPUnit test). Beyond being unnecessary, clearing in ReflectionProviderStaticAccessor/PhpVersionStaticAccessor is actively misleading: postInitializeContainer() registers both before it sets the feature toggles, so a clear there fires too early to be the guard while looking like one.
• 1870b3715 — extends the comment on the TypeCombinator::clearCache() in postInitializeContainer() to record why it is the only clear the process needs (it is the last step of create(), and container compilation is where the accessors get temporarily swapped), plus a "don't add one to the accessors or the toggles" note. That comment is exactly what was missing when I misread this the first time.

make tests — 17797 tests, 90136 assertions, 97 skipped, exit 0. make phpstan — no errors.

Where that leaves #15037

Unexplained. The symptom — class-level @method/@property becoming invisible — is about annotation-method reflection, and a widened union from a stale memo would not produce it even if the memo were stale. I'd suggest reopening it for a fresh diagnosis rather than merging this; I did not reproduce the reported behaviour on glibc, and the reporter's environment is Alpine/musl, which I have not tested.