Resolve bootstrap autoloaders' classes from the files they ask for, running them for real only when that cannot redeclare a symbol

The function_exists($className) gate added for phpstan/phpstan#14988
confused two meanings of "functions": AutoloadFunctionsSourceLocator is
about autoload functions - the spl_autoload_register() callbacks that
bootstrap files register - not about class names coinciding with defined
functions. Executed for a class, such an autoloader either asks for a
file, which the file-read trap detects, or defines the class without one,
through class_alias() or eval().

The gate's probe also poisoned its own evidence: a trapped include
succeeds with empty content, defining nothing but still registering in
get_included_files(), so comparing the trapped files against
get_included_files() taken after the probe declined the very lookup it
was probing. Laravel's facade aliases whose target class is not loaded
yet hit exactly that: resolving Redirect makes class_alias() ask for the
file of Illuminate\Support\Facades\Redirect, the probe trapped that read,
found the file "already included" and declined, and larastan's
monicahq/monica e2e failed with seven "unknown class Redirect" errors.
Any earlier probe trapping the same file poisoned later lookups the same
way, since the pseudo-include sticks for the rest of the process.

Now every lookup probes under the trap first, the class is located
statically in the files the autoloaders asked for, and the autoloaders
run for real only when executing those files could not fatally redeclare
anything - judged by the files' statically parsed symbols, which
pseudo-includes cannot poison, instead of by get_included_files().

The bug-15102c e2e covers the shape Illuminate\Foundation\AliasLoader
creates in a real Laravel app: a prepended autoloader aliasing a name
that collides with a global helper function to a class only Composer can
autoload.

See phpstan/phpstan#15102

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JkCjnojdWZvswKCPmzt4zY

Author: ondrejmirtes

.github/workflows/e2e-tests.yml

@@ -147,6 +147,10 @@ jobs:
               cd e2e/bug-15102
               composer install
               ../../bin/phpstan analyze
+          - script: |
+              cd e2e/bug-15102c
+              composer install
+              ../../bin/phpstan analyze
           - script: |
               cd e2e/bug-14724
               composer install

e2e/bug-15102c/.gitignore

@@ -0,0 +1,2 @@
+/vendor/
+composer.lock

e2e/bug-15102c/bootstrap.php

@@ -0,0 +1,16 @@
+<?php declare(strict_types = 1);
+
+// The shape Illuminate\Foundation\AliasLoader creates in a real Laravel app: a prepended
+// autoloader resolving a short alias with class_alias(), where the aliased class is not
+// loaded yet - Composer autoloads it on demand when class_alias() asks for it. The alias
+// name collides with a global helper function ('Redirect' vs redirect()), like Laravel's
+// Redirect, Cache, View and Session aliases do.
+require_once __DIR__ . '/vendor/autoload.php';
+
+spl_autoload_register(static function (string $class): void {
+	if ($class !== 'Redirect') {
+		return;
+	}
+
+	class_alias(E2eFacadeAlias\Redirect::class, 'Redirect');
+}, true, true);

e2e/bug-15102c/composer.json

@@ -0,0 +1,10 @@
+{
+	"autoload": {
+		"psr-4": {
+			"E2eFacadeAlias\\": "src/"
+		},
+		"files": [
+			"helpers.php"
+		]
+	}
+}

e2e/bug-15102c/helpers.php

@@ -0,0 +1,9 @@
+<?php declare(strict_types = 1);
+
+// The global helper whose name collides with the alias - Laravel loads these via
+// Composer's autoload.files, so the function exists before analysis starts and
+// function_exists('Redirect') is true (function names are case-insensitive).
+function redirect(): int
+{
+	return 1;
+}

e2e/bug-15102c/phpstan.dist.neon

@@ -0,0 +1,6 @@
+parameters:
+	level: 8
+	bootstrapFiles:
+		- bootstrap.php
+	paths:
+		- test.php

e2e/bug-15102c/src/Redirect.php

@@ -0,0 +1,15 @@
+<?php declare(strict_types = 1);
+
+namespace E2eFacadeAlias;
+
+// The class behind the alias. Unlike bug-15102b's fixture it is NOT loaded during
+// bootstrap - only Composer can autoload it - so resolving the alias makes
+// class_alias() trigger a nested file read while the probe's trap is active.
+class Redirect
+{
+
+	public function doFoo(): void
+	{
+	}
+
+}

