From 48a7bbe9fdc48aeb306ce1777337e805d971eb85 Mon Sep 17 00:00:00 2001
From: Sander Muller <github@scode.nl>
Date: Wed, 5 Aug 2026 18:18:35 +0200
Subject: [PATCH] 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>
---
 .github/workflows/e2e-tests.yml               |  4 ++
 e2e/bug-14988/.gitignore                      |  1 +
 e2e/bug-14988/classes/gadget.php              | 10 +++++
 e2e/bug-14988/composer.json                   |  7 +++
 e2e/bug-14988/composer.lock                   | 18 ++++++++
 e2e/bug-14988/custom-autoloader.php           | 43 +++++++++++++++++++
 e2e/bug-14988/phpstan.neon                    | 12 ++++++
 e2e/bug-14988/pkg/bootstrap.php               |  9 ++++
 e2e/bug-14988/pkg/gadget.php                  |  8 ++++
 e2e/bug-14988/pkg/thing.php                   |  8 ++++
 e2e/bug-14988/src/probe.php                   | 24 +++++++++++
 .../AutoloadFunctionsSourceLocator.php        | 13 ++++++
 12 files changed, 157 insertions(+)
 create mode 100644 e2e/bug-14988/.gitignore
 create mode 100644 e2e/bug-14988/classes/gadget.php
 create mode 100644 e2e/bug-14988/composer.json
 create mode 100644 e2e/bug-14988/composer.lock
 create mode 100644 e2e/bug-14988/custom-autoloader.php
 create mode 100644 e2e/bug-14988/phpstan.neon
 create mode 100644 e2e/bug-14988/pkg/bootstrap.php
 create mode 100644 e2e/bug-14988/pkg/gadget.php
 create mode 100644 e2e/bug-14988/pkg/thing.php
 create mode 100644 e2e/bug-14988/src/probe.php

