Refuse the trap's open for a file the process has already run

The empty script FileReadTrapStreamWrapper::stream_read() serves only shadows
the real file while the compiler actually asks the wrapper for the contents.
With OPcache holding the script it does not ask: stream_open() still runs, so
the path is recorded, but stream_read() never does, and the real op_array
executes a second time. A file declaring a function then fatals with "Cannot
redeclare", which is the function-per-file layout of php-standard-library and
azjezz/psl: a files-autoload bootstrap loads every one of them at startup, and
the same paths stay reachable through a PSR-4 prefix for the autoloader to
include again.

Refuse the open when the target has already run in this process. That stops
the include before anything can be compiled or fetched from a cache, and the
path is recorded beforehand, which is all AutoloadSourceLocator wants from the
trap. Serving the empty script is unchanged for every file that has not run,
so the cold path keeps working as it did.

Deciding this on get_included_files() rather than on the OPcache API keeps the
answer independent of how, or whether, the script is cached. An earlier
revision of this fix dropped the shared memory entry with opcache_invalidate()
so that the include would read through the wrapper again; that held on Windows
but not on Linux, where the same three assumptions it rested on - that
opcache_is_script_cached() reports the entry, that opcache_invalidate() drops
it, and that OPcache consults its cache only after stream_open() has run - do
not all hold with this wrapper registered over file://. Refusing the open
depends on none of them, and also covers opcache.file_cache_only, which no API
can invalidate.

Refusing is not a new failure mode: an autoloader reaching this branch is
about to include a file that already ran, which fatally redeclares today. An
autoloader using include(), as Composer's does, now gets a warning that
AutoloadSourceLocator::silenceErrors() swallows.

The test drives both branches in a subprocess under the worker's own OPcache
flags: a file the bootstrap already loaded, which must be trapped without
running again, and one nothing has loaded, which must still be trapped and
left undeclared.

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

Author: theodorejb

src/Reflection/BetterReflection/SourceLocator/FileReadTrapStreamWrapper.php

@@ -3,10 +3,15 @@
 namespace PHPStan\Reflection\BetterReflection\SourceLocator;
 
 use PHPStan\ShouldNotHappenException;
+use function array_fill_keys;
+use function array_key_exists;
+use function count;
 use function function_exists;
+use function get_included_files;
 use function is_dir;
 use function is_file;
 use function opcache_get_status;
+use function realpath;
 use function stat;
 use function stream_resolve_include_path;
 use function stream_wrapper_register;
@@ -54,6 +59,11 @@ final class FileReadTrapStreamWrapper
 
 	private static ?bool $opcacheEnabled = null;
 
+	private static int $includedFilesCount = -1;
+
+	/** @var array<string, true> */
+	private static array $includedFilesMap = [];
+
 	private bool $readFromFile = false;
 
 	private int $seekPosition = 0;
@@ -117,6 +127,12 @@ public function stream_open($path, $mode, $options, &$openedPath): bool
 
 		if ($exists) {
 			self::$autoloadLocatedFiles[] = $path;
+
+			if (self::alreadyIncluded($path)) {
+				// the path is recorded, which is all the locator wants; refusing
+				// the open is the only way to keep the file from running again
+				return false;
+			}
 		}
 		$this->path = $path;
 		$this->readFromFile = false;
@@ -146,6 +162,47 @@ public function stream_read($count): string
 		return '';
 	}
 
+	/**
+	 * Whether the file at this path has already run in this process, so that
+	 * including it again would redeclare everything it holds.
+	 *
+	 * The empty script stream_read() serves only shadows the real file while
+	 * the compiler actually asks this wrapper for the contents. With OPcache
+	 * holding the script it does not ask: stream_open() still runs - so the
+	 * path is recorded - but stream_read() never does, and the real op_array
+	 * executes a second time. A file declaring a function then fatals with
+	 * "Cannot redeclare function...". This affects function-per-file packages
+	 * like php-standard-library and azjezz/psl: a files-autoload bootstrap
+	 * loads every one of them at startup, and the same paths stay reachable
+	 * through a PSR-4 prefix for the autoloader to include again.
+	 *
+	 * Refusing the open is what closes that off, because it stops the include
+	 * before anything can be compiled or fetched from a cache. Deciding it on
+	 * get_included_files() rather than on the OPcache API keeps the answer
+	 * independent of how (or whether) the script is cached: opcache_invalidate()
+	 * reaches a shared memory entry but never a file cache one, and neither it
+	 * nor opcache_is_script_cached() behaves the same across platforms when
+	 * called with this wrapper registered over file://.
+	 */
+	private static function alreadyIncluded(string $path): bool
+	{
+		$includedFiles = get_included_files();
+		if (count($includedFiles) !== self::$includedFilesCount) {
+			self::$includedFilesCount = count($includedFiles);
+			self::$includedFilesMap = array_fill_keys($includedFiles, true);
+		}
+
+		if (array_key_exists($path, self::$includedFilesMap)) {
+			return true;
+		}
+
+		// get_included_files() reports the resolved path, the include may be
+		// given one that only points at the same file
+		$realPath = realpath($path);
+
+		return $realPath !== false && array_key_exists($realPath, self::$includedFilesMap);
+	}
+
 	/**
 	 * Whether the empty script served for this path would stay in OPcache and
 	 * shadow the real file for the rest of the process.
@@ -164,6 +221,11 @@ public function stream_read($count): string
 	 * phar://.../vendor/composer/../../src/....
 	 */
 	private static function servesParseError(string $path): bool
+	{
+		return self::resolveServesParseError(PHP_VERSION_ID, self::opcacheEnabled(), $path);
+	}
+
+	private static function opcacheEnabled(): bool
 	{
 		if (self::$opcacheEnabled === null) {
 			self::$opcacheEnabled = false;
@@ -173,7 +235,7 @@ private static function servesParseError(string $path): bool
 			}
 		}
 
-		return self::resolveServesParseError(PHP_VERSION_ID, self::$opcacheEnabled, $path);
+		return self::$opcacheEnabled;
 	}
 
 	public static function resolveServesParseError(int $phpVersionId, bool $opcacheEnabled, string $path): bool

tests/PHPStan/Reflection/BetterReflection/SourceLocator/FileReadTrapStreamWrapperTest.php

@@ -3,7 +3,16 @@
 namespace PHPStan\Reflection\BetterReflection\SourceLocator;
 
 use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Group;
 use PHPUnit\Framework\TestCase;
+use function escapeshellarg;
+use function exec;
+use function explode;
+use function extension_loaded;
+use function implode;
+use function sprintf;
+use function str_contains;
+use const PHP_BINARY;
 
 final class FileReadTrapStreamWrapperTest extends TestCase
 {
@@ -29,4 +38,48 @@ public function testResolveServesParseError(int $phpVersionId, bool $opcacheEnab
 		$this->assertSame($expected, FileReadTrapStreamWrapper::resolveServesParseError($phpVersionId, $opcacheEnabled, $path));
 	}
 
+	/**
+	 * A file the process has already run must not run again when an autoloader
+	 * includes it inside the trap - with OPcache holding the script, the empty
+	 * script stream_read() serves never reaches the compiler. A file nothing has
+	 * loaded must still be trapped and left undeclared.
+	 *
+	 * Needs its own process: OPcache is only on in the processes PHPStan spawns
+	 * for itself, and the failure is a fatal error.
+	 */
+	#[Group('exec')]
+	public function testTrapSurvivesOpcacheCacheHit(): void
+	{
+		if (!extension_loaded('Zend OPcache')) {
+			self::markTestSkipped('OPcache is not available.');
+		}
+
+		exec(sprintf(
+			'%s -d opcache.enable=1 -d opcache.enable_cli=1 -d opcache.validate_timestamps=0 %s 2>&1',
+			escapeshellarg(PHP_BINARY),
+			escapeshellarg(__DIR__ . '/data/opcache-trap/driver.php'),
+		), $outputLines, $exitCode);
+		$output = implode("\n", $outputLines);
+
+		$this->assertSame(0, $exitCode, $output);
+
+		$values = [];
+		foreach ($outputLines as $outputLine) {
+			if (!str_contains($outputLine, '=')) {
+				continue;
+			}
+			[$name, $value] = explode('=', $outputLine, 2);
+			$values[$name] = $value;
+		}
+
+		// hold whether or not OPcache could be turned on
+		$this->assertSame('1', $values['trappedLoaded'] ?? null, $output);
+		$this->assertSame('1', $values['trappedCold'] ?? null, $output);
+		$this->assertSame('1', $values['coldStayedUndeclared'] ?? null, $output);
+
+		if (($values['opcacheEnabled'] ?? '0') !== '1') {
+			self::markTestSkipped('OPcache could not be enabled for the CLI, so the cache hit was not exercised.');
+		}
+	}
+
 }

tests/PHPStan/Reflection/BetterReflection/SourceLocator/data/opcache-trap/cold-function.php

@@ -0,0 +1,8 @@
+<?php declare(strict_types = 1);
+
+namespace OpcacheTrap;
+
+function coldThing(): string
+{
+	return 'y';
+}

tests/PHPStan/Reflection/BetterReflection/SourceLocator/data/opcache-trap/driver.php

@@ -0,0 +1,71 @@
+<?php declare(strict_types = 1);
+
+// Driver for FileReadTrapStreamWrapperTest::testTrapSurvivesOpcacheCacheHit().
+//
+// Probes two names through the trap the way AutoloadSourceLocator does:
+//  - OpcacheTrap\thing lives in a file the bootstrap has already loaded, which
+//    is the php-standard-library / azjezz/psl shape: a files-autoload bootstrap
+//    loads every function file at startup, and the same paths stay reachable
+//    through a PSR-4 prefix. With OPcache on, the include of the already-cached
+//    path used to be served from shared memory without ever reaching the trap's
+//    stream_read(), so the real file ran again and fatalled with
+//    "Cannot redeclare function OpcacheTrap\thing()".
+//  - OpcacheTrap\coldThing lives in a file nothing has loaded, and must still be
+//    trapped and recorded the way it always was.
+
+use PHPStan\Reflection\BetterReflection\SourceLocator\FileReadTrapStreamWrapper;
+
+require_once __DIR__ . '/../../../../../../../vendor/autoload.php';
+
+$loaded = __DIR__ . '/function.php';
+$cold = __DIR__ . '/cold-function.php';
+
+require_once $loaded;
+
+spl_autoload_register(static function (string $name) use ($loaded, $cold): void {
+	if ($name === 'OpcacheTrap\thing') {
+		include $loaded;
+	} elseif ($name === 'OpcacheTrap\coldThing') {
+		include $cold;
+	}
+});
+
+$opcacheStatus = opcache_get_status(false);
+$opcacheEnabled = $opcacheStatus !== false && ($opcacheStatus['opcache_enabled'] ?? false) === true;
+
+// AutoloadSourceLocator::silenceErrors() does the same around the trap.
+set_error_handler(static fn (): bool => true);
+
+$trap = static function (string $name): array {
+	return FileReadTrapStreamWrapper::withStreamWrapperOverride(static function () use ($name): array {
+		$autoloaders = spl_autoload_functions();
+		if ($autoloaders === false) {
+			return [];
+		}
+
+		foreach ($autoloaders as $autoloader) {
+			$autoloader($name);
+
+			if (FileReadTrapStreamWrapper::$autoloadLocatedFiles !== []) {
+				return FileReadTrapStreamWrapper::$autoloadLocatedFiles;
+			}
+		}
+
+		return [];
+	});
+};
+
+$trappedLoaded = array_map('realpath', $trap('OpcacheTrap\thing')) === [realpath($loaded)];
+$trappedCold = array_map('realpath', $trap('OpcacheTrap\coldThing')) === [realpath($cold)];
+
+// The cold file must have been shadowed by the trap, not really executed.
+$coldStayedUndeclared = !function_exists('OpcacheTrap\coldThing');
+
+restore_error_handler();
+
+// Compared here rather than in the test so that the separator normalization PHP
+// applies to include paths on Windows does not leak into the assertion.
+echo 'opcacheEnabled=', $opcacheEnabled ? '1' : '0', "\n";
+echo 'trappedLoaded=', $trappedLoaded ? '1' : '0', "\n";
+echo 'trappedCold=', $trappedCold ? '1' : '0', "\n";
+echo 'coldStayedUndeclared=', $coldStayedUndeclared ? '1' : '0', "\n";

tests/PHPStan/Reflection/BetterReflection/SourceLocator/data/opcache-trap/function.php

@@ -0,0 +1,8 @@
+<?php declare(strict_types = 1);
+
+namespace OpcacheTrap;
+
+function thing(): string
+{
+	return 'x';
+}