Invalidate the OPcache entries of included files before an autoloader runs in the autoload trap (#6742)

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);