Do not autoload a class whose name is an already defined function

AutoloadFunctionsSourceLocator runs the autoloaders collected from bootstrap
files to find a class, without first checking whether the name is already a
defined function. A catch-all bootstrap autoloader then resolves a name like
VeeWee\Xml\Dom\Builder\value to the file that defines the function and
plain-includes it. That file was already loaded once - veewee/xml ships one
function per PSR-4 path and requires it from its files-autoload bootstrap - so
the second include fatally redeclares the function and the worker dies with
"Cannot redeclare function ...".

The common real-world autoloader here is PHP_CodeSniffer's, loaded via
bootstrapFiles because the package ships no Composer autoload metadata; it falls
back to Composer's findFile() for any name and includes with a plain include.

The name is probed as a class and the file holds a function, so running the
autoloader cannot find a class there; it only re-includes the file. Return early
when the name is already a defined function, the same way the locator already
returns early for an existing class, interface or trait. A class that genuinely
exists under that name in another file is still found by the later source
locators in the chain.

Wrapping the autoloader call in FileReadTrapStreamWrapper (as AutoloadSourceLocator
does) was considered but is not viable here: these bootstrap autoloaders run for
real, and some read a file for its return value (a loader delegating via
"$loader = include ...; $loader->loadClass()") or write cache files, which the
trap breaks.

e2e/bug-14988 reproduces it: an unguarded one-function-per-file, a bootstrap that
requires it, and a catch-all autoloader shaped like PHP_CodeSniffer's. Before the
change the worker fatals with the redeclare; after it, analysis completes. It also
covers a class and a function that share a name in separate files (both reachable
only through that bootstrap autoloader, not Composer), asserting the class still
resolves.

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

Author: 2 people

.github/workflows/e2e-tests.yml

@@ -128,6 +128,10 @@ jobs:
               cd e2e/bug-14514
               composer install
               ../../bin/phpstan analyze bug-14515.php
+          - script: |
+              cd e2e/bug-14988
+              composer install
+              ../../bin/phpstan analyse
           - script: |
               cd e2e/bug-14724
               composer install

e2e/bug-14988/.gitignore

@@ -0,0 +1 @@
+/vendor

e2e/bug-14988/classes/gadget.php

@@ -0,0 +1,10 @@
+<?php declare(strict_types=1);
+
+namespace Redeclare\Builder;
+
+class gadget
+{
+
+	public int $size = 3;
+
+}

e2e/bug-14988/composer.json

@@ -0,0 +1,7 @@
+{
+	"autoload": {
+		"files": [
+			"pkg/bootstrap.php"
+		]
+	}
+}

e2e/bug-14988/composer.lock

@@ -0,0 +1,43 @@
+<?php declare(strict_types=1);
+
+namespace Redeclare;
+
+use function is_file;
+use function spl_autoload_register;
+use function strlen;
+use function strncmp;
+use function substr;
+
+/**
+ * Stands in for the real-world autoloader that reproduces phpstan/phpstan#14988: PHP_CodeSniffer's
+ * own autoloader, loaded via bootstrapFiles for a package that ships no Composer autoload metadata.
+ * It shares the three properties that make it fatal:
+ *
+ *  1. It is registered as a string callable ("Class::method"), which spl_autoload_functions()
+ *     normalises to ['Class', 'method'] - an array whose first element is a string, not a
+ *     ClassLoader object - so it survives bin/phpstan's Composer ClassLoader exclusion.
+ *  2. It is catch-all: it resolves names outside its own namespace.
+ *  3. It uses a plain include (not include_once), so a file already loaded is executed again.
+ */
+final class Autoloader
+{
+
+	public static function load(string $class): void
+	{
+		if (strncmp($class, 'Redeclare\\Builder\\', 18) !== 0) {
+			return;
+		}
+
+		$name = substr($class, strlen('Redeclare\\Builder\\'));
+		foreach (['/classes/', '/pkg/'] as $dir) {
+			$file = __DIR__ . $dir . $name . '.php';
+			if (is_file($file)) {
+				include $file;
+				return;
+			}
+		}
+	}
+
+}
+
+spl_autoload_register('Redeclare\\Autoloader::load', true, true);

e2e/bug-14988/custom-autoloader.php

@@ -0,0 +1,12 @@
+parameters:
+	level: 0
+	paths:
+		- src
+	bootstrapFiles:
+		- custom-autoloader.php
+	ignoreErrors:
+		# The probe deliberately references a name that is a function, not a class. The point of
+		# this fixture is that analysis completes instead of fatally re-including the function file.
+		-
+			message: '#^Class Redeclare\\Builder\\thing not found\.$#'
+			path: src/probe.php

e2e/bug-14988/phpstan.neon

@@ -0,0 +1,9 @@
+<?php declare(strict_types=1);
+
+if (!function_exists('Redeclare\Builder\thing')) {
+	require_once __DIR__ . '/thing.php';
+}
+
+if (!function_exists('Redeclare\Builder\gadget')) {
+	require_once __DIR__ . '/gadget.php';
+}

e2e/bug-14988/pkg/bootstrap.php

@@ -0,0 +1,8 @@
+<?php declare(strict_types=1);
+
+namespace Redeclare\Builder;
+
+function gadget(): int
+{
+	return 1;
+}

e2e/bug-14988/pkg/gadget.php

@@ -0,0 +1,8 @@
+<?php declare(strict_types=1);
+
+namespace Redeclare\Builder;
+
+function thing(): string
+{
+	return 'thing';
+}