Answer reflection cache misses without a failing include()

FileCacheStorage::load() learned that an entry was never written by
letting `@include` fail, which costs about 29us per miss: PHP walks the
include_path and builds two warnings only for the @ to discard them. A
stat() rules the file out in about 1.4us and adds nothing to the hit
path, where the include stats the file anyway.

Misses are far from rare. CachedPhpInternalSourceLocator sits behind
every file locator, so every class name they fail to resolve asks the
cache whether it is a PHP built-in - 114k misses per run on a large
project, in every run, warm cache or not. The stubs map is the only
source the wrapped locator reads from, so a class it does not list can
never have been cached; checking the map first skips the key hashing
and the stat() too. The wrapped locator is still asked, so class alias
resolution behaves as before.

Measured on a large project (10 workers, full analysis): the cache-miss
path dropped from 5.0s to 1.95s of fleet time with the guard alone, and
the whole run by 2.3s of user CPU across four ABBA pairs.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C2cdRMUX8Be44eUzEM6RQ2

Author: ondrejmirtes

src/Cache/FileCacheStorage.php

@@ -49,6 +49,17 @@ public function load(string $key, string $variableKey)
 	{
 		[,, $filePath] = $this->getFilePaths($key);
 
+		// Letting include() fail is an expensive way to learn that an entry was
+		// never written: PHP walks the include_path and builds two warnings only
+		// to have them discarded by the @, about 29us per miss, while the stat()
+		// that rules the file out costs about 1.4us and is free on the hit path
+		// (the include stats the file anyway). Misses are not rare - every class
+		// name that reaches the PHP-internal locator and turns out not to be a
+		// built-in is one, tens of thousands per run and per worker.
+		if (!is_file($filePath)) {
+			return null;
+		}
+
 		return (static function ($variableKey, $filePath) {
 			$cacheItem = @include $filePath;
 			if (!$cacheItem instanceof CacheItem) {

src/Reflection/BetterReflection/BetterReflectionSourceLocatorFactory.php

@@ -185,6 +185,7 @@ public function create(): SourceLocator
 				new PhpInternalSourceLocator($astPhp8Locator, $this->phpstormStubsSourceStubber),
 				$this->cache,
 				$this->phpVersion,
+				$this->phpstormStubsSourceStubber,
 			));
 
 			$locators[] = $this->skipBundledPolyfills(new AutoloadSourceLocator($this->fileNodesFetcher, true));

src/Reflection/BetterReflection/SourceLocator/CachedPhpInternalSourceLocator.php

@@ -11,6 +11,7 @@
 use PHPStan\BetterReflection\Reflection\ReflectionEnum;
 use PHPStan\BetterReflection\Reflection\ReflectionFunction;
 use PHPStan\BetterReflection\Reflector\Reflector;
+use PHPStan\BetterReflection\SourceLocator\SourceStubber\PhpStormStubsSourceStubber;
 use PHPStan\BetterReflection\SourceLocator\Type\SourceLocator;
 use PHPStan\Cache\Cache;
 use PHPStan\Internal\ComposerHelper;
@@ -59,6 +60,7 @@ public function __construct(
 		private SourceLocator $inner,
 		private Cache $cache,
 		private PhpVersion $phpVersion,
+		private PhpStormStubsSourceStubber $stubber,
 	)
 	{
 	}
@@ -70,6 +72,20 @@ public function locateIdentifier(Reflector $reflector, Identifier $identifier):
 		if ($identifier->isClass() || $identifier->isFunction()) {
 			$name = strtolower($name);
 		}
+
+		// Almost everything that reaches this locator is a userland class name
+		// that every earlier locator failed to resolve, and a name the stubs do
+		// not have can never have been cached - the stubber is the only source
+		// the wrapped locator reads from. Ruling those out against the stubs map
+		// is an array lookup, where asking the cache means hashing the key and
+		// stat()ing a file that will never exist. The wrapped locator is still
+		// asked: it resolves class aliases before consulting the stubber, so it
+		// can answer for a name the map does not list - such an answer just does
+		// not get cached, under a key that would be the alias anyway.
+		if ($identifier->isClass() && !$this->stubber->hasClass($name)) {
+			return $this->inner->locateIdentifier($reflector, $identifier);
+		}
+
 		$cacheKey = sprintf('phpinternal-%s-%s', $identifier->getType()->getName(), $name);
 		$variableCacheKey = $this->getVariableCacheKey();
 

tests/PHPStan/Cache/FileCacheStorageTest.php

@@ -0,0 +1,89 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Cache;
+
+use FilesystemIterator;
+use Override;
+use PHPStan\Internal\DirectoryCreatorException;
+use PHPStan\Testing\PHPStanTestCase;
+use RecursiveDirectoryIterator;
+use RecursiveIteratorIterator;
+use function is_dir;
+use function rmdir;
+use function sys_get_temp_dir;
+use function uniqid;
+use function unlink;
+
+final class FileCacheStorageTest extends PHPStanTestCase
+{
+
+	private string $directory;
+
+	protected function setUp(): void
+	{
+		parent::setUp();
+
+		$this->directory = sys_get_temp_dir() . '/' . uniqid('phpstan-cache-', true);
+	}
+
+	#[Override]
+	protected function tearDown(): void
+	{
+		parent::tearDown();
+
+		if (!is_dir($this->directory)) {
+			return;
+		}
+
+		$files = new RecursiveIteratorIterator(
+			new RecursiveDirectoryIterator($this->directory, FilesystemIterator::SKIP_DOTS),
+			RecursiveIteratorIterator::CHILD_FIRST,
+		);
+		foreach ($files as $file) {
+			if ($file->isDir()) {
+				rmdir($file->getPathname());
+				continue;
+			}
+
+			unlink($file->getPathname());
+		}
+
+		rmdir($this->directory);
+	}
+
+	public function testMissingEntry(): void
+	{
+		$storage = new FileCacheStorage($this->directory);
+
+		$this->assertNull($storage->load('never-written', 'v1'));
+	}
+
+	/**
+	 * @throws DirectoryCreatorException
+	 */
+	public function testEntrySavedAfterAMissIsLoadedBack(): void
+	{
+		$storage = new FileCacheStorage($this->directory);
+
+		// the miss comes first on purpose: load() stat()s the file to avoid a
+		// failing include(), and PHP's stat cache must not answer the second
+		// load() with what the first one saw
+		$this->assertNull($storage->load('key', 'v1'));
+		$storage->save('key', 'v1', ['data' => 1]);
+
+		$this->assertSame(['data' => 1], $storage->load('key', 'v1'));
+	}
+
+	/**
+	 * @throws DirectoryCreatorException
+	 */
+	public function testEntryWithDifferentVariableKey(): void
+	{
+		$storage = new FileCacheStorage($this->directory);
+		$storage->save('key', 'v1', ['data' => 1]);
+
+		$this->assertNull($storage->load('key', 'v2'));
+		$this->assertSame(['data' => 1], $storage->load('key', 'v1'));
+	}
+
+}