Keep a single memoization layer for located reflections

Located reflections were cached twice - by MemoizingReflector (keyed
by name) and again by MemoizingSourceLocator (keyed by identifier),
pinning every reflection object graph in memory twice per worker
process.

The locator-level cache could not simply be dropped: created
reflections capture the reflector passed to
SourceLocator::locateIdentifier() and resolve parent classes,
interfaces and prototypes through it, bypassing MemoizingReflector
entirely - the memoizing locator was the only cache absorbing those
internal lookups. MemoizingReflector now locates identifiers itself
instead of wrapping DefaultReflector, so created reflections capture
the memoizing reflector and route internal lookups through the same
name-keyed cache. The MemoizingSourceLocator wrappers are removed
along with the cache.memoizingSourceLocatorEntriesCountMax parameter
and the originalBetterReflectionReflector service.

The stub validator container relied on the removed locator wrapper as
its only memoization, so it now overrides betterReflectionSourceLocator
with the stub source locator instead of swapping reflectors.

In self-analysis this reduces total worker peak memory
from ~2.5 GB to ~2.1 GB with unchanged elapsed time.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017DjgMHgfvwhD4ogdTaRtLp

Author: ondrejmirtes

conf/config.neon

@@ -126,7 +126,6 @@ parameters:
 		nodesByStringCountMax: 256
 		resolvedPhpDocBlockCacheCountMax: 2048
 		nameScopeMapMemoryCacheCountMax: 512
-		memoizingSourceLocatorEntriesCountMax: 0
 		phpStormStubsNodesCountMax: 64
 	reportUnmatchedIgnoredErrors: true
 	reportIgnoresWithoutComments: false

conf/config.stubValidator.neon

@@ -19,19 +19,16 @@ services:
 		arguments:
 			allStubFiles: %allStubFiles%
 			php8Parser: @php8PhpParser
-			memoizingSourceLocatorEntriesCountMax: %cache.memoizingSourceLocatorEntriesCountMax%
 
 	# overrides service from parsers.neon
 	defaultAnalysisParser!:
 		factory: @stubParser
 
-	# overrides service from services.neon
-	nodeScopeResolverReflector:
-		factory: @stubReflector
-
-	# overrides service from services.neon so that Reflector autowires to stubReflector
-	originalBetterReflectionReflector!:
-		factory: @stubReflector
+	# overrides service from services.neon so that the reflector
+	# (and everything above it) reflects only the stub files
+	betterReflectionSourceLocator!:
+		factory: @stubSourceLocator
+		autowired: false
 
 	# overrides service from services.neon
 	reflectionProvider:
@@ -52,16 +49,10 @@ services:
 	stubBetterReflectionProvider:
 		class: PHPStan\Reflection\BetterReflection\BetterReflectionProvider
 		arguments:
-			reflector: @stubReflector
+			reflector: @betterReflectionReflector
 			universalObjectCratesClasses: %universalObjectCratesClasses%
 		autowired: false
 
-	stubReflector:
-		class: PHPStan\BetterReflection\Reflector\DefaultReflector
-		arguments:
-			sourceLocator: @stubSourceLocator
-		autowired: false
-
 	stubSourceLocator:
 		class: PHPStan\BetterReflection\SourceLocator\Type\SourceLocator
 		factory: @PHPStan\PhpDoc\StubSourceLocatorFactory::create()

conf/parametersSchema.neon

@@ -150,7 +150,6 @@ parametersSchema:
 		nodesByStringCountMax: int(),
 		resolvedPhpDocBlockCacheCountMax: int(),
 		nameScopeMapMemoryCacheCountMax: int(),
-		memoizingSourceLocatorEntriesCountMax: int(),
 		phpStormStubsNodesCountMax: int()
 	])
 	reportUnmatchedIgnoredErrors: bool()

conf/services.neon

@@ -42,13 +42,6 @@ services:
 		autowired:
 			- PHPStan\BetterReflection\SourceLocator\SourceStubber\ReflectionSourceStubber
 
