Make fork-mode parallel workers work when PHPStan runs from a .phar

[ondrejmirtes]

Follow-up to #5663. Without this, the experimental pcntl_fork()
parallel-worker path can't be used when PHPStan is installed via
composer (i.e. running as phpstan.phar) — it surfaces as spurious
parse errors against phar-internal files:

Parse error: Unterminated comment starting line 103 in
phar:///…/phpstan.phar/vendor/react/socket/src/ConnectionInterface.php
Parse error: Unclosed '{' on line 170 in
phar:///…/phpstan.phar/vendor/react/socket/src/SocketServer.php

Why it happens

PHP's built-in phar:// stream wrapper opens the .phar once at
runtime and 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 — concurrent lazy class loads in
different workers move the cursor under each other, so a worker
fread()s the bytes belonging to a different file and the parser sees
a half-truncated source that almost parses. The corruption position
is non-deterministic but always lands at a "looks plausible" spot in
some phar-internal file.

This is OS-level fd semantics, not something PHP userland can fix by
fiddling with the existing wrapper.

How this fixes it

PharForkPreparation::prepare() runs in the parent before any
fork:

1. Phar::extractTo() the running phar into a fresh per-run tmp
   directory.
2. stream_wrapper_unregister('phar') and re-register
   PharRedirectStreamWrapper in its place.

The redirect wrapper translates every phar://…/foo access to
$extractDir/foo and delegates to ordinary disk I/O. After fork each
child opens fresh fds against ordinary files — no shared cursor, no
race. Autoload, file_get_contents, stat, directory iteration all
keep working transparently (the user code never knows it isn't talking
to phar:// anymore).

ParallelAnalyser and FixerApplication call the (idempotent)
prepare() once they have decided to take the fork path. When not
running from a phar (Phar::running(false) === '') it's a no-op. A
shutdown hook with a getmypid() guard cleans the tmp dir on parent
exit only.

Cost

• Parent: one extraction (~100ms for PHPStan's phar, ~30–80 MB in
  /tmp).
• Workers: per-read translation in the wrapper (microseconds, dwarfed
  by the saved per-worker re-boot).
• Memory: laziness preserved — children only read files they actually
  need; nothing is eagerly pre-loaded.

🤖 Generated with Claude Code