Answer reflection cache misses without a failing include()

[ondrejmirtes]

FileCacheStorage::load() found out that an entry was never written by letting @include fail. That costs about 29 µs per miss: PHP walks the include_path and builds two warnings, and then the @ throws them away. A stat() rules the file out in about 1.4 µs, and it's free on the hit path because the include stats the file anyway (90.0 vs 89.9 µs per hit, microbenchmarked).

Misses are common. CachedPhpInternalSourceLocator sits behind every file locator, so every class name those locators can't resolve asks the cache whether it's a PHP built-in. On a large project (slevomat, 10 workers, full analysis) that's ~114k misses per run, in every run, whether the cache is warm or cold. The wrapped locator answers "not a built-in" in 3.8 µs, so the cache in front of it cost 8–12x more than the work it was caching.

Two changes:

• is_file() guard in FileCacheStorage::load(). This is general and helps every miss path.
• Stubs-map gate in CachedPhpInternalSourceLocator. The stubber is the only source the wrapped locator reads from, so a class not listed in PhpStormStubsSourceStubber::hasClass() can never have been cached. For those names we now skip the key hashing and the stat() too. The wrapped locator is still asked, so class-alias resolution behaves as before. Classes were 88% of the negative lookups; functions and constants have no cheap public check and just go through the guard.

Measurements

Measured with an instrumented phar on slevomat (full analysis, result cache deleted in every leg, outputs byte-identical):

• With the guard alone, the cache-miss path dropped from 5.04 s to 1.95 s of fleet-wide time.
• The whole run dropped by 2.3 s of user CPU, consistent across 4 ABBA pairs.
• The stubs-map gate removes most of the remaining 1.95 s. It wasn't benchmarked separately.

Tests

• New FileCacheStorageTest pins the one hazard the guard introduces: PHP's stat cache must not answer a load() after a miss → save() with the stale negative. I mutated the guard to memoize misses and testEntrySavedAfterAMissIsLoadedBack failed; with the real guard it passes.
• make tests (21416 tests), make phpstan and make cs all pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_01C2cdRMUX8Be44eUzEM6RQ2