Invalidate the OPcache entries of files a bootstrap autoloader included without declaring the class

AutoloadFunctionsSourceLocator runs a bootstrap autoloader for real. When the file it
includes does not declare the requested class, AutoloadSourceLocator later runs the
autoloaders again for the same name inside FileReadTrapStreamWrapper. With OPcache
active, the second include runs the script compiled from the real file, not the trap's
empty script, and the process dies with "Cannot redeclare class".

OPcache is active in the --debug main process and in spawned workers, because the
process restart switches it on. Forked workers switch it off, so a default run on
Linux or macOS does not crash.

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

Author: SanderMuller

.github/workflows/e2e-tests.yml

@@ -254,6 +254,13 @@ jobs:
               cd e2e/bug-15102c
               composer install
               ../../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 'exit(extension_loaded("Zend OPcache") ? 0 : 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/AutoloadFunctionsSourceLocator.php

@@ -8,8 +8,14 @@
 use PHPStan\BetterReflection\Reflection\Reflection;
 use PHPStan\BetterReflection\Reflector\Reflector;
 use PHPStan\BetterReflection\SourceLocator\Type\SourceLocator;
+use function array_slice;
 use function class_exists;
+use function count;
+use function function_exists;
+use function get_included_files;
+use function ini_get;
 use function interface_exists;
+use function opcache_invalidate;
 use function PHPStan\autoloadFunctions;
 use function trait_exists;
 
@@ -37,7 +43,12 @@ public function locateIdentifier(Reflector $reflector, Identifier $identifier):
 
 		$autoloadFunctions = autoloadFunctions();
 		foreach ($autoloadFunctions as $autoloadFunction) {
+			$includedFilesCount = self::isOpcacheActive() ? count(get_included_files()) : null;
 			$autoloadFunction($className);
+			if ($includedFilesCount !== null) {
+				self::invalidateFilesNotDeclaringClass($className, $includedFilesCount);
+			}
+
 			$reflection = $this->autoloadSourceLocator->locateIdentifier($reflector, $identifier);
 			if ($reflection !== null) {
 				return $reflection;
@@ -52,6 +63,34 @@ public function locateIdentifier(Reflector $reflector, Identifier $identifier):
 		return null;
 	}
 
+	/**
+	 * The autoloader included files for the class for real, but did not declare it. AutoloadSourceLocator
+	 * later runs the autoloaders again for the same name inside FileReadTrapStreamWrapper, and the
+	 * autoloader includes the same files again. With OPcache active, that include runs the script
+	 * OPcache compiled from the real file, not the empty script the trap serves, and dies with
+	 * "Cannot redeclare class". Invalidating the entries makes that include go through the trap.
+	 */
+	private static function invalidateFilesNotDeclaringClass(string $className, int $includedFilesCount): void
+	{
+		if (class_exists($className, false) || interface_exists($className, false) || trait_exists($className, false)) {
+			return;
+		}
+
+		foreach (array_slice(get_included_files(), $includedFilesCount) as $file) {
+			opcache_invalidate($file, true);
+		}
+	}
+
+	/**
+	 * Forked workers switch OPcache off (see ForkedProcess), so they skip the get_included_files() calls.
+	 */
+	private static function isOpcacheActive(): bool
+	{
+		return function_exists('opcache_invalidate')
+			&& (bool) ini_get('opcache.enable')
+			&& (bool) ini_get('opcache.enable_cli');
+	}
+
 	#[Override]
 	public function locateIdentifiersByType(Reflector $reflector, IdentifierType $identifierType): array
 	{