Consult bootstrap-registered custom autoloaders only after the static source locators (#6069)

phpstan-bot · web-flow · commit f896750e0934 · 2026-08-07T11:02:06.000+02:00
diff --git a/.github/workflows/e2e-tests.yml b/.github/workflows/e2e-tests.yml
@@ -132,6 +132,14 @@ jobs:
               cd e2e/bug-14988
               composer install
               ../../bin/phpstan analyse
+          - script: |
+              cd e2e/bug-12972b
+              composer install
+              ../../bin/phpstan analyze
+          - script: |
+              cd e2e/bug-12972c
+              composer install
+              ../../bin/phpstan analyze
           - script: |
               cd e2e/bug-14724
               composer install
diff --git a/bin/phpstan b/bin/phpstan
@@ -91,31 +91,15 @@ use Symfony\Component\Console\Helper\ProgressBar;
 	$autoloadFunctionsAfter = spl_autoload_functions();
 
 	if ($autoloadFunctionsBefore !== false && $autoloadFunctionsAfter !== false) {
-		$newAutoloadFunctions = [];
-		foreach ($autoloadFunctionsAfter as $after) {
-			if (
-				is_array($after)
-				&& count($after) > 0
-			) {
-				if (is_object($after[0])
-					&& get_class($after[0]) === \Composer\Autoload\ClassLoader::class
-				) {
-					continue;
-				}
-				if ($after[0] === 'PHPStan\\PharAutoloader') {
-					continue;
-				}
-			}
-			foreach ($autoloadFunctionsBefore as $before) {
-				if ($after === $before) {
-					continue 2;
-				}
-			}
-
-			$newAutoloadFunctions[] = $after;
-		}
-
-		$GLOBALS['__phpstanAutoloadFunctions'] = $newAutoloadFunctions;
+		$collectedAutoloadFunctions = \PHPStan\collectNewAutoloadFunctions($autoloadFunctionsBefore, $autoloadFunctionsAfter);
+		$GLOBALS['__phpstanAutoloadFunctions'] = array_merge(
+			$GLOBALS['__phpstanAutoloadFunctions'] ?? [],
+			$collectedAutoloadFunctions['appended'],
+		);
+		$GLOBALS['__phpstanAutoloadFunctionsPrependedToComposer'] = array_merge(
+			$GLOBALS['__phpstanAutoloadFunctionsPrependedToComposer'] ?? [],
+			$collectedAutoloadFunctions['prepended'],
+		);
 	}
 
 	$devOrPharLoader->register(true);
diff --git a/compiler/build/scoper.inc.php b/compiler/build/scoper.inc.php
@@ -141,6 +141,7 @@ function (string $filePath, string $prefix, string $content): string {
 		function (string $filePath, string $prefix, string $content): string {
 			if (!in_array($filePath, [
 				'bin/phpstan',
+				'src/autoloadFunctions.php',
 				'src/Testing/TestCaseSourceLocatorFactory.php',
 				'src/Testing/PHPStanTestCase.php',
 				'vendor/ondrejmirtes/better-reflection/src/SourceLocator/Type/ComposerSourceLocator.php',
diff --git a/e2e/bug-12972b/.gitignore b/e2e/bug-12972b/.gitignore
@@ -0,0 +1,2 @@
+/vendor/
+composer.lock
diff --git a/e2e/bug-12972b/autoloader.php b/e2e/bug-12972b/autoloader.php
@@ -0,0 +1,20 @@
+<?php
+
+require_once __DIR__ . '/vendor/autoload.php';
+
+// Registered *after* Composer's class loader: the third argument (prepend)
+// defaults to false, so this ends up at the back of the spl_autoload queue.
+//
+// \other12972\MyClass is part of Composer's class map (see composer.json), so at
+// runtime Composer's class loader resolves it first and this autoloader is never
+// invoked for it - running `php real-world.php` therefore never throws.
+//
+// PHPStan must mirror that order: the Composer class map source locator has to
+// resolve the class before this bootstrap autoloader is consulted. Analysing the
+// project used to invoke this autoloader first, hitting the LogicException and
+// crashing with an internal error that cannot happen at runtime.
+spl_autoload_register(function($class) {
+	if ($class === \other12972\MyClass::class) {
+		throw new LogicException('this should not happen');
+	}
+});
diff --git a/e2e/bug-12972b/composer.json b/e2e/bug-12972b/composer.json
@@ -0,0 +1,7 @@
+{
+	"autoload": {
+		"classmap": [
+			"src/"
+		]
+	}
+}
diff --git a/e2e/bug-12972b/phpstan.dist.neon b/e2e/bug-12972b/phpstan.dist.neon
@@ -0,0 +1,8 @@
+parameters:
+    level: 9
+
+    paths:
+        - src
+
+    bootstrapFiles:
+        - autoloader.php
diff --git a/e2e/bug-12972b/real-world.php b/e2e/bug-12972b/real-world.php
@@ -0,0 +1,6 @@
+<?php
+
+require 'autoloader.php';
+
+$root = new \Foo12972\MyRoot();
+$root->doBar(new \other12972\MyClass());
diff --git a/e2e/bug-12972b/src/folder/file2.php b/e2e/bug-12972b/src/folder/file2.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace Foo12972;
+
+use other12972\MyClass;
+
+class MyRoot {
+	function doBar(MyClass $myClass):void {}
+}
diff --git a/e2e/bug-12972b/src/other/file.php b/e2e/bug-12972b/src/other/file.php
@@ -0,0 +1,10 @@
+<?php
+
+namespace other12972;
+
+class MyClass {
+	public function doSomething(): int
+	{
+		return 1;
+	}
+}
diff --git a/e2e/bug-12972c/.gitignore b/e2e/bug-12972c/.gitignore
@@ -0,0 +1,2 @@
+/vendor/
+composer.lock
diff --git a/e2e/bug-12972c/autoloader.php b/e2e/bug-12972c/autoloader.php
@@ -0,0 +1,12 @@
+<?php
+
+require_once __DIR__ . '/vendor/autoload.php';
+
+// Registered *before* Composer's class loader (third argument = prepend).
+// At runtime this resolves \shared12972c\Thing before Composer ever sees it,
+// so PHPStan must consult it before the Composer class map as well.
+spl_autoload_register(function ($class) {
+	if ($class === \shared12972c\Thing::class) {
+		require __DIR__ . '/prepended/Thing.php';
+	}
+}, true, true);
diff --git a/e2e/bug-12972c/classmap/Thing.php b/e2e/bug-12972c/classmap/Thing.php
@@ -0,0 +1,10 @@
+<?php
+
+namespace shared12972c;
+
+class Thing {
+	public function composerOnly(): int
+	{
+		return 1;
+	}
+}
diff --git a/e2e/bug-12972c/composer.json b/e2e/bug-12972c/composer.json
@@ -0,0 +1,7 @@
+{
+	"autoload": {
+		"classmap": [
+			"classmap/"
+		]
+	}
+}
diff --git a/e2e/bug-12972c/consumer/consumer.php b/e2e/bug-12972c/consumer/consumer.php
@@ -0,0 +1,10 @@
+<?php
+
+namespace consumer12972c;
+
+use shared12972c\Thing;
+
+function run(Thing $thing): int
+{
+	return $thing->prependedOnly();
+}
diff --git a/e2e/bug-12972c/phpstan.dist.neon b/e2e/bug-12972c/phpstan.dist.neon
@@ -0,0 +1,8 @@
+parameters:
+    level: 9
+
+    paths:
+        - consumer
+
+    bootstrapFiles:
+        - autoloader.php
diff --git a/e2e/bug-12972c/prepended/Thing.php b/e2e/bug-12972c/prepended/Thing.php
@@ -0,0 +1,10 @@
+<?php
+
+namespace shared12972c;
+
+class Thing {
+	public function prependedOnly(): int
+	{
+		return 2;
+	}
+}
diff --git a/e2e/bug-12972c/real-world.php b/e2e/bug-12972c/real-world.php
@@ -0,0 +1,6 @@
+<?php
+
+require 'autoloader.php';
+
+$thing = new \shared12972c\Thing();
+echo $thing->prependedOnly(), "\n";
diff --git a/src/Command/CommandHelper.php b/src/Command/CommandHelper.php
@@ -41,6 +41,7 @@
 use function array_filter;
 use function array_key_exists;
 use function array_map;
+use function array_merge;
 use function array_values;
 use function class_exists;
 use function count;
@@ -56,6 +57,7 @@
 use function is_file;
 use function is_readable;
 use function is_string;
+use function PHPStan\collectNewAutoloadFunctions;
 use function register_shutdown_function;
 use function spl_autoload_functions;
 use function sprintf;
@@ -526,18 +528,15 @@ public static function begin(
 		$autoloadFunctionsAfter = spl_autoload_functions();
 
 		if ($autoloadFunctionsBefore !== false && $autoloadFunctionsAfter !== false) {
-			$newAutoloadFunctions = $GLOBALS['__phpstanAutoloadFunctions'] ?? [];
-			foreach ($autoloadFunctionsAfter as $after) {
-				foreach ($autoloadFunctionsBefore as $before) {
-					if ($after === $before) {
-						continue 2;
-					}
-				}
-
-				$newAutoloadFunctions[] = $after;
-			}
-
-			$GLOBALS['__phpstanAutoloadFunctions'] = $newAutoloadFunctions;
+			$collectedAutoloadFunctions = collectNewAutoloadFunctions($autoloadFunctionsBefore, $autoloadFunctionsAfter);
+			$GLOBALS['__phpstanAutoloadFunctions'] = array_merge(
+				$GLOBALS['__phpstanAutoloadFunctions'] ?? [],
+				$collectedAutoloadFunctions['appended'],
+			);
+			$GLOBALS['__phpstanAutoloadFunctionsPrependedToComposer'] = array_merge(
+				$GLOBALS['__phpstanAutoloadFunctionsPrependedToComposer'] ?? [],
+				$collectedAutoloadFunctions['prepended'],
+			);
 		}
 
 		if (PHP_VERSION_ID >= 80000) {
diff --git a/src/Reflection/BetterReflection/BetterReflectionSourceLocatorFactory.php b/src/Reflection/BetterReflection/BetterReflectionSourceLocatorFactory.php
@@ -98,12 +98,18 @@ public function create(): SourceLocator
 			}
 
 			$astLocator = new Locator($this->parser);
+
+			// Custom autoloaders that bootstrap files registered *before* Composer's
+			// class loader (e.g. spl_autoload_register($fn, true, true)) run before
+			// Composer resolves the class at runtime, so they are consulted before
+			// the static source locators below - mirroring that runtime order.
 			$locators[] = new AutoloadFunctionsSourceLocator(
 				new AutoloadSourceLocator($this->fileNodesFetcher, false),
 				new ReflectionClassSourceLocator(
 					$astLocator,
 					$this->reflectionSourceStubber,
 				),
+				true,
 			);
 
 			$analysedDirectories = [];
@@ -184,6 +190,22 @@ public function create(): SourceLocator
 				$this->phpVersion,
 			));
 
+			// Custom autoloaders registered *after* Composer's class loader are
+			// consulted only as a fallback, after the static locators above
+			// (analysed files, Composer class map/PSR-4, PHP internals). At runtime
+			// Composer's class loader resolves such classes first, so these custom
+			// autoloaders are never invoked for them - invoking them eagerly here
+			// would run code paths that cannot happen at runtime. They remain useful
+			// for classes that only a custom autoloader can produce (e.g. eval'd).
+			$locators[] = new AutoloadFunctionsSourceLocator(
+				new AutoloadSourceLocator($this->fileNodesFetcher, false),
+				new ReflectionClassSourceLocator(
+					$astLocator,
+					$this->reflectionSourceStubber,
+				),
+				false,
+			);
+
 			$locators[] = new AutoloadSourceLocator($this->fileNodesFetcher, true);
 			$locators[] = new PhpVersionBlacklistSourceLocator(new PhpInternalSourceLocator($astLocator, $this->reflectionSourceStubber), $this->phpstormStubsSourceStubber);
 			$locators[] = new PhpVersionBlacklistSourceLocator(new EvaledCodeSourceLocator($astLocator, $this->reflectionSourceStubber), $this->phpstormStubsSourceStubber);
diff --git a/src/Reflection/BetterReflection/SourceLocator/AutoloadFunctionsSourceLocator.php b/src/Reflection/BetterReflection/SourceLocator/AutoloadFunctionsSourceLocator.php
@@ -12,14 +12,21 @@
 use function function_exists;
 use function interface_exists;
 use function PHPStan\autoloadFunctions;
+use function PHPStan\autoloadFunctionsPrependedToComposer;
 use function trait_exists;
 
 final class AutoloadFunctionsSourceLocator implements SourceLocator
 {
 
+	/**
+	 * @param bool $prependedToComposer When true, consult only the autoloaders
+	 *   registered before Composer's class loader (prepended); otherwise consult
+	 *   the ones registered after it (appended).
+	 */
 	public function __construct(
 		private AutoloadSourceLocator $autoloadSourceLocator,
 		private ReflectionClassSourceLocator $reflectionClassSourceLocator,
+		private bool $prependedToComposer,
 	)
 	{
 	}
@@ -48,7 +55,9 @@ public function locateIdentifier(Reflector $reflector, Identifier $identifier):
 			return null;
 		}
 
-		$autoloadFunctions = autoloadFunctions();
+		$autoloadFunctions = $this->prependedToComposer
+			? autoloadFunctionsPrependedToComposer()
+			: autoloadFunctions();
 		foreach ($autoloadFunctions as $autoloadFunction) {
 			$autoloadFunction($className);
 			$reflection = $this->autoloadSourceLocator->locateIdentifier($reflector, $identifier);
diff --git a/src/autoloadFunctions.php b/src/autoloadFunctions.php
diff --git a/tests/PHPStan/CollectNewAutoloadFunctionsTest.php b/tests/PHPStan/CollectNewAutoloadFunctionsTest.php

-Original file line number
+Diff line change
@@ @@ -0,0 +1,7 @@ @@
 +{
 +	"autoload": {
 +		"classmap": [
 +			"src/"
 +		]
 +	}
 +}