-	originalBetterReflectionReflector:
-		class: PHPStan\BetterReflection\Reflector\DefaultReflector
-		arguments:
-			sourceLocator: @betterReflectionSourceLocator
-		autowired: false
-
-
 	# not registered using attributes because we don't want to apply service tags automatically
 	-
 		class: PHPStan\Dependency\ExportedNodeVisitor

src/PhpDoc/StubSourceLocatorFactory.php

@@ -7,7 +7,6 @@
 use PHPStan\BetterReflection\SourceLocator\SourceStubber\PhpStormStubsSourceStubber;
 use PHPStan\BetterReflection\SourceLocator\Type\AggregateSourceLocator;
 use PHPStan\BetterReflection\SourceLocator\Type\Composer\Psr\Psr4Mapping;
-use PHPStan\BetterReflection\SourceLocator\Type\MemoizingSourceLocator;
 use PHPStan\BetterReflection\SourceLocator\Type\PhpInternalSourceLocator;
 use PHPStan\BetterReflection\SourceLocator\Type\SourceLocator;
 use PHPStan\Reflection\BetterReflection\SourceLocator\OptimizedPsrAutoloaderLocatorFactory;
@@ -26,7 +25,6 @@ public function __construct(
 		private OptimizedSingleFileSourceLocatorRepository $optimizedSingleFileSourceLocatorRepository,
 		private OptimizedPsrAutoloaderLocatorFactory $optimizedPsrAutoloaderLocatorFactory,
 		private array $allStubFiles,
-		private int $memoizingSourceLocatorEntriesCountMax,
 	)
 	{
 	}
@@ -52,10 +50,9 @@ public function create(): SourceLocator
 
 		$locators[] = new PhpInternalSourceLocator($astPhp8Locator, $this->phpStormStubsSourceStubber);
 
-		return new MemoizingSourceLocator(
-			new AggregateSourceLocator($locators),
-			$this->memoizingSourceLocatorEntriesCountMax === 0 ? null : $this->memoizingSourceLocatorEntriesCountMax,
-		);
+		// no MemoizingSourceLocator here - located reflections are already memoized
+		// by MemoizingReflector, a second cache layer would only pin them in memory twice
+		return new AggregateSourceLocator($locators);
 	}
 
 }

src/Reflection/BetterReflection/BetterReflectionSourceLocatorFactory.php

@@ -10,7 +10,6 @@
 use PHPStan\BetterReflection\SourceLocator\Type\AggregateSourceLocator;
 use PHPStan\BetterReflection\SourceLocator\Type\Composer\Psr\Psr4Mapping;
 use PHPStan\BetterReflection\SourceLocator\Type\EvaledCodeSourceLocator;
-use PHPStan\BetterReflection\SourceLocator\Type\MemoizingSourceLocator;
 use PHPStan\BetterReflection\SourceLocator\Type\PhpInternalSourceLocator;
 use PHPStan\BetterReflection\SourceLocator\Type\SourceLocator;
 use PHPStan\DependencyInjection\AutowiredParameter;
@@ -75,8 +74,6 @@ public function __construct(
 		private bool $playgroundMode, // makes all PHPStan classes in the PHAR discoverable with PSR-4
 		#[AutowiredParameter]
 		private ?string $singleReflectionFile,
-		#[AutowiredParameter(ref: '%cache.memoizingSourceLocatorEntriesCountMax%')]
-		private int $memoizingSourceLocatorEntriesCountMax,
 	)
 	{
 	}
@@ -175,10 +172,9 @@ public function create(): SourceLocator
 			return new AggregateSourceLocator($locators);
 		};
 
