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.

In the phar

php-scoper prefixes the new use Composer\Autoload\ClassLoader;, but Box leaves the class itself unprefixed, so the prefixed name matches no autoloader at all and every probe still went through the trap. The phar built for an earlier push of this PR still had the fatal for that reason — thanks to the review that caught it.

compiler/build/scoper.inc.php already strips that prefix back off in a fixed list of files; AutoloadSourceLocator.php is now on it. The list moves from the patcher closure into compiler/build/scoper-namespaces.php, next to the scoper's other lists, so that a test can read it: ScoperComposerClassLoaderTest fails when a file in src/ or bin/phpstan refers to Composer\Autoload\ClassLoader without being listed, the way ScoperClassNameStringsTest already guards class-name strings.

Checksum PHAR is expected to fail here. It runs when compiler/ changes, and it requires the phar to be byte-identical to the base's. This PR changes src/ and deliberately changes the scoping of one file. The list move on its own is output-neutral; I can split it out if you'd like that verified separately.

Paths behind a stream wrapper

Fixing the scoping exposed a second problem. The phar's own autoloader is an unprefixed ClassLoader too, and it maps PHPStan\ to phar://.../src. realpath() cannot resolve a path behind a stream wrapper, so the fast path discarded the answer, and PHPStan's own classes that were not loaded yet went missing. The extension jobs on that push failed with Call to method yes() on an unknown class PHPStan\TrinaryLogic.

A ClassLoader that answers with a stream-wrapper path is now left to the trap, which has always recorded such paths; only plain local paths take the new route. The OPcache hazard is about files on disk, so the fix still applies where it matters. AutoloadSourceLocatorTest::testClassInsidePharBehindComposerClassLoader() covers this with a tar archive standing in for the phar (PharData writes one even with phar.readonly on). It fails on the previous push and passes against the base.

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. The test runs from source, so it cannot see the scoping problem above; ScoperComposerClassLoaderTest covers that, and fails without the new list entry.

Also checked by hand on Windows, PHP 8.5.9, against a project on php-standard-library/type 6.2.1 at level 5, analysing return $o instanceof \Psl\Type\optional; with the worker's OPcache flags:

• 2.2.15 phar, and the base from source: Cannot redeclare function Psl\Type\optional()
• this PR from source: class.notFound on the instanceof line, no fatal

Applying the patchers from scoper.inc.php to AutoloadSourceLocator.php, prefixed as in the CI-built phar, leaves the import prefixed with the base config and unprefixed with this one. I could not build a full phar on Windows, so the phar built for this push is what confirms the end-to-end result.

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. Happy to look at it separately if you would like it covered.

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.

[theodorejb]

@SanderMuller Thanks for finding the phar issue. I rebased and had Claude update the commit to add AutoloadSourceLocator.php to the list of files the ClassLoader patcher un-prefixes. The list now lives in compiler/build/scoper-namespaces.php to avoid future regressions, and a new ScoperComposerClassLoaderTest fails when a file in src/ or bin/phpstan refers to Composer\Autoload\ClassLoader without being on it (the same pattern ScoperClassNameStringsTest uses). It fails without the new entry.

In regards to performance, two A/B runs each of PHPStan's own src came out within noise (70–72s with the change, 72–76s without), and the changed path only runs about 50 times per worker.

[SanderMuller]

Thanks, that fixes it. With the phar CI built from bed3f0c, the php-standard-library/type repro now reports class.notFound instead of the fatal, with and without OPcache. The new build test fails without the entry, and the phar test fails without the :// guard.

On a real project of about 4,500 files the reported errors are identical. CPU did not go up: median 140.2s before and 131.4s after, over 3 cold runs each. The full suite and make phpstan pass locally. The red Checksum PHAR job is expected here: the only file that differs between the base and PR checksum phars is AutoloadSourceLocator.php.