Restart with OPcache's file cache when WP_CLI_OPCACHE is set - #6439

Each wp run compiles WP-CLI, WordPress and all active plugins again. PHP's own default for opcache.enable_cli is 0, though distributions, Docker images and hosts may turn it on. But even with it on, OPcache keeps compiled code in shared memory, which only lasts for one process. Only the file cache (opcache.file_cache) keeps it across runs, and it isn't set by default.

With WP_CLI_OPCACHE=1, WP-CLI now restarts PHP once with the file cache enabled. Compiled code is then stored on disk and reused by the next run.

This is the idea behind PHPStan always running with OPcache (PHPStan 2.3). It's opt-in for now, as a prototype.

How it works

• Turning it on: set WP_CLI_OPCACHE as an environment variable, or in the env: section of a config file:

  env:
    WP_CLI_OPCACHE: 1

• New bootstrap step: RestartWithOpcache runs after the config is loaded and the logger and formatter are set up. That's before the shutdown handler, the root check, --require files and packages, so those only run in the restarted process.

• composer/xdebug-handler does the restart (new dependency, ^3.0.3). The bundle already ships it via composer/composer. It:

  • writes a temporary php.ini with the current settings, including -d options and WP_CLI_PHP_ARGS;
  • passes STDIN, STDOUT, TTYs and the exit code through;
  • handles Windows and signals.

  OpcacheRestarter extends it: requiresRestart() decides when to restart, and restart() adds the OPcache options.

• Only the classes the restart needs are loaded before restarting (Composer\XdebugHandler, Composer\Pcre), through WP-CLI's own autoloader. Loading the Composer autoloader there would also include every bundled command's registration file in a process that's about to be replaced. With it, the parent took ~280 ms before restarting; now it's ~15 ms.

• When it restarts: whenever the file cache isn't in use yet. That includes PHP setups that already have opcache.enable_cli=1 without a file cache.

• Skipped when:

  • WP_CLI_OPCACHE isn't set, or OPcache isn't loaded;
  • opcache.enable=0 (it defaults to 1, so this is a deliberate opt-out, and nothing would be cached);
  • the file cache is already configured, e.g. in php.ini;
  • Xdebug is active;
  • the cache directory isn't writable, or proc_open() is disabled.

  WP-CLI then runs as before.

• Subprocesses: processes WP-CLI launches itself (launch_self(), runcommand() with launch) restart in turn. The restarted process clears xdebug-handler's restart marker, so they don't mistake themselves for a restarted process.

OPcache settings

The restarted process keeps the user's other settings. That includes OPcache settings from php.ini that had no effect while OPcache was off for the CLI, for example ones tuned for PHP-FPM. So these are always set:

opcache.memory_consumption, opcache.max_accelerated_files and other shared-memory settings don't apply with file_cache_only. opcache.blacklist_filename is kept from php.ini.

Results

hyperfine, 20 runs after 3 warmups, PHP 8.3, nightly bundle run from source, on a site with WooCommerce, Yoast, Elementor, ACF and CF7. OPcache is loaded with PHP's defaults, so opcache.enable_cli=0:

• Cost of the restart: a second PHP startup, about 25 ms here. Commands that don't load WordPress, like cli version or help, are therefore slower with it. That's one reason to keep it opt-in, or to only restart for commands that load WordPress.
• Phar: OPcache caches files inside the phar too. With the nightly phar and OPcache options passed directly, option get siteurl went from 1.19 s to 0.57 s. I haven't run this PR's restart from a phar build.

OPcache modes for option get siteurl --skip-plugins --skip-themes, with the options passed directly (no restart), 15 runs:

So setups that already have opcache.enable_cli=1 without a file cache gain the most: every run pays for OPcache's optimizer and keeps nothing, which is twice as slow as having it off.

Open questions

• Opt-in or default: the gain is large for anything that loads WordPress. A default would need a cheap way to skip the restart for commands that don't load WordPress.
• Earlier restart: restarting before the bootstrap, in php/wp-cli.php, would save another ~10 ms of the parent's work (compiling utils.php and class-wp-cli.php). But config files wouldn't be read yet, and it would need its own handling of the cache directory and autoloading.
• WP_CLI_EARLY_REQUIRE files run before the bootstrap, so they run in both processes.
• wp cli info could report whether the file cache is in use.
• Cache cleanup: OPcache separates the cache by PHP build, but nothing removes old builds' directories yet. wp cli cache clear would delete them along with the rest of the cache.

Tests

• New scenario in features/bootstrap.feature:
  • With WP_CLI_OPCACHE=1, it checks that the restarted process uses the file cache in <cache dir>/opcache, that STDIN and a memory_limit from WP_CLI_PHP_ARGS reach it, and that its exit code (3) comes back.
  • Without the variable, it checks that nothing changes.
  • With opcache.save_comments=0 and opcache.validate_timestamps=0 in the PHP settings, the restarted process still has both on.
  • With opcache.enable=0, there's no restart.
  • It then turns the restart on through wp-cli.yml.
  • If OPcache isn't loaded, the file-cache checks are skipped (OPcache's extension name contains a space, so @require-extension-* can't be used). It fails without the new step, and the save_comments check fails without the forced settings.
• Manual checks:
  • a runcommand() subprocess with launch restarts too;
  • with -d opcache.enable_cli=1 already set, it still restarts and ends up with the file cache;
  • the cache directory is created with 0700;
  • with file_cache_only, a configured opcache.preload script doesn't run, while it does with shared memory.
• Feature suites: bootstrap, runner, cli-info, cli and help pass, apart from 3 scenarios that also fail on main in this environment (Composer installs blocked by the network, and early root detection while running as root).
• Static checks: PHPUnit passes apart from the 2 FileCacheTest failures that also happen on main when run as root. PHPCS is clean, and PHPStan reports no new errors.

🤖 Generated with Claude Code

https://claude.ai/code/session_01D26yjkN2BiqCXT6p6o1WqS

Summary by CodeRabbit

• New Features
  • WP-CLI can now use PHP’s OPcache file cache when enabled with WP_CLI_OPCACHE, including when the setting is provided through wp-cli.yml.
  • If OPcache or a usable cache directory is unavailable, WP-CLI continues without the OPcache restart. Existing behavior remains unchanged when the feature is not enabled.