Decode the framed sections on demand instead of on restore

restore() no longer hands back the errors, locally ignored errors, collected
data and exported nodes as arrays: the cache file carries them as closures, and
a run that never asks for a section never pays for it. The var_export format
does this by writing `static function (): array { return [...]; }` into the
file, which only defers the array literal - PHP still compiles it and OPCache
still holds it.

A framed file needs no such trick. Each of those sections is one array frame, so
the reader remembers where it starts, walks past its entries without
unserializing them, and hands out a callback that seeks back and decodes on
demand. Walking rather than skipping wholesale keeps the eager validation of the
whole file's framing, so a damaged cache is still discarded by restore() instead
of throwing later inside a callback. fseek() past the end of a file succeeds, so
the position is compared with the file size after every entry - a killed save
leaves exactly that kind of truncation.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: 2 people

.github/workflows/e2e-tests.yml

@@ -127,8 +127,21 @@ jobs:
           - script: |
               cd e2e/result-cache-truncated
               ../../bin/phpstan -vvv
+              # Cut inside the first section's payload: the cache is damaged, not merely stale, so
+              # it has to be discarded rather than read as far as it goes.
               php truncate.php
-              ../../bin/phpstan -vvv
+              OUTPUT=$(../../bin/phpstan -vvv 2>&1)
+              echo "$OUTPUT"
+              ../bashunit -a contains 'an error occurred while loading the cache file' "$OUTPUT"
+              ../bashunit -a contains 'Result cache is saved.' "$OUTPUT"
+              # And once more inside a section that is read lazily, which is a different code path.
+              php truncate-lazy.php
+              OUTPUT=$(../../bin/phpstan -vvv 2>&1)
+              echo "$OUTPUT"
+              ../bashunit -a contains 'is truncated at entry' "$OUTPUT"
+              OUTPUT=$(../../bin/phpstan -vvv 2>&1)
+              echo "$OUTPUT"
+              ../bashunit -a contains 'Result cache restored.' "$OUTPUT"
           - script: |
               cd e2e/bug-14514
               composer install

e2e/result-cache-truncated/truncate-lazy.php

@@ -0,0 +1,13 @@
+<?php declare(strict_types = 1);
+
+// The same shape as truncate.php, but cutting far enough in to land inside one of the sections
+// restore() reads lazily. Those are walked rather than decoded when the cache is opened, and
+// fseek() past the end of a file succeeds, so only comparing the position with the file size
+// catches this - otherwise the section would be handed out as a callback pointing past the end.
+$file = __DIR__ . '/tmp/resultCache.php';
+$contents = file_get_contents($file);
+if ($contents === false) {
+	throw new RuntimeException('No result cache at ' . $file);
+}
+
+file_put_contents($file, substr($contents, 0, (int) (strlen($contents) * 0.9)));

src/Analyser/ResultCache/ResultCacheManager.php

@@ -46,6 +46,9 @@
 use function fgets;
 use function fopen;
 use function fread;
+use function fseek;
+use function fstat;
+use function ftell;
 use function fwrite;
 use function get_loaded_extensions;
 use function hash_file;
@@ -68,6 +71,7 @@
 use function unlink;
 use function unserialize;
 use const PHP_VERSION_ID;
+use const SEEK_CUR;
 
 /**
  * @phpstan-import-type LinesToIgnore from FileAnalyserResult
@@ -98,6 +102,13 @@ final class ResultCacheManager
 	 */
 	private const SERIALIZED_FILE_PREFIX = '<?php return; ?>';
 
+	/**
+	 * Sections restore() hands back as callbacks instead of arrays, so a run that never asks for them
+	 * never pays for decoding them. Each is a whole array frame in the file, so the reader only has to
+	 * remember where it starts and walk past its entries.
+	 */
+	private const LAZY_SECTIONS = ['errors', 'locallyIgnoredErrors', 'collectedData', 'exportedNodes'];
+
 	/** @var array<string, string> */
 	private array $fileHashes = [];
 
