Ask Composer's autoloaders for the file instead of letting them include it

[theodorejb]

AutoloadSourceLocator finds which file declares a class by running the registered autoloaders behind FileReadTrapStreamWrapper, which records the path an include reached for and serves an empty script in its place. That only shadows the real file while the compiler asks the wrapper for the contents. With OPcache already holding the script it does not ask, and the file runs a second time:

Child process error (exit code 255): Fatal error: Cannot redeclare
function Psl\Type\optional() ...

That is fatal for a file declaring a function, which is the function-per-file layout of php-standard-library and azjezz/psl: their files-autoload bootstrap has already loaded every path their PSR-4 prefix also resolves to. The probe itself is legitimate — analysed code doing use Psl\Type; and calling Type\optional(...) makes PHPStan check whether that name is also a class.

2.2.13 exposed this by force-enabling OPcache in spawned workers (TurboProcessRestarter::resolveOpcacheArgs()). It already handles the opposite direction — servesParseError() and the opcache_invalidate() loop stop the trap's empty script from being cached and shadowing the real file — but the cache-hit bypass was missed.

Fix

ClassLoader::findFile() answers with the same path loadClass() would include, without running anything. Asking it, rather than arranging for the include to be harmless, means nothing is compiled and no cache is consulted — which is what makes this hold wherever PHP runs.

FileReadTrapStreamWrapper is untouched.

Ordering

Autoloaders still run in registration order. Every non-Composer autoloader runs inside the trap as before, one at a time, since an autoloader ahead of Composer's may claim a name Composer would resolve elsewhere.

Running them one at a time matters in practice: hoa/compiler registers an autoloader that sits ahead of the analysed project's loader, and an earlier revision of this patch — which gave up on the fast path at the first non-Composer autoloader — would therefore almost never have taken it.

Path resolution

findFile() concatenates the mapped prefix with the rest of the name, so its answer can carry ../ segments and mixed separators, where PHP resolves an include path before the trap ever sees it. It is resolved here to match, which locateIdentifier() relies on when it compares the located path against ReflectionClass::getFileName() to tell two same-named classes in one file apart. AutoloadSourceLocatorTest covers exactly that case and catches the difference.

On the earlier revisions

The first two versions of this PR kept the include and tried to make it safe — dropping the shared memory entry with opcache_invalidate(), then refusing the open for a file already in get_included_files(). Both passed on Windows and failed the Linux integration job, which is why the branch was force-pushed twice.

Both depend on OPcache consulting the wrapper at all, which is not something the engine promises. Asking findFile() depends on nothing of the sort: if the autoloader is never called, the file cannot be included.

Test

FileReadTrapStreamWrapperTest::testTrapSurvivesOpcacheCacheHit(), in the exec group. The failure is a fatal error and OPcache is only on in spawned processes, so it drives the real AutoloadSourceLocator in a subprocess under the worker's own OPcache flags, against a ClassLoader whose PSR-4 prefix resolves to an already-loaded file. Without the fix it reproduces the reported stack, ClassLoader->loadClass() inside withStreamWrapperOverride(). It covers:

• a name whose prefix resolves to a file the process already ran, which must not run it again;
• a name whose file nothing has loaded, which must still resolve without executing it.

Checked with OPcache on, with OPcache off, and against the pre-fix code.

What this does not cover

An autoloader that is not a Composer\Autoload\ClassLoader still goes through the trap, and is still exposed to the same OPcache behaviour. That includes wrapped loaders — Symfony's DebugClassLoader is not a ClassLoader instance even though it delegates to one.

That exposure is pre-existing rather than introduced here, and closing it would mean solving the original problem: keeping an include from running a file that is already in the opcode cache, without the engine promising to consult the stream wrapper.

Closes phpstan/phpstan#15184

🤖 Generated with Claude Code

[phpstan-bot]

This pull request has been marked as ready for review.

[SanderMuller]

The fix works from source, but in the phar the new fast path never runs, so the fatal from phpstan/phpstan#15184 is still there.

php-scoper prefixes the new import. The phar that CI built for this PR (artifact phar-file of run 34738406883) has:

use _PHPStan_6c01f7a60\Composer\Autoload\ClassLoader;

The project's autoloader is an unprefixed Composer\Autoload\ClassLoader, so the instanceof check is always false and every autoloader still goes through the trap. compiler/build/scoper.inc.php already has a patcher that removes this prefix, but only in bin/phpstan, TestCaseSourceLocatorFactory.php, PHPStanTestCase.php and BetterReflection's ComposerSourceLocator.php. I think AutoloadSourceLocator.php needs to go on that list.

Repro on macOS, PHP 8.5.8: a project with php-standard-library/type 6.x, level 5, analysing one file that does return $o instanceof \Psl\Type\optional;. With --debug:

• 2.2.15 phar: Fatal error: Cannot redeclare function Psl\Type\optional()
• this PR's CI phar: the same fatal
• this PR's CI phar with only that import unprefixed: class.notFound on the instanceof line, no fatal

On the PR head from source:

• testTrapSurvivesOpcacheCacheHit passes. With the base AutoloadSourceLocator.php it fails with Cannot redeclare function OpcacheTrap\thing(), so the test covers the bug. It cannot catch the scoping problem, because it does not run from the phar.
• The SourceLocator tests pass (73 tests), and phpcs is clean on the touched files. make phpstan reports one error, at tests/PHPStan/Type/ObjectTypeTest.php:803, which this PR does not touch.
• I suspected that realpath() changes the located path for a package installed through a symlink, as a Composer path repository does. It does not: the base and the PR both return the resolved target.

All five red checks are also red on #6564, another 2.2.x PR.

I did not run the Windows setup from the issue, and I did not measure performance.