Do not let a bootstrap autoloader's exception abort the analysis

Both source locators that ask the registered autoloaders for a class walk the
whole spl queue, which is not the order PHP uses: at runtime the class loader
that resolves the class first means the other autoloaders are never invoked for
that name. An autoloader that throws when the file it found does not declare
the class it was asked for therefore throws here for names it can never see at
runtime, and the exception surfaces as an internal error that aborts the file.
Two widely used ones do that - symfony/error-handler's DebugClassLoader, which
throws a RuntimeException in four conditions, and Yii 2's Yii::autoload(),
which throws an UnknownClassException when the file it included did not declare
the class and YII_DEBUG is on.

Swallowing it lets the remaining autoloaders and source locators take their
turn, so the class is resolved the way it is at runtime, or reported as not
found. The trapped loop in AutoloadSourceLocator has the same defect; it
predates the recently reverted work and is fixed here too, since fixing only
one of the two leaves any name no static locator resolves still aborting.

Unlike the reverted attempts this changes neither the order of the locators nor
the way autoloaders are run, and it declines nothing by name.

e2e/debug-class-loader is the DebugClassLoader case with the real package: an
internal error before, the unknown class reported after. e2e/bug-12972b, the
project phpstan/phpstan#14976 is about, is re-enabled.

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

Author: SanderMuller

.github/workflows/e2e-tests.yml

@@ -219,15 +219,19 @@ jobs:
               cd e2e/bug-14514
               composer install
               ../../bin/phpstan analyze bug-14515.php
-          # Fails since the revert of the bootstrap autoloader changes:
+          # Fails until https://github.com/phpstan/phpstan/issues/14988 is fixed again:
           # - script: |
           #     cd e2e/bug-14988
           #     composer install
           #     ../../bin/phpstan analyse
-          # - script: |
-          #     cd e2e/bug-12972b
-          #     composer install
-          #     ../../bin/phpstan analyze
+          - script: |
+              cd e2e/bug-12972b
+              composer install
+              ../../bin/phpstan analyze
+          - script: |
+              cd e2e/debug-class-loader
+              composer install
+              ../../bin/phpstan analyze
           - script: |
               cd e2e/bug-12972c
               composer install

e2e/debug-class-loader/.gitignore

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

e2e/debug-class-loader/bootstrap.php

@@ -0,0 +1,8 @@
+<?php declare(strict_types = 1);
+
+// What a Symfony application's entry script does in dev: DebugClassLoader wraps every
+// registered autoloader and throws a RuntimeException when the file it found does not
+// declare the class it was asked for, or when the case does not match.
+require_once __DIR__ . '/vendor/autoload.php';
+
+Symfony\Component\ErrorHandler\DebugClassLoader::enable();

e2e/debug-class-loader/composer.json

@@ -0,0 +1,10 @@
+{
+	"require": {
+		"symfony/error-handler": "^7.0"
+	},
+	"autoload": {
+		"psr-4": {
+			"DebugClassLoaderE2e\\": "src/"
+		}
+	}
+}

e2e/debug-class-loader/phpstan.dist.neon

@@ -0,0 +1,12 @@
+parameters:
+	level: 6
+	bootstrapFiles:
+		- bootstrap.php
+	paths:
+		- test.php
+	ignoreErrors:
+		# The point of this project is that analysis completes and reports the unknown class
+		# instead of dying inside the autoloader.
+		-
+			message: '#^Parameter \$widget of method DebugClassLoaderE2e\\Consumer\:\:doFoo\(\) has invalid type DebugClassLoaderE2e\\Widget\.$#'
+			path: test.php

e2e/debug-class-loader/src/Widget.php

@@ -0,0 +1,10 @@
+<?php declare(strict_types = 1);
+
+namespace DebugClassLoaderE2e;
+
+// The declared name does not match the file name, so Composer's PSR-4 map sends
+// DebugClassLoaderE2e\Widget to this file and DebugClassLoader throws for it.
+class Widgets
+{
+
+}

e2e/debug-class-loader/test.php

@@ -0,0 +1,17 @@
+<?php declare(strict_types = 1);
+
+namespace DebugClassLoaderE2e;
+
+class Consumer
+{
+
+	// Nothing ever instantiates the mistyped name, so no autoloader is invoked for it at
+	// runtime. PHPStan resolves every name it sees, so it does ask - and the exception used
+	// to abort the analysis of this file with an internal error instead of reporting the
+	// unknown class. See https://github.com/phpstan/phpstan/issues/14976
+	/** @param Widget $widget */
+	public function doFoo($widget): void
+	{
+	}
+
+}

src/Reflection/BetterReflection/SourceLocator/AutoloadFunctionsSourceLocator.php

@@ -8,6 +8,7 @@
 use PHPStan\BetterReflection\Reflection\Reflection;
 use PHPStan\BetterReflection\Reflector\Reflector;
 use PHPStan\BetterReflection\SourceLocator\Type\SourceLocator;
+use Throwable;
 use function class_exists;
 use function interface_exists;
 use function PHPStan\autoloadFunctions;