e2e/bug-15102c/test.php

@@ -0,0 +1,5 @@
+<?php declare(strict_types = 1);
+
+function (Redirect $redirect): void {
+	$redirect->doFoo();
+};

src/Reflection/BetterReflection/SourceLocator/AutoloadFunctionsSourceLocator.php

@@ -10,15 +10,20 @@
 use PHPStan\BetterReflection\SourceLocator\Type\SourceLocator;
 use function class_exists;
 use function function_exists;
-use function get_included_files;
-use function in_array;
 use function interface_exists;
+use function opcache_invalidate;
 use function PHPStan\autoloadFunctions;
 use function PHPStan\autoloadFunctionsPrependedToComposer;
 use function restore_error_handler;
 use function set_error_handler;
 use function trait_exists;
 
+/**
+ * Consults the autoload functions that bootstrap files registered - spl_autoload_register()
+ * callbacks that are not Composer's class loader. Asked for a class, such an autoloader either
+ * reads a file (which the file-read trap detects, so the class is located in it statically) or
+ * defines the class without one, through class_alias() or eval().
+ */
 final class AutoloadFunctionsSourceLocator implements SourceLocator
 {
 
@@ -55,17 +60,36 @@ public function locateIdentifier(Reflector $reflector, Identifier $identifier):
 			return null;
 		}
 