@@ -471,12 +482,12 @@ public function restore(array $allAnalysedFiles, bool $debug, bool $onlyFiles, ?
 		$filesToAnalyse = [];
 		$invertedDependenciesToReturn = [];
 		$invertedUsedTraitDependenciesToReturn = [];
-		$errors = $data['errors'];
-		$locallyIgnoredErrors = $data['locallyIgnoredErrors'];
+		$errors = $data['errorsCallback']();
+		$locallyIgnoredErrors = $data['locallyIgnoredErrorsCallback']();
 		$linesToIgnore = $data['linesToIgnore'];
 		$unmatchedLineIgnores = $data['unmatchedLineIgnores'];
-		$collectedData = $data['collectedData'];
-		$exportedNodes = $data['exportedNodes'];
+		$collectedData = $data['collectedDataCallback']();
+		$exportedNodes = $data['exportedNodesCallback']();
 		$filteredErrors = [];
 		$filteredLocallyIgnoredErrors = [];
 		$filteredLinesToIgnore = [];
@@ -1346,12 +1357,17 @@ private function readCacheFile(string $cacheFilePath): ?array
 			return null;
 		}
 
+		$stat = fstat($handle);
+		$fileSize = $stat === false ? 0 : $stat['size'];
+		$closeHandle = true;
+
 		try {
 			if (rtrim((string) fgets($handle), "\n") !== self::SERIALIZED_FILE_PREFIX) {
 				return null;
 			}
 
 			$data = [];
+			$lazy = array_fill_keys(self::LAZY_SECTIONS, false);
 			while (($header = fgets($handle)) !== false) {
 				$header = rtrim($header, "\n");
 				if ($header === '') {
@@ -1370,15 +1386,90 @@ private function readCacheFile(string $cacheFilePath): ?array
 					continue;
 				}
 
-				$data[substr($name, 0, -1)] = $this->readEntryFrames($handle, (int) $size);
+				$name = substr($name, 0, -1);
+				$count = (int) $size;
+				if (!array_key_exists($name, $lazy)) {
+					$data[$name] = $this->readEntryFrames($handle, $count);
+
+					continue;
+				}
+
+				// The entries are walked rather than decoded: that validates the framing of the whole
+				// file up front, so a damaged cache is still discarded by restore() instead of failing
+				// later inside the callback, and leaves the payloads to be unserialized on demand.
+				$offset = ftell($handle);
+				if ($offset === false) {
+					throw new RuntimeException(sprintf('Cannot tell the position of section "%s".', $name));
+				}
+
+				$this->skipEntryFrames($handle, $count, $fileSize, $name);
+				$lazy[$name] = true;
+				$data[$name . 'Callback'] = fn (): array => $this->readEntryFramesAt($handle, $offset, $count, $name);
 			}
 
+			foreach ($lazy as $name => $seen) {
+				if ($seen) {
+					continue;
+				}
+
+				$data[$name . 'Callback'] = static fn (): array => [];
+			}
+
+			$closeHandle = false;
+
 			return $data;
 		} finally {
-			fclose($handle);
+			if ($closeHandle) {
+				fclose($handle);
+			}
 		}
 	}
 
+	/**
+	 * Walks past an array frame's entries without unserializing them, checking as it goes that the
+	 * file really holds them.
+	 *
+	 * @param resource $handle
+	 */
+	private function skipEntryFrames($handle, int $count, int $fileSize, string $name): void
+	{
+		for ($i = 0; $i < $count; $i++) {
+			$length = fgets($handle);
+			if ($length === false) {
+				throw new RuntimeException(sprintf('Section "%s" ended after %d of %d entries.', $name, $i, $count));
+			}
+
+			$length = (int) rtrim($length, "\n");
+			if ($length <= 0) {
+				throw new RuntimeException(sprintf('Frame length %d is not positive.', $length));
+			}
+
+			// fseek() past the end of a file succeeds, so the position is what catches a truncated
+			// section - a killed save leaves exactly that.
+			if (fseek($handle, $length, SEEK_CUR) !== 0) {
+				throw new RuntimeException(sprintf('Cannot skip entry %d of section "%s".', $i, $name));
+			}
+
+			$position = ftell($handle);
+			if ($position === false || $position > $fileSize) {
+				throw new RuntimeException(sprintf('Section "%s" is truncated at entry %d of %d.', $name, $i, $count));
+			}
+		}
+	}
+
+	/**
+	 * @param resource $handle
+	 * @return array<mixed>
+	 */
+	private function readEntryFramesAt($handle, int $offset, int $count, string $name): array
+	{
+		if (fseek($handle, $offset) !== 0) {
+			throw new RuntimeException(sprintf('Cannot seek to section "%s".', $name));
+		}
+
+		return $this->readEntryFrames($handle, $count);
+	}
+
 	/**
 	 * @param resource $handle
 	 * @return array<mixed>