diff --git a/.github/workflows/e2e-tests.yml b/.github/workflows/e2e-tests.yml
index df2ca12db66..11504b44489 100644
--- a/.github/workflows/e2e-tests.yml
+++ b/.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
diff --git a/e2e/bug-14988/.gitignore b/e2e/bug-14988/.gitignore
new file mode 100644
index 00000000000..61ead86667c
--- /dev/null
+++ b/e2e/bug-14988/.gitignore
@@ -0,0 +1 @@
+/vendor
diff --git a/e2e/bug-14988/classes/gadget.php b/e2e/bug-14988/classes/gadget.php
new file mode 100644
index 00000000000..5ff2deec60c
--- /dev/null
+++ b/e2e/bug-14988/classes/gadget.php
@@ -0,0 +1,10 @@
+<?php declare(strict_types=1);
+
+namespace Redeclare\Builder;
+
+class gadget
+{
+
+	public int $size = 3;
+
+}
diff --git a/e2e/bug-14988/composer.json b/e2e/bug-14988/composer.json
new file mode 100644
index 00000000000..18fc06991e6
--- /dev/null
+++ b/e2e/bug-14988/composer.json
@@ -0,0 +1,7 @@
+{
+	"autoload": {
+		"files": [
+			"pkg/bootstrap.php"
+		]
+	}
+}
diff --git a/e2e/bug-14988/composer.lock b/e2e/bug-14988/composer.lock
new file mode 100644
index 00000000000..ba8d41762cc
--- /dev/null
+++ b/e2e/bug-14988/composer.lock
@@ -0,0 +1,18 @@
+{
+    "_readme": [
+        "This file locks the dependencies of your project to a known state",
+        "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
+        "This file is @generated automatically"
+    ],
+    "content-hash": "d751713988987e9331980363e24189ce",
+    "packages": [],
+    "packages-dev": [],
+    "aliases": [],
+    "minimum-stability": "stable",
+    "stability-flags": {},
+    "prefer-stable": false,
+    "prefer-lowest": false,
+    "platform": {},
+    "platform-dev": {},
+    "plugin-api-version": "2.9.0"
+}
diff --git a/e2e/bug-14988/custom-autoloader.php b/e2e/bug-14988/custom-autoloader.php
new file mode 100644
index 00000000000..808df847e57
--- /dev/null
+++ b/e2e/bug-14988/custom-autoloader.php
@@ -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);
diff --git a/e2e/bug-14988/phpstan.neon b/e2e/bug-14988/phpstan.neon
new file mode 100644
index 00000000000..6310a322f3d
--- /dev/null
+++ b/e2e/bug-14988/phpstan.neon
@@ -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
diff --git a/e2e/bug-14988/pkg/bootstrap.php b/e2e/bug-14988/pkg/bootstrap.php
new file mode 100644
index 00000000000..e901ff81f2f
--- /dev/null
+++ b/e2e/bug-14988/pkg/bootstrap.php
@@ -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';
+}
diff --git a/e2e/bug-14988/pkg/gadget.php b/e2e/bug-14988/pkg/gadget.php
new file mode 100644
index 00000000000..0765019e533
--- /dev/null
+++ b/e2e/bug-14988/pkg/gadget.php
@@ -0,0 +1,8 @@
+<?php declare(strict_types=1);
+
+namespace Redeclare\Builder;
+
+function gadget(): int
+{
+	return 1;
+}
diff --git a/e2e/bug-14988/pkg/thing.php b/e2e/bug-14988/pkg/thing.php
new file mode 100644
index 00000000000..33ab9ccc40c
--- /dev/null
+++ b/e2e/bug-14988/pkg/thing.php
@@ -0,0 +1,8 @@
+<?php declare(strict_types=1);
+
+namespace Redeclare\Builder;
+
+function thing(): string
+{
+	return 'thing';
+}
diff --git a/e2e/bug-14988/src/probe.php b/e2e/bug-14988/src/probe.php
new file mode 100644
index 00000000000..34d0ffe5f7b
--- /dev/null
+++ b/e2e/bug-14988/src/probe.php
@@ -0,0 +1,24 @@
+<?php declare(strict_types=1);
+
+namespace App;
+
+use Redeclare\Builder\gadget;
+
+class Probe
+{
+
+	// Probing a name that is only a function forces a hasClass() lookup, which used to re-run the
+	// custom autoloader and fatally re-include the already-loaded function file.
+	public function isThing(object $o): bool
+	{
+		return $o instanceof \Redeclare\Builder\thing;
+	}
+
+	// A class and a function may share a name in PHP. Even though the function is already loaded,
+	// the class defined in a separate file must still resolve (via the later source locators).
+	public function makeGadget(): int
+	{
+		return (new gadget())->size;
+	}
+
+}
diff --git a/src/Reflection/BetterReflection/SourceLocator/AutoloadFunctionsSourceLocator.php b/src/Reflection/BetterReflection/SourceLocator/AutoloadFunctionsSourceLocator.php
index 3da44c64bf1..750c0a175b8 100644
--- a/src/Reflection/BetterReflection/SourceLocator/AutoloadFunctionsSourceLocator.php
+++ b/src/Reflection/BetterReflection/SourceLocator/AutoloadFunctionsSourceLocator.php
@@ -9,6 +9,7 @@
 use PHPStan\BetterReflection\Reflector\Reflector;
 use PHPStan\BetterReflection\SourceLocator\Type\SourceLocator;
 use function class_exists;
+use function function_exists;
 use function interface_exists;
 use function PHPStan\autoloadFunctions;
 use function trait_exists;
@@ -35,6 +36,18 @@ public function locateIdentifier(Reflector $reflector, Identifier $identifier):
 			return null;
 		}
 
+		// If the name is already a defined function, this locator must not run the bootstrap
+		// autoloaders for it: a catch-all autoloader (e.g. PHP_CodeSniffer's, which falls back to
+		// Composer's findFile()) would resolve the name to the function's own file and plain-include
+		// it a second time - it was loaded once already, e.g. by a package that ships one function
+		// per PSR-4 path and requires it from its bootstrap - fatally redeclaring the function.
+		// Returning null only declines this locator; a class and a function may share a name in PHP,
+		// and a class that genuinely exists under this name in another file is still located by the
+		// later source locators in the chain. See https://github.com/phpstan/phpstan/issues/14988
+		if (function_exists($className)) {
+			return null;
+		}
+
 		$autoloadFunctions = autoloadFunctions();
 		foreach ($autoloadFunctions as $autoloadFunction) {
 			$autoloadFunction($className);