Memoize file contents by path in CachedParser to skip redundant reads

src/Parser/CachedParser.php

@@ -5,6 +5,9 @@
 use PhpParser\Node;
 use PHPStan\File\FileReader;
 use function array_key_first;
+use function clearstatcache;
+use function filemtime;
+use function filesize;
 use function strlen;
 
 final class CachedParser implements Parser
@@ -36,6 +39,20 @@ final class CachedParser implements Parser
 	/** @var array<string, true> */
 	private array $parsedByString = [];
 
+	/**
+	 * parseFile() is called once per class using a trait, so the same file
+	 * is read from disk over and over (one hot trait file was read 94,000
+	 * times in a cold run of a large Laravel project). Memoizing the contents
+	 * by path skips those redundant reads; the total memoized source size is
+	 * bounded the same way as the AST cache above.
+	 */
+	private const MEMOIZED_SOURCE_BYTES_LIMIT = 524_288;
+
+	/** @var array<string, array{int, int, string}> path => [mtime, size, source code] */
+	private array $cachedSourceByFile = [];
+
+	private int $memoizedSourceBytes = 0;
+
 	/**
 	 * The AST of a parsed file takes up roughly 50-60x more memory than the
 	 * source code itself, so alongside the entry count limit, the total source
@@ -59,7 +76,7 @@ public function __construct(
 	 */
 	public function parseFile(string $file): array
 	{
-		$sourceCode = FileReader::read($file);
+		$sourceCode = $this->readFile($file);
 		$isCached = isset($this->cachedNodesByString[$sourceCode]);
 		if ($isCached && !isset($this->parsedByString[$sourceCode])) {
 			return $this->markRecentlyUsed($sourceCode);
@@ -100,6 +117,61 @@ public function parseString(string $sourceCode): array
 		return $nodes;
 	}
 
+	/**
+	 * Read a file's contents, memoized by path and keyed by mtime; clearstatcache
+	 * keeps this correct when a file changes between calls in a long-running
+	 * process (PHPStan Pro, fixer worker). Bounded by MEMOIZED_SOURCE_BYTES_LIMIT
+	 * with least-recently-used eviction.
+	 */
+	private function readFile(string $file): string
+	{
+		// mtime alone has one-second granularity, so a same-second edit could be
+		// served stale in a long-running process (PHPStan Pro, fixer worker);
+		// keying by size as well catches edits that change the length. filesize()
+		// is served from PHP's stat cache populated by filemtime(), so it costs
+		// no extra syscall.
+		clearstatcache(true, $file);
+		$mtime = @filemtime($file);
+		$size = @filesize($file);
+		if ($mtime === false || $size === false) {
+			return FileReader::read($file);
+		}
+
+		if (
+			isset($this->cachedSourceByFile[$file])
+			&& $this->cachedSourceByFile[$file][0] === $mtime
+			&& $this->cachedSourceByFile[$file][1] === $size
+		) {
+			$entry = $this->cachedSourceByFile[$file];
+			unset($this->cachedSourceByFile[$file]);
+			$this->cachedSourceByFile[$file] = $entry;
+
+			return $entry[2];
+		}
+
+		$sourceCode = FileReader::read($file);
+		$incomingBytes = strlen($sourceCode);
+		if ($incomingBytes <= self::MEMOIZED_SOURCE_BYTES_LIMIT) {
+			if (isset($this->cachedSourceByFile[$file])) {
+				// stale entry for this path (mtime or size changed)
+				$this->memoizedSourceBytes -= strlen($this->cachedSourceByFile[$file][2]);
+				unset($this->cachedSourceByFile[$file]);
+			}
+			while ($this->memoizedSourceBytes + $incomingBytes > self::MEMOIZED_SOURCE_BYTES_LIMIT) {
+				$oldestPath = array_key_first($this->cachedSourceByFile);
+				if ($oldestPath === null) {
+					break;
+				}
+				$this->memoizedSourceBytes -= strlen($this->cachedSourceByFile[$oldestPath][2]);
+				unset($this->cachedSourceByFile[$oldestPath]);
+			}
+			$this->cachedSourceByFile[$file] = [$mtime, $size, $sourceCode];
+			$this->memoizedSourceBytes += $incomingBytes;
+		}
+
+		return $sourceCode;
+	}
+
 	/**
 	 * LRU bookkeeping: re-insert the entry at the end so genuinely cold sources
 	 * are evicted first, not the ones inserted earliest.

tests/PHPStan/Parser/CachedParserTest.php

@@ -5,13 +5,21 @@
 use Generator;
 use PhpParser\Node;
 use PhpParser\Node\Stmt\Namespace_;
+use PhpParser\Node\Stmt\Nop;
 use PHPStan\BetterReflection\Reflection\ExprCacheHelper;
 use PHPStan\File\FileHelper;
 use PHPStan\File\FileReader;
 use PHPStan\Testing\PHPStanTestCase;
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\MockObject\Stub;
+use function file_put_contents;
 use function sprintf;
+use function str_repeat;
+use function sys_get_temp_dir;
+use function time;
+use function touch;
+use function uniqid;
+use function unlink;
 
 class CachedParserTest extends PHPStanTestCase
 {
@@ -237,4 +245,84 @@ public function testWithExprCacheHelper(): void
 		$this->assertSame(['startLine' => 1, 'startTokenPos' => 35, 'startFilePos' => 137, 'endLine' => 10, 'endTokenPos' => 35, 'endFilePos' => 143, 'kind' => 1, 'rawValue' => "'hello'"], $reImported->getAttributes());
 	}
 
+	public function testParseFileSkipsReadingUnchangedFileAndRereadsAfterChange(): void
+	{
+		$parser = new CachedParser($this->getContentEchoingParserStub(), 500);
+		$path = sys_get_temp_dir() . '/phpstan-cached-parser-' . uniqid() . '.php';
+		$baseTime = time() - 10;
+
+		try {
+			file_put_contents($path, 'contents A');
+			touch($path, $baseTime);
+			$this->assertSame('contents A', $parser->parseFile($path)[0]->getAttribute('content'));
+
+			// Same-length contents change with an unchanged mtime is not detectable
+			// by the [mtime, size] key: the memoized contents are returned without re-reading.
+			file_put_contents($path, 'contents B');
+			touch($path, $baseTime);
+			$this->assertSame('contents A', $parser->parseFile($path)[0]->getAttribute('content'));
+
+			// A size change invalidates the memo even when the mtime is unchanged.
+			file_put_contents($path, 'contents B longer');
+			touch($path, $baseTime);
+			$this->assertSame('contents B longer', $parser->parseFile($path)[0]->getAttribute('content'));
+
+			// A newer mtime invalidates the memo, so the file is read again.
+			file_put_contents($path, 'contents C longer');
+			touch($path, $baseTime + 10);
+			$this->assertSame('contents C longer', $parser->parseFile($path)[0]->getAttribute('content'));
+		} finally {
+			@unlink($path);
+		}
+	}
+
+	public function testFileContentsMemoIsBoundedByTotalSourceBytes(): void
+	{
+		$parser = new CachedParser($this->getContentEchoingParserStub(), 500);
+		$baseTime = time() - 10;
+		$bigA = sys_get_temp_dir() . '/phpstan-cached-parser-a-' . uniqid() . '.php';
+		$bigB = sys_get_temp_dir() . '/phpstan-cached-parser-b-' . uniqid() . '.php';
+		$huge = sys_get_temp_dir() . '/phpstan-cached-parser-h-' . uniqid() . '.php';
+
+		try {
+			// A file larger than the memo limit is never memoized: a content change
+			// with an unchanged mtime is still picked up because the file is re-read.
+			file_put_contents($huge, 'huge first ' . str_repeat('x', 600_000));
+			touch($huge, $baseTime);
+			$this->assertStringStartsWith('huge first', $parser->parseFile($huge)[0]->getAttribute('content'));
+			file_put_contents($huge, 'huge second ' . str_repeat('x', 600_000));
+			touch($huge, $baseTime);
+			$this->assertStringStartsWith('huge second', $parser->parseFile($huge)[0]->getAttribute('content'));
+
+			// Two ~300 KB files exceed the limit together: memoizing the second
+			// evicts the first (least recently used), so a content change to the
+			// first with an unchanged mtime is picked up by the forced re-read.
+			file_put_contents($bigA, 'big-a first ' . str_repeat('a', 300_000));
+			touch($bigA, $baseTime);
+			$this->assertStringStartsWith('big-a first', $parser->parseFile($bigA)[0]->getAttribute('content'));
+
+			file_put_contents($bigB, 'big-b ' . str_repeat('b', 300_000));
+			touch($bigB, $baseTime);
+			$this->assertStringStartsWith('big-b', $parser->parseFile($bigB)[0]->getAttribute('content'));
+
+			file_put_contents($bigA, 'big-a second ' . str_repeat('a', 300_000));
+			touch($bigA, $baseTime);
+			$this->assertStringStartsWith('big-a second', $parser->parseFile($bigA)[0]->getAttribute('content'));
+		} finally {
+			@unlink($bigA);
+			@unlink($bigB);
+			@unlink($huge);
+		}
+	}
+
+	private function getContentEchoingParserStub(): Parser&Stub
+	{
+		$mock = $this->createStub(Parser::class);
+		$mock->method('parseFile')->willReturnCallback(
+			static fn (string $file): array => [new Nop(['content' => FileReader::read($file)])],
+		);
+
+		return $mock;
+	}
+
 }