Keep the restarted process's OPcache private and adapt it to the php.ini

A php.ini tuned for the web server can turn the OPcache activation into
something worse than a slowdown:

- opcache.file_cache would persist this run's opcodes and, being
  validated by build id and mtime only (and the mtime checks are off
  here), serve the previous PHPStan's opcodes after an update at the
  same phar path — it is blanked.
- opcache.save_comments=0 strips the doc comments annotation readers in
  the bootstrapped project code depend on — pinned on.
- opcache.max_file_size also triggers the mtime read that refuses
  zero-mtime phar members — pinned to 0.
- opcache.file_cache_only makes blanking the file cache a fatal startup
  error and usually means shared memory is unavailable on purpose;
  opcache.preload would run the application's preload script inside
  PHPStan (there is no CLI exemption) and rejects an empty -d value.
  Both leave the configuration untouched, as before this feature.
- Buffer sizes the php.ini already grants are never lowered, and the
  interned strings buffer stays below the memory it is carved out of
  (a fatal startup error otherwise).

The raised buffers are not tuning: with the stock 128M/8M the interned
strings run out during PHPStan's own boot, the lazily loaded classes
end up uncached and uninterned, and the whole gain is gone (slevomat
app/model: 24.8s user against 23.7s with OPcache off and 23.5s with the
buffers raised). Full slevomat with 256M/64M: 613s user, 678 MB largest
forked worker, against 684s / 833 MB with OPcache off.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ek2A83bWb3Yf4CRmtvBfi4

Author: ondrejmirtes

src/Turbo/TurboProcessRestarter.php

@@ -7,6 +7,7 @@
 use function get_cfg_var;
 use function ini_get;
 use function is_string;
+use function max;
 use function pcntl_exec;
 use function php_ini_loaded_file;
 use const PHP_BINARY;
@@ -28,7 +29,7 @@
  *
  * The restarted process also gets OPcache activated — with JIT pinned off,
  * whatever the user's ini says — so forked workers share the parent's warm