-		return new MemoizingSourceLocator(
-			new LazySourceLocator($initializer),
-			$this->memoizingSourceLocatorEntriesCountMax === 0 ? null : $this->memoizingSourceLocatorEntriesCountMax,
-		);
+		// no MemoizingSourceLocator here - located reflections are already memoized
+		// by MemoizingReflector, a second cache layer would only pin them in memory twice
+		return new LazySourceLocator($initializer);
 	}
 
 }

src/Reflection/BetterReflection/Reflector/MemoizingReflector.php

@@ -10,8 +10,10 @@
 use PHPStan\BetterReflection\Reflection\ReflectionFunction;
 use PHPStan\BetterReflection\Reflector\Exception\IdentifierNotFound;
 use PHPStan\BetterReflection\Reflector\Reflector;
+use PHPStan\BetterReflection\SourceLocator\Type\SourceLocator;
 use PHPStan\DependencyInjection\AutowiredParameter;
 use PHPStan\DependencyInjection\AutowiredService;
+use PHPStan\ShouldNotHappenException;
 use function array_key_exists;
 use function strtolower;
 
@@ -29,8 +31,8 @@ final class MemoizingReflector implements Reflector
 	private array $functionReflections = [];
 
 	public function __construct(
-		#[AutowiredParameter(ref: '@originalBetterReflectionReflector')]
-		private Reflector $reflector,
+		#[AutowiredParameter(ref: '@betterReflectionSourceLocator')]
+		private SourceLocator $sourceLocator,
 	)
 	{
 	}
@@ -51,13 +53,22 @@ public function reflectClass(string $className): ReflectionClass
 			return $classReflection;
 		}
 
-		try {
-			return $this->classReflections[$lowerClassName] = $this->reflector->reflectClass($className);
-		} catch (IdentifierNotFound $e) {
+		// located directly, without a DefaultReflector - created reflections capture
+		// the reflector passed here and resolve e.g. parent classes and interfaces
+		// through it, so passing $this routes those lookups through this cache too
+		$identifier = new Identifier($className, new IdentifierType(IdentifierType::IDENTIFIER_CLASS));
+		$classReflection = $this->sourceLocator->locateIdentifier($this, $identifier);
+		if ($classReflection === null) {
 			$this->classReflections[$className] = null;
 
-			throw $e;
+			throw IdentifierNotFound::fromIdentifier($identifier);
 		}
+
+		if (!$classReflection instanceof ReflectionClass) {
+			throw new ShouldNotHappenException();
+		}
+
+		return $this->classReflections[$lowerClassName] = $classReflection;
 	}
 
 	#[Override]
@@ -72,13 +83,19 @@ public function reflectConstant(string $constantName): ReflectionConstant
 			return $constantReflection;
 		}
 
-		try {
-			return $this->constantReflections[$constantName] = $this->reflector->reflectConstant($constantName);
-		} catch (IdentifierNotFound $e) {
+		$identifier = new Identifier($constantName, new IdentifierType(IdentifierType::IDENTIFIER_CONSTANT));
+		$constantReflection = $this->sourceLocator->locateIdentifier($this, $identifier);
+		if ($constantReflection === null) {
 			$this->constantReflections[$constantName] = null;
 
-			throw $e;
+			throw IdentifierNotFound::fromIdentifier($identifier);
+		}
+
+		if (!$constantReflection instanceof ReflectionConstant) {
+			throw new ShouldNotHappenException();
 		}
+
+		return $this->constantReflections[$constantName] = $constantReflection;
 	}
 
 	#[Override]
@@ -94,31 +111,49 @@ public function reflectFunction(string $functionName): ReflectionFunction
 			return $functionReflection;
 		}
 
-		try {
-			return $this->functionReflections[$lowerFunctionName] = $this->reflector->reflectFunction($functionName);
-		} catch (IdentifierNotFound $e) {
+		$identifier = new Identifier($functionName, new IdentifierType(IdentifierType::IDENTIFIER_FUNCTION));
+		$functionReflection = $this->sourceLocator->locateIdentifier($this, $identifier);
+		if ($functionReflection === null) {
 			$this->functionReflections[$lowerFunctionName] = null;
 
-			throw $e;
+			throw IdentifierNotFound::fromIdentifier($identifier);
+		}
+
+		if (!$functionReflection instanceof ReflectionFunction) {
+			throw new ShouldNotHappenException();
 		}
+
+		return $this->functionReflections[$lowerFunctionName] = $functionReflection;
 	}
 