-		if (function_exists($className)) {
-			if ($this->wouldReIncludeALoadedFile($autoloadFunctions, $className)) {
-				return null;
-			}
+		$locatedFiles = $this->probeAutoloadFunctions($autoloadFunctions, $className);
 
-			// The trap intercepts file reads, not execution, so the probe ran the autoloaders for
-			// real. One that defines the class without reading a file - class_alias(), eval() -
-			// has already done its work, and calling it again would redeclare what it defined.
-			if (class_exists($className, false) || interface_exists($className, false) || trait_exists($className, false)) {
-				return $this->locateWithoutAutoloading($reflector, $identifier);
-			}
+		// An autoloader can define the class without reading any file - class_alias() with an
+		// already-loaded target, or eval(). The trap intercepts file reads, not execution, so
+		// such an autoloader has already done its work during the probe.
+		if (class_exists($className, false) || interface_exists($className, false) || trait_exists($className, false)) {
+			return $this->locateWithoutAutoloading($reflector, $identifier);
+		}
+
+		if ($locatedFiles === []) {
+			return null;
+		}
+
+		// The autoloaders asked for these files - locate the class in them statically, without
+		// executing anything.
+		$reflection = $this->autoloadSourceLocator->locateIdentifierInFiles($reflector, $identifier, $locatedFiles);
+		if ($reflection !== null) {
+			return $reflection;
+		}
+
+		// The located files do not declare the class under this name. Running the autoloaders
+		// for real can still resolve it: class_alias() whose target Composer has to autoload
+		// first asks for the *target's* file, which never declares the alias name - Laravel's
+		// Redirect alias reads the file of Illuminate\Support\Facades\Redirect. But a real run
+		// is only safe when it cannot redeclare anything: a catch-all autoloader can resolve a
+		// class name to the file of an already-loaded function of the same name and fatally
+		// include it a second time, which is what
+		// https://github.com/phpstan/phpstan/issues/14988 reported.
+		if ($this->autoloadSourceLocator->wouldIncludingFilesRedeclareSymbols($locatedFiles)) {
+			return null;
 		}
 
 		foreach ($autoloadFunctions as $autoloadFunction) {
@@ -91,22 +115,16 @@ private function locateWithoutAutoloading(Reflector $reflector, Identifier $iden
 	}
 
 	/**
-	 * Whether running these autoloaders for $className would include a file that is loaded already.
-	 *
-	 * A function of this name exists, so an autoloader that maps names to paths - a catch-all one
-	 * like PHP_CodeSniffer's, falling back to Composer's findFile() - can resolve this *class* name
-	 * to the *function's* own file. Including that file a second time fatally redeclares the
-	 * function, which is what https://github.com/phpstan/phpstan/issues/14988 reported.
-	 *
-	 * Probing under the file-read trap answers which file the autoloaders would read without
-	 * executing it, so only that case is declined. Declining on the name alone would also block
-	 * class names that merely coincide with a function - classes and functions live in separate
-	 * symbol spaces, and Laravel's facade aliases (Cache, File, Str, ...) collide with the global
-	 * helpers cache(), file() and str(). See https://github.com/phpstan/phpstan/issues/15102
+	 * Runs the autoload functions under the file-read trap and reports which files they asked
+	 * for. No file content is executed - the trap serves empty data - so the probe is free of
+	 * the side effects that make running bootstrap autoloaders for real hazardous. Mirrors
+	 * spl_autoload_call() by stopping at the first autoloader that defines the name or asks
+	 * for a file.
 	 *
 	 * @param array<int, callable(string): void> $autoloadFunctions
+	 * @return string[]
 	 */
-	private function wouldReIncludeALoadedFile(array $autoloadFunctions, string $className): bool
+	private function probeAutoloadFunctions(array $autoloadFunctions, string $className): array
 	{
 		set_error_handler(static fn (): bool => true);
 
@@ -136,21 +154,17 @@ static function () use ($autoloadFunctions, $className): array {
 			restore_error_handler();
 		}
 
-		if ($locatedFiles === []) {
-			return false;
+		if (!function_exists('opcache_invalidate')) {
+			return $locatedFiles;
 		}
 
-		// PHP canonicalises the path before it reaches a stream wrapper - a `/./` segment, a
-		// symlinked directory or an include-path-relative name all arrive resolved - so the
-		// trapped paths compare directly against get_included_files().
-		$includedFiles = get_included_files();
+		// The pseudo-include may have cached the trap's empty content; running the autoloaders
+		// for real afterwards has to compile the actual file.
 		foreach ($locatedFiles as $locatedFile) {
-			if (in_array($locatedFile, $includedFiles, true)) {
-				return true;
-			}
+			opcache_invalidate($locatedFile, true);
 		}
 
-		return false;
+		return $locatedFiles;
 	}
 
 	#[Override]

src/Reflection/BetterReflection/SourceLocator/AutoloadSourceLocator.php

@@ -168,6 +168,62 @@ public function locateIdentifier(Reflector $reflector, Identifier $identifier):
 		return null;
 	}
 
+	/**
+	 * Whether including these files for real would redeclare a class or function that is
+	 * already defined in this process - which is fatal, so the caller must not execute them.
+	 * The check is against the files' statically parsed symbols, not get_included_files():
+	 * a file-read-trap probe pseudo-includes every file it traps (the include succeeds with
+	 * empty content and registers in get_included_files() while defining nothing), so the
+	 * include list overreports what is genuinely loaded.
+	 *
+	 * @param string[] $files
+	 */
+	public function wouldIncludingFilesRedeclareSymbols(array $files): bool
+	{
+		foreach ($files as $file) {
+			if (!is_file($file)) {
+				continue;
+			}
+
+			$result = $this->fileNodesFetcher->fetchNodes($file);
+			foreach (array_keys($result->getClassNodes()) as $className) {
+				if (class_exists($className, false) || interface_exists($className, false) || trait_exists($className, false)) {
+					return true;
+				}
+			}
+
+			foreach (array_keys($result->getFunctionNodes()) as $functionName) {
+				if (function_exists($functionName)) {
+					return true;
+				}
+			}
+		}
+
+		return false;
+	}
+
+	/**
+	 * Locates the identifier in the given files without invoking any autoloader - used by
+	 * AutoloadFunctionsSourceLocator with the files its file-read-trap probe recorded.
+	 *
+	 * @param string[] $files
+	 */
+	public function locateIdentifierInFiles(Reflector $reflector, Identifier $identifier, array $files): ?Reflection
+	{
+		foreach ($files as $file) {
+			if (!is_file($file)) {
+				continue;
+			}
+
+			$reflection = $this->findReflection($reflector, $file, $identifier, null);
+			if ($reflection !== null) {
+				return $reflection;
+			}
+		}
+
+		return null;
+	}
+
 	private function findReflection(Reflector $reflector, string $file, Identifier $identifier, ?int $startLine): ?Reflection
 	{
 		$result = $this->fileNodesFetcher->fetchNodes($file);