- * opcode cache (see getOpcacheArgs()).
+ * opcode cache (see resolveOpcacheArgs()).
  *
  * The restart carries a marker ini entry with the extension path. It doubles
  * as the retry stop (a binary that failed to load leaves the extension
@@ -41,14 +42,23 @@ final class TurboProcessRestarter
 
 	public const EXTENSION_PATH_INI = 'phpstan.turboExtensionPath';
 
-	/** Shared memory reserved (not touched) for the opcode cache, in MB — see getOpcacheArgs() for the sizing */
+	/** Shared memory reserved (not touched) for the opcode cache, in MB — see resolveOpcacheArgs() for the sizing */
 	private const OPCACHE_MEMORY_CONSUMPTION_MB_LIMIT = 256;
 
 	/** Carved out of the memory above for interned strings, in MB */
 	private const OPCACHE_INTERNED_STRINGS_BUFFER_MB_LIMIT = 64;
 
 	private const OPCACHE_MAX_ACCELERATED_FILES_LIMIT = 20000;
 
+	/** The php.ini directives resolveOpcacheArgs() reacts to */
+	private const OPCACHE_INI_INPUTS = [
+		'opcache.file_cache_only',
+		'opcache.preload',
+		'opcache.memory_consumption',
+		'opcache.interned_strings_buffer',
+		'opcache.max_accelerated_files',
+	];
+
 	/**
 	 * The extension path this process was restarted with, null when the
 	 * process was not restarted.
@@ -120,7 +130,35 @@ public static function restartIfSuitable(array $argv): void
 	}
 
 	/**
-	 * OPcache directives for the restarted process, as `name=value` ini entries.
+	 * `-d` entries activating OPcache for the restarted process — see
+	 * resolveOpcacheArgs() for the reasoning behind each of them.
+	 *
+	 * Nothing is added when OPcache is not loaded at all — real on PHP <= 8.4,
+	 * gone on 8.5+ (always built in and loaded). Loading it from here is not
+	 * worth it: -d zend_extension=opcache emits a startup warning on builds
+	 * without the shared object, and on 8.5+ always.
+	 *
+	 * @return list<string>
+	 */
+	private static function getOpcacheArgs(): array
+	{
+		if (!extension_loaded('Zend OPcache')) {
+			return [];
+		}
+
+		$ini = [];
+		foreach (self::OPCACHE_INI_INPUTS as $name) {
+			$ini[$name] = ini_get($name);
+		}
+
+		return self::resolveOpcacheArgs($ini);
+	}
+
+	/**
+	 * OPcache directives for the restarted process, as `name=value` ini
+	 * entries, given the current values of the OPCACHE_INI_INPUTS directives
+	 * (the restarted process loads the same php.ini, so they are what it
+	 * would otherwise run with).
 	 *
 	 * The exec is paid for anyway, so it doubles as the chance to activate
 	 * OPcache, usually dormant on CLI (opcache.enable_cli defaults to off):
@@ -144,40 +182,72 @@ public static function restartIfSuitable(array $argv): void
 	 *
 	 * Timestamp checks are switched off, or nothing of PHPStan itself would be
 	 * cached: opcache_compile_file() refuses any file whose mtime it reads as
-	 * 0, and the members of the distributed phar carry exactly that (the
-	 * build normalizes them for reproducibility). It reads the mtime whenever
-	 * opcache.validate_timestamps *or* opcache.file_update_protection is on,
-	 * so both go — for a private cache that dies with the process they
-	 * revalidate nothing anyway, and skipping them also drops a stat() per
-	 * include. The uncached state is what made OPcache *slower* than no
-	 * OPcache for phar runs: code compiled under an active OPcache but not
-	 * persisted never gets its strings interned into SHM, so its type names
-	 * have no class-entry cache slot and every class-typed parameter, return
-	 * and property check falls back to a lowercased-copy class-table lookup
-	 * (measured at +27% CPU on slevomat).
+	 * 0, which is what every member of the distributed phar carried until the
+	 * build started stamping them (phar.yml). It reads the mtime whenever
+	 * opcache.validate_timestamps, opcache.file_update_protection or
+	 * opcache.max_file_size is on, so all three go — for a private cache that
+	 * dies with the process they revalidate nothing anyway, and skipping them
+	 * also drops a stat() per include. The uncached state is what made
+	 * OPcache *slower* than no OPcache for phar runs: code compiled under an
+	 * active OPcache but not persisted never gets its strings interned into
+	 * SHM, so its type names have no class-entry cache slot and every
+	 * class-typed parameter, return and property check falls back to a
+	 * lowercased-copy class-table lookup (measured at +27% CPU on slevomat).
 	 *
 	 * The buffers are raised above the stock 128M/8M/10000 for the same
 	 * reason: once any of them is exhausted, everything compiled afterwards
-	 * lands in that same uncached, uninterned state. PHPStan's own phar needs
-	 * about 35M of code; project bootstraps loaded by extensions (a Doctrine
-	 * objectManagerLoader booting the whole app, say) add hundreds of MB, and
-	 * the shared memory is only reserved, not touched, until used. It is not
-	 * sized for the largest possible project, though — an SHM reservation that
-	 * cannot be satisfied is fatal (exit code 254) in the restarted process,
-	 * with no parent left to fall back to.
+	 * lands in that same uncached, uninterned state — the stock 8M of interned
+	 * strings run out during PHPStan's own boot already, which alone costs the
+	 * whole gain. PHPStan's phar needs about 35M of code; project bootstraps
+	 * loaded by extensions (a Doctrine objectManagerLoader booting the whole
+	 * app, say) add hundreds of MB, and the shared memory is only reserved,
+	 * not touched, until used. It is not sized for the largest possible
+	 * project, though — an SHM reservation that cannot be satisfied is fatal
+	 * (exit code 254) in the restarted process, with no parent left to fall
+	 * back to. Sizes the php.ini already grants are never lowered, and the
+	 * interned strings buffer is kept below the memory it is carved out of
+	 * (another fatal startup error otherwise).
+	 *
+	 * That private cache must neither outlive the process nor reach outside
+	 * it, which is what the remaining entries guard against in a php.ini tuned
+	 * for the web server rather than for us:
+	 * - opcache.file_cache is blanked. A file cache is validated by the PHP
+	 *   build id and (only with opcache.validate_timestamps) the mtime — so
+	 *   with the checks off it would keep serving the previous PHPStan's
+	 *   opcodes after an update, the phar path being the same, and it would
+	 *   fill the web server's cache directory with this run's scripts.
+	 * - opcache.save_comments is pinned on: stripping doc comments (a common
+	 *   web tuning) breaks annotation readers in the project code the
+	 *   extensions bootstrap, which worked with OPcache dormant.
 	 *
-	 * The only case adding nothing is OPcache not being loaded at all — real
-	 * on PHP <= 8.4, gone on 8.5+ (always built in and loaded). Loading it
-	 * from here is not worth it: -d zend_extension=opcache emits a startup
-	 * warning on builds without the shared object, and on 8.5+ always.
+	 * Two configurations are left alone entirely — no OPcache entries at all,
+	 * so the restarted process runs with what the php.ini says, as before:
+	 * - opcache.file_cache_only: blanking the file cache would be a fatal
+	 *   startup error, and it usually means shared memory is unavailable on
+	 *   that host on purpose.
+	 * - opcache.preload: the application's preload script would run inside
+	 *   PHPStan (there is no CLI exemption), and it cannot be blanked with -d
+	 *   (the directive rejects an empty value).
 	 *
+	 * @param array<string, string|false> $ini
 	 * @return list<string>
 	 */
-	private static function getOpcacheArgs(): array
+	public static function resolveOpcacheArgs(array $ini): array
 	{
-		if (!extension_loaded('Zend OPcache')) {
+		if (self::isIniOn($ini['opcache.file_cache_only'] ?? false)) {
 			return [];
 		}
+		$preload = $ini['opcache.preload'] ?? false;
+		if ($preload !== false && $preload !== '') {
+			return [];
+		}
+
+		$memory = max(self::OPCACHE_MEMORY_CONSUMPTION_MB_LIMIT, self::iniInt($ini['opcache.memory_consumption'] ?? false));
+		$internedStrings = max(self::OPCACHE_INTERNED_STRINGS_BUFFER_MB_LIMIT, self::iniInt($ini['opcache.interned_strings_buffer'] ?? false));
+		if ($internedStrings >= $memory) {
+			$memory = $internedStrings + self::OPCACHE_MEMORY_CONSUMPTION_MB_LIMIT - self::OPCACHE_INTERNED_STRINGS_BUFFER_MB_LIMIT;
+		}
+		$files = max(self::OPCACHE_MAX_ACCELERATED_FILES_LIMIT, self::iniInt($ini['opcache.max_accelerated_files'] ?? false));
 
 		return [
 			'opcache.enable=1',
@@ -186,10 +256,23 @@ private static function getOpcacheArgs(): array
 			'opcache.jit_buffer_size=0',
 			'opcache.validate_timestamps=0',
 			'opcache.file_update_protection=0',
-			'opcache.memory_consumption=' . self::OPCACHE_MEMORY_CONSUMPTION_MB_LIMIT,
-			'opcache.interned_strings_buffer=' . self::OPCACHE_INTERNED_STRINGS_BUFFER_MB_LIMIT,
-			'opcache.max_accelerated_files=' . self::OPCACHE_MAX_ACCELERATED_FILES_LIMIT,
+			'opcache.max_file_size=0',
+			'opcache.file_cache=',
+			'opcache.save_comments=1',
+			'opcache.memory_consumption=' . $memory,
+			'opcache.interned_strings_buffer=' . $internedStrings,
+			'opcache.max_accelerated_files=' . $files,
 		];
 	}
 
+	private static function isIniOn(string|false $value): bool
+	{
+		return $value !== false && $value !== '' && $value !== '0';
+	}
+
+	private static function iniInt(string|false $value): int
+	{
+		return $value === false ? 0 : (int) $value;
+	}
+
 }

tests/PHPStan/Turbo/TurboProcessRestarterTest.php

@@ -0,0 +1,111 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Turbo;
+
+use PHPStan\Testing\PHPStanTestCase;
+use PHPUnit\Framework\Attributes\DataProvider;
+use function array_fill_keys;
+use function array_keys;
+
+final class TurboProcessRestarterTest extends PHPStanTestCase
+{
+
+	private const STOCK_ARGS = [
+		'opcache.enable=1',
+		'opcache.enable_cli=1',
+		'opcache.jit=disable',
+		'opcache.jit_buffer_size=0',
+		'opcache.validate_timestamps=0',
+		'opcache.file_update_protection=0',
+		'opcache.max_file_size=0',
+		'opcache.file_cache=',
+		'opcache.save_comments=1',
+		'opcache.memory_consumption=256',
+		'opcache.interned_strings_buffer=64',
+		'opcache.max_accelerated_files=20000',
+	];
+
+	/**
+	 * @return iterable<string, array{array<string, string|false>, list<string>}>
+	 */
+	public static function dataResolveOpcacheArgs(): iterable
+	{
+		$stock = [
+			'opcache.file_cache_only' => '0',
+			'opcache.preload' => '',
+			'opcache.memory_consumption' => '128',
+			'opcache.interned_strings_buffer' => '8',
+			'opcache.max_accelerated_files' => '10000',
+		];
+
+		yield 'stock php.ini' => [$stock, self::STOCK_ARGS];
+
+		yield 'directives unknown (ini_get false)' => [
+			array_fill_keys(array_keys($stock), false),
+			self::STOCK_ARGS,
+		];
+
+		// a web-tuned file cache must not persist this run's opcodes: after a
+		// PHPStan update it would serve the old ones (nothing but the mtime is
+		// validated, and validation is off here) — the same arguments blank it
+		yield 'file cache configured' => [
+			['opcache.file_cache' => '/tmp/opcache'] + $stock,
+			self::STOCK_ARGS,
+		];
+
+		// blanking the file cache would be a fatal startup error here, and SHM
+		// may be unavailable on purpose — leave the configuration alone
+		yield 'file_cache_only' => [
+			['opcache.file_cache_only' => '1'] + $stock,
+			[],
+		];
+
+		// would execute the application's preload script inside PHPStan, and
+		// cannot be blanked with -d (OnUpdateStringUnempty rejects '')
+		yield 'preload configured' => [
+			['opcache.preload' => '/var/www/config/preload.php'] + $stock,
+			[],
+		];
+
+		yield 'larger user sizes are kept' => [
+			['opcache.memory_consumption' => '512', 'opcache.interned_strings_buffer' => '96', 'opcache.max_accelerated_files' => '100000'] + $stock,
+			self::withSizes(512, 96, 100000),
+		];
+
+		yield 'smaller user sizes are raised' => [
+			['opcache.memory_consumption' => '64', 'opcache.interned_strings_buffer' => '4', 'opcache.max_accelerated_files' => '2000'] + $stock,
+			self::STOCK_ARGS,
+		];
+
+		// the interned strings buffer is carved out of memory_consumption; an
+		// interned buffer at or above it is a fatal startup error
+		yield 'user interned buffer larger than the memory' => [
+			['opcache.memory_consumption' => '128', 'opcache.interned_strings_buffer' => '300'] + $stock,
+			self::withSizes(492, 300, 20000),
+		];
+	}
+
+	/**
+	 * @param array<string, string|false> $ini
+	 * @param list<string> $expected
+	 */
+	#[DataProvider('dataResolveOpcacheArgs')]
+	public function testResolveOpcacheArgs(array $ini, array $expected): void
+	{
+		$this->assertSame($expected, TurboProcessRestarter::resolveOpcacheArgs($ini));
+	}
+
+	/**
+	 * @return list<string>
+	 */
+	private static function withSizes(int $memory, int $interned, int $files): array
+	{
+		$args = self::STOCK_ARGS;
+		$args[9] = 'opcache.memory_consumption=' . $memory;
+		$args[10] = 'opcache.interned_strings_buffer=' . $interned;
+		$args[11] = 'opcache.max_accelerated_files=' . $files;
+
+		return $args;
+	}
+
+}