+	/**
+	 * @return list<ReflectionClass>
+	 */
 	#[Override]
 	public function reflectAllClasses(): iterable
 	{
-		return $this->reflector->reflectAllClasses();
+		/** @var list<ReflectionClass> */
+		return $this->sourceLocator->locateIdentifiersByType($this, new IdentifierType(IdentifierType::IDENTIFIER_CLASS));
 	}
 
+	/**
+	 * @return list<ReflectionFunction>
+	 */
 	#[Override]
 	public function reflectAllFunctions(): iterable
 	{
-		return $this->reflector->reflectAllFunctions();
+		/** @var list<ReflectionFunction> */
+		return $this->sourceLocator->locateIdentifiersByType($this, new IdentifierType(IdentifierType::IDENTIFIER_FUNCTION));
 	}
 
+	/**
+	 * @return list<ReflectionConstant>
+	 */
 	#[Override]
 	public function reflectAllConstants(): iterable
 	{
-		return $this->reflector->reflectAllConstants();
+		/** @var list<ReflectionConstant> */
+		return $this->sourceLocator->locateIdentifiersByType($this, new IdentifierType(IdentifierType::IDENTIFIER_CONSTANT));
 	}
 
 }

src/Testing/TestCase.neon

@@ -9,7 +9,6 @@ services:
 			php8Parser: @php8PhpParser
 			fileExtensions: %fileExtensions%
 			excludePaths: %excludePaths%
-			memoizingSourceLocatorEntriesCountMax: %cache.memoizingSourceLocatorEntriesCountMax%
 
 	# overrides service from parsers.neon
 	currentPhpVersionSimpleParser!:

src/Testing/TestCaseSourceLocatorFactory.php

@@ -9,7 +9,6 @@
 use PHPStan\BetterReflection\SourceLocator\SourceStubber\ReflectionSourceStubber;
 use PHPStan\BetterReflection\SourceLocator\Type\AggregateSourceLocator;
 use PHPStan\BetterReflection\SourceLocator\Type\EvaledCodeSourceLocator;
-use PHPStan\BetterReflection\SourceLocator\Type\MemoizingSourceLocator;
 use PHPStan\BetterReflection\SourceLocator\Type\PhpInternalSourceLocator;
 use PHPStan\BetterReflection\SourceLocator\Type\SourceLocator;
 use PHPStan\Php\PhpVersion;
@@ -47,7 +46,6 @@ public function __construct(
 		private PhpVersion $phpVersion,
 		private array $fileExtensions,
 		private ?array $excludePaths,
-		private int $memoizingSourceLocatorEntriesCountMax,
 	)
 	{
 	}
@@ -98,10 +96,9 @@ public function create(): SourceLocator
 		$locators[] = new PhpVersionBlacklistSourceLocator(new PhpInternalSourceLocator($astLocator, $this->reflectionSourceStubber), $this->phpstormStubsSourceStubber);
 		$locators[] = new PhpVersionBlacklistSourceLocator(new EvaledCodeSourceLocator($astLocator, $this->reflectionSourceStubber), $this->phpstormStubsSourceStubber);
 
-		return new MemoizingSourceLocator(
-			new AggregateSourceLocator($locators),
-			$this->memoizingSourceLocatorEntriesCountMax === 0 ? null : $this->memoizingSourceLocatorEntriesCountMax,
-		);
+		// no MemoizingSourceLocator here - located reflections are already memoized
+		// by MemoizingReflector, a second cache layer would only pin them in memory twice
+		return new AggregateSourceLocator($locators);
 	}
 
 }