Lock Composer autoload around phar:// reads in forked workers

Alternative approach to making the experimental pcntl_fork() worker
path work when PHPStan is run from a .phar. Where #5669 extracts the
phar before forking and reroutes every phar:// read to disk, this
takes the opposite tack: leave PHP's built-in phar:// wrapper in
place but serialise the racy operation.

PHP's built-in phar:// stream wrapper caches a single fd for the
running .phar; after pcntl_fork() that fd's open file description
(and its seek cursor) is shared between parent and every forked
child, so concurrent lazy class loads across workers can interleave
and read garbage offsets — surfacing as spurious parse errors against
phar-internal files.

PharAutoloaderLock::install() wraps every registered Composer
ClassLoader so loadClass() acquires an exclusive flock on a tmp file
before its `include` and releases it after. Two workers can never
hold the lock simultaneously, so they can never be inside
`include 'phar://…'` simultaneously, so the cursor can't be moved
out from under either of them.

Cost: per-class load takes one flock pair. Each worker contends with
siblings only during its initial "loading wave" — a few hundred
classes touched once. After its symbol table is populated the lock
is never taken again and workers run fully parallel for the rest of
the analysis.

Covers only class autoload. Non-class phar reads
(file_get_contents('phar://…'), stat, dir iteration) still go through
the unlocked built-in wrapper; in practice those happen during boot,
which is pre-fork, so they don't race.

ParallelAnalyser and FixerApplication call the (idempotent) install()
once they have decided to take the fork path. No-op when not running
inside a phar.

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

Author: ondrejmirtes

src/Command/FixerApplication.php

@@ -25,6 +25,7 @@
 use PHPStan\Internal\DirectoryCreatorException;
 use PHPStan\Internal\HttpClientFactory;
 use PHPStan\Parallel\ForkParallelChecker;
+use PHPStan\Parallel\PharAutoloaderLock;
 use PHPStan\PhpDoc\StubFilesProvider;
 use PHPStan\Process\ForkedProcessPromise;
 use PHPStan\Process\ProcessCanceledException;
@@ -100,6 +101,7 @@ public function __construct(
 		private HttpClientFactory $httpClientFactory,
 		private ForkParallelChecker $forkParallelChecker,
 		private FixerWorkerRunner $fixerWorkerRunner,
+		private PharAutoloaderLock $pharAutoloaderLock,
 	)
 	{
 	}
@@ -457,8 +459,13 @@ private function analyse(
 			});
 		});
 
+		$useFork = $this->forkParallelChecker->isSupported();
+		if ($useFork) {
+			$this->pharAutoloaderLock->install();
+		}
+
 		$process = $this->createProcessPromise(
-			$this->forkParallelChecker->isSupported(),
+			$useFork,
 			$loop,
 			$server,
 			$mainScript,

src/Parallel/ParallelAnalyser.php

@@ -54,6 +54,7 @@ public function __construct(
 		private int $decoderBufferSize,
 		private ForkParallelChecker $forkParallelChecker,
 		private WorkerRunner $workerRunner,
+		private PharAutoloaderLock $pharAutoloaderLock,
 	)
 	{
 		$this->processTimeout = max($processTimeout, self::DEFAULT_TIMEOUT);
@@ -175,6 +176,9 @@ public function analyse(
 		};
 
 		$useFork = $this->forkParallelChecker->isSupported();
+		if ($useFork) {
+			$this->pharAutoloaderLock->install();
+		}
 
 		for ($i = 0; $i < $numberOfProcesses; $i++) {
 			if (count($jobs) === 0) {

src/Parallel/PharAutoloaderLock.php

@@ -0,0 +1,100 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Parallel;
+
+use Composer\Autoload\ClassLoader;
+use Phar;
+use PHPStan\DependencyInjection\AutowiredService;
+use function fclose;
+use function flock;
+use function fopen;
+use function getmypid;
+use function register_shutdown_function;
+use function spl_autoload_register;
+use function sys_get_temp_dir;
+use function touch;
+use function uniqid;
+use function unlink;
+use const LOCK_EX;
+use const LOCK_UN;
+
+/**
+ * Serialises Composer autoload reads from a shared phar fd so concurrent
+ * forked workers can't race on its seek cursor.
+ *
+ * When PHPStan is run from a .phar (composer-distributed install), PHP's
+ * built-in phar:// stream wrapper caches a single fd internally; after
+ * pcntl_fork() that fd's open file description (and its seek cursor) is
+ * shared between parent and every forked child, so concurrent lazy class
+ * loads across workers can interleave and read garbage offsets — surfacing
+ * as spurious parse errors against phar-internal files.
+ *
+ * The minimal-surgery fix here: wrap every registered Composer ClassLoader
+ * so that loadClass() acquires an exclusive flock on a tmp file before its
+ * `include`, and releases it after. Two workers can never be inside
+ * `include 'phar://…'` at the same time, so the cursor can't be moved out
+ * from under either of them.
+ *
+ * Cost model: per-class load takes one flock pair. A worker contends with
+ * siblings only during its initial "loading wave" — the few hundred classes
+ * it touches once. After that its symbol table is populated and the lock
+ * is never taken again, so workers run fully parallel for the rest of the
+ * analysis.
+ *
+ * Covers only autoload. Non-class phar reads — file_get_contents('phar://…')
+ * etc. — still go through the unlocked built-in wrapper; in practice those
+ * happen during boot, which is pre-fork, so they don't race. If a lazy
+ * non-class phar read does fire post-fork, the alternative extract-and-
+ * reroute approach (see #5669) is the comprehensive fix.
+ *
+ * No-op when not running inside a phar; called by ParallelAnalyser and
+ * FixerApplication right before they fork. Idempotent.
+ */
+#[AutowiredService]
+final class PharAutoloaderLock
+{
+
+	private bool $installed = false;
+
+	public function install(): void
+	{
+		if ($this->installed) {
+			return;
+		}
+		$this->installed = true;
+
+		if (Phar::running(false) === '') {
+			return;
+		}
+
+		$lockPath = sys_get_temp_dir() . '/phpstan-fork-phar-lock-' . getmypid() . '-' . uniqid();
+		touch($lockPath);
+
+		foreach (ClassLoader::getRegisteredLoaders() as $loader) {
+			$loader->unregister();
+			spl_autoload_register(static function (string $class) use ($loader, $lockPath): void {
+				$fh = fopen($lockPath, 'r');
+				if ($fh === false) {
+					$loader->loadClass($class);
+					return;
+				}
+				flock($fh, LOCK_EX);
+				try {
+					$loader->loadClass($class);
+				} finally {
+					flock($fh, LOCK_UN);
+					fclose($fh);
+				}
+			});
+		}
+
+		$parentPid = getmypid();
+		register_shutdown_function(static function () use ($parentPid, $lockPath): void {
+			if (getmypid() !== $parentPid) {
+				return;
+			}
+			@unlink($lockPath);
+		});
+	}
+
+}