@@ -37,7 +38,19 @@ public function locateIdentifier(Reflector $reflector, Identifier $identifier):
 
 		$autoloadFunctions = autoloadFunctions();
 		foreach ($autoloadFunctions as $autoloadFunction) {
-			$autoloadFunction($className);
+			try {
+				$autoloadFunction($className);
+			} catch (Throwable) {
+				// This locator asks every bootstrap-registered autoloader for the class, which is not
+				// the order PHP uses: at runtime the class loader that resolves the class first is
+				// often another one, so an autoloader that throws for names outside its own scope is
+				// never invoked for them and its exception cannot happen. Letting it propagate here
+				// aborts the analysis of the file with an internal error instead, so it is swallowed
+				// and the remaining autoloaders and source locators get their turn. The class may
+				// still have been defined before the throw, so the locators below run either way.
+				// See https://github.com/phpstan/phpstan/issues/14976
+			}
+
 			$reflection = $this->autoloadSourceLocator->locateIdentifier($reflector, $identifier);
 			if ($reflection !== null) {
 				return $reflection;

src/Reflection/BetterReflection/SourceLocator/AutoloadSourceLocator.php

@@ -3,7 +3,6 @@
 namespace PHPStan\Reflection\BetterReflection\SourceLocator;
 
 use Override;
-use ParseError;
 use PhpParser\Node\Arg;
 use PhpParser\Node\Expr\FuncCall;
 use PhpParser\Node\Name;
@@ -23,6 +22,7 @@
 use PHPStan\Type\ConstantTypeHelper;
 use ReflectionClass;
 use ReflectionFunction;
+use Throwable;
 use function array_key_exists;
 use function array_keys;
 use function class_exists;
@@ -346,10 +346,15 @@ static function () use ($className): ?array {
 					foreach ($functions as $preExistingAutoloader) {
 						try {
 							$preExistingAutoloader($className);
-						} catch (ParseError) {
-							// the trap served a parse error instead of the empty
-							// script, see FileReadTrapStreamWrapper::stream_read();
-							// the file was recorded before the include compiled it
+						} catch (Throwable) {
+							// Two unrelated throws land here, and neither one means the class was not found.
+							// The trap can serve a parse error instead of the empty script, see
+							// FileReadTrapStreamWrapper::stream_read(). And asking every registered
+							// autoloader for the class is not the order PHP uses, so an autoloader that
+							// throws for names outside its own scope throws here for names it is never
+							// invoked for at runtime. Either exception would abort the analysis of the file
+							// with an internal error, so both are swallowed - the file the autoloader asked
+							// for is recorded by the trap before the throw.
 						}
 
 						/**

tests/PHPStan/Reflection/BetterReflection/SourceLocator/AutoloadFunctionsSourceLocatorTest.php

@@ -0,0 +1,97 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Reflection\BetterReflection\SourceLocator;
+
+use LogicException;
+use PhpParser\PrettyPrinter\Standard;
+use PHPStan\BetterReflection\Identifier\Identifier;
+use PHPStan\BetterReflection\Identifier\IdentifierType;
+use PHPStan\BetterReflection\Reflector\DefaultReflector;
+use PHPStan\BetterReflection\SourceLocator\Ast\Locator;
+use PHPStan\BetterReflection\SourceLocator\SourceStubber\ReflectionSourceStubber;
+use PHPStan\Testing\PHPStanTestCase;
+use TestSingleFileSourceLocator\AFoo;
+use function class_alias;
+use function class_exists;
+
+class AutoloadFunctionsSourceLocatorTest extends PHPStanTestCase
+{
+
+	/**
+	 * A bootstrap autoloader that throws for names outside its own scope must not abort the
+	 * analysis: this locator asks every registered autoloader, while at runtime the class loader
+	 * that resolves the class first means the throwing one is never invoked for that name.
+	 *
+	 * @see https://github.com/phpstan/phpstan/issues/14976
+	 */
+	public function testAThrowingAutoloaderDoesNotStopTheRemainingOnes(): void
+	{
+		require_once __DIR__ . '/data/a.php';
+		$this->assertFalse(class_exists('ThrowingAutoloaderAlias', false), 'precondition: the alias does not exist yet');
+
+		$GLOBALS['__phpstanAutoloadFunctions'] = [
+			static function (string $class): void {
+				throw new LogicException('this should not happen');
+			},
+			static function (string $class): void {
+				if ($class !== 'ThrowingAutoloaderAlias') {
+					return;
+				}
+
+				class_alias(AFoo::class, 'ThrowingAutoloaderAlias');
+			},
+		];
+
+		try {
+			$locator = $this->createLocator();
+			$reflection = $locator->locateIdentifier(
+				new DefaultReflector($locator),
+				new Identifier('ThrowingAutoloaderAlias', new IdentifierType(IdentifierType::IDENTIFIER_CLASS)),
+			);
+
+			$this->assertNotNull($reflection, 'the class defined by the second autoloader should be located');
+			$this->assertSame(AFoo::class, $reflection->getName());
+		} finally {
+			unset($GLOBALS['__phpstanAutoloadFunctions']);
+		}
+	}
+
+	/**
+	 * Nothing resolves the name, so the locator declines - the point is that it declines instead of
+	 * letting the autoloader's exception surface as an internal error.
+	 */
+	public function testAThrowingAutoloaderMakesTheLocatorDecline(): void
+	{
+		$GLOBALS['__phpstanAutoloadFunctions'] = [
+			static function (string $class): void {
+				throw new LogicException('this should not happen');
+			},
+		];
+
+		try {
+			$locator = $this->createLocator();
+			$reflection = $locator->locateIdentifier(
+				new DefaultReflector($locator),
+				new Identifier('NeverDefinedByAnyAutoloader', new IdentifierType(IdentifierType::IDENTIFIER_CLASS)),
+			);
+
+			$this->assertNull($reflection);
+		} finally {
+			unset($GLOBALS['__phpstanAutoloadFunctions']);
+		}
+	}
+
+	private function createLocator(): AutoloadFunctionsSourceLocator
+	{
+		$container = self::getContainer();
+
+		return new AutoloadFunctionsSourceLocator(
+			new AutoloadSourceLocator($container->getByType(FileNodesFetcher::class), false),
+			new ReflectionClassSourceLocator(
+				new Locator($container->getService('phpParserDecorator')),
+				new ReflectionSourceStubber(new Standard()),
+			),
+		);
+	}
+
+}