Invalidate the OPcache entries of included files before an autoloader runs in the autoload trap

A bootstrap autoloader can include a file that the process already
included for real. With OPcache active, the trapped include then runs
the cached real script, and the process dies with "Cannot redeclare".
Composer's loaders no longer run in the trap (findFileWithComposer()),
so only the other autoloaders need this.

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

Author: SanderMuller

.github/workflows/e2e-tests.yml

@@ -262,6 +262,13 @@ jobs:
               php -r 'if (!extension_loaded("Zend OPcache")) { fwrite(STDERR, "OPcache is not loaded, so this step cannot reproduce the crash.\n"); exit(1); }'
               ../../bin/phpstan analyze --debug
               php -d disable_functions=pcntl_fork ../../bin/phpstan analyze
+          - script: |
+              cd e2e/bootstrap-autoloader-wrong-file
+              # The crash needs OPcache: forked workers switch it off, the --debug main process and
+              # spawned workers (pcntl_fork disabled, as on Windows) keep it on.
+              php -r 'if (!extension_loaded("Zend OPcache")) { fwrite(STDERR, "OPcache is not loaded, so this step cannot reproduce the crash.\n"); exit(1); }'
+              ../../bin/phpstan analyze --debug
+              php -d disable_functions=pcntl_fork ../../bin/phpstan analyze
           - script: |
               cd e2e/bug-14724
               composer install

e2e/bootstrap-autoloader-wrong-file/bootstrap.php

@@ -0,0 +1,17 @@
+<?php declare(strict_types = 1);
+
+// A hand-written autoloader, not Composer's: it includes the file for the requested
+// name and does not check what the file declared.
+spl_autoload_register(static function (string $class): void {
+	$prefix = 'BootstrapAutoloaderWrongFile\\';
+	if (!str_starts_with($class, $prefix)) {
+		return;
+	}
+
+	$file = __DIR__ . '/src/' . substr($class, strlen($prefix)) . '.php';
+	if (!is_file($file)) {
+		return;
+	}
+
+	require $file;
+});

e2e/bootstrap-autoloader-wrong-file/phpstan.dist.neon

@@ -0,0 +1,14 @@
+parameters:
+	level: 8
+	bootstrapFiles:
+		- bootstrap.php
+	paths:
+		- test.php
+	ignoreErrors:
+		# The autoloader includes src/Widget.php for this name, and the file declares Widgets.
+		# The analysis must report the unknown class, not die re-including that file.
+		-
+			message: '#^Parameter \$widget of method BootstrapAutoloaderWrongFile\\Consumer\:\:doFoo\(\) has invalid type BootstrapAutoloaderWrongFile\\Widget\.$#'
+			identifier: class.notFound
+			count: 1
+			path: test.php

e2e/bootstrap-autoloader-wrong-file/src/Widget.php

@@ -0,0 +1,10 @@
+<?php declare(strict_types = 1);
+
+namespace BootstrapAutoloaderWrongFile;
+
+// The declared name does not match the file name, so the autoloader includes this
+// file for BootstrapAutoloaderWrongFile\Widget and Widget is never declared.
+class Widgets
+{
+
+}

e2e/bootstrap-autoloader-wrong-file/test.php

@@ -0,0 +1,12 @@
+<?php declare(strict_types = 1);
+
+namespace BootstrapAutoloaderWrongFile;
+
+class Consumer
+{
+
+	public function doFoo(Widget $widget): void
+	{
+	}
+
+}

src/Reflection/BetterReflection/SourceLocator/AutoloadSourceLocator.php

@@ -31,6 +31,8 @@
 use function count;
 use function defined;
 use function function_exists;
+use function get_included_files;
+use function ini_get;
 use function interface_exists;
 use function is_array;
 use function is_file;
@@ -69,6 +71,9 @@ final class AutoloadSourceLocator implements SourceLocator
 	/** @var array<string, int> */
 	private array $startLineByClass = [];
 
+	/** How many get_included_files() entries invalidateIncludedFiles() has handled. */
+	private static int $invalidatedIncludedFilesCount = 0;
+
 	public function __construct(private FileNodesFetcher $fileNodesFetcher, private bool $executeAutoloadersInFileReadTrap)
 	{
 	}
@@ -355,6 +360,8 @@ static function () use ($className, &$foundByComposer): ?array {
 							return [[$composerFile], $className, null];
 						}
 
+						self::invalidateIncludedFiles();
+
 						try {
 							$preExistingAutoloader($className);
 						} catch (ParseError) {
@@ -432,6 +439,33 @@ private static function findFileWithComposer(callable $autoloader, string $class
 		return $resolvedFile;
 	}
 
+	/**
+	 * An autoloader can include a file that this process already included for real, for example a file
+	 * a bootstrap autoloader included without declaring the class. With OPcache active, the trapped
+	 * include of that file runs the script OPcache compiled from the real file, not the empty script
+	 * FileReadTrapStreamWrapper serves, and dies with "Cannot redeclare". Invalidating the entries of
+	 * the included files makes that include go through the trap. The opcache_invalidate() loop after
+	 * the trap cannot do this, because the include has already run by then. That loop removes the
+	 * empty script the trap left in OPcache.
+	 *
+	 * Only an autoloader that runs inside the trap needs this. findFileWithComposer() includes nothing.
+	 * Forked workers switch OPcache off (see ForkedProcess), so they skip this.
+	 */
+	private static function invalidateIncludedFiles(): void
+	{
+		if (!function_exists('opcache_invalidate') || !(bool) ini_get('opcache.enable') || !(bool) ini_get('opcache.enable_cli')) {
+			return;
+		}
+
+		$includedFiles = get_included_files();
+		$includedFilesCount = count($includedFiles);
+		for ($i = self::$invalidatedIncludedFilesCount; $i < $includedFilesCount; $i++) {
+			opcache_invalidate($includedFiles[$i], true);
+		}
+
+		self::$invalidatedIncludedFilesCount = $includedFilesCount;
+	}
+
 	private function silenceErrors(): void
 	{
 		set_error_handler(static fn (): bool => true);