Native PHP worker pool on all platforms (#3602)

## Related issues

<!--
Link a related issue to this PR. If the PR does not immediately resolve
the issue,
for example, it requires a separate deployment to production, avoid
using the "Fixes" keyword and use "Related to" instead.
-->

- Fixes #

## How AI was used in this PR

<!--
Help reviewers understand what to look for and verify that you've
reviewed the code yourself.
-->



## Proposed Changes

Using `PHP_CLI_SERVER_WORKERS` for concurrency is only supported on
macOS and Linux. We want concurrency on Windows, too. This PR
accomplishes that by implementing a Node.js HTTP load balancer that
proxies requests to a fixed pool of 4 `php -S` processes. This works
surprisingly well in our testing.

In our benchmarks, this solution yields ~30% performance improvement on
Windows compared to Playground.

## Testing Instructions

<!--
Add as many details as possible to help others reproduce the issue and
test the fix.
"Before / After" screenshots can also be very helpful when the change is
visual.
-->

CI should pass

## Pre-merge Checklist

<!--
Complete applicable items on this checklist **before** merging into
trunk. Inapplicable items can be left unchecked.

Both the PR author and reviewer are responsible for ensuring the
checklist is completed.
-->

- [ ] Have you checked for TypeScript, React or other console errors?

---------

Co-authored-by: Fredrik Rombach Ekelund <fredrik.rombach.ekelund@automattic.com>
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
Co-authored-by: Fredrik Rombach Ekelund <fredrik@f26d.dev>

Author: 3 people

.buildkite/commands/run-e2e-tests.sh

@@ -152,8 +152,15 @@ if [ "$PLATFORM" = "linux" ]; then
     # right-edge content (e.g. the preferences Save button) below the fold
     # for the split-pane settings layout. 1920x1080 matches a typical
     # desktop and avoids relying on scroll-into-view.
+    inner_exit=0
     xvfb-run -a -s "-screen 0 1920x1080x24" \
-      npx playwright test --max-failures=1 --output=/tmp/test-results
+      npx playwright test --max-failures=1 --output=/tmp/test-results || inner_exit=$?
+    # On failure, collect daemon logs into /tmp/test-results (copied to the
+    # artifact dir below). $HOME here is the node user that ran the tests.
+    if [ "$inner_exit" -ne 0 ] && [ -d "$HOME/.studio/daemon/logs" ]; then
+      cp -r "$HOME/.studio/daemon/logs" /tmp/test-results/daemon-logs || true
+    fi
+    exit "$inner_exit"
   ' || test_exit=$?
 
   if [ -d /tmp/test-results ]; then
@@ -168,5 +175,15 @@ else
   npx playwright install
 
   echo 'Running Playwright tests...'
-  npx playwright test
+  # Capture the exit code so a failure doesn't trip `set -e` before we collect
+  # the daemon logs (~/.studio/daemon/logs) for artifact upload.
+  test_exit=0
+  npx playwright test || test_exit=$?
+
+  if [ "$test_exit" -ne 0 ] && [ -d "$HOME/.studio/daemon/logs" ]; then
+    mkdir -p test-results/daemon-logs
+    cp -r "$HOME/.studio/daemon/logs/." test-results/daemon-logs/ || true
+  fi
+
+  exit "$test_exit"
 fi

.buildkite/pipeline.yml

@@ -12,6 +12,7 @@ e2e_config: &e2e_config
     - test-results/**/*.zip
     - test-results/**/*.png
     - test-results/**/*error-context.md
+    - test-results/daemon-logs/**/*.log
   plugins: [$CI_TOOLKIT_PLUGIN, $NVM_PLUGIN]
   agents:
     queue: "{{matrix.platform}}"
@@ -101,6 +102,10 @@ steps:
           STUDIO_RUNTIME: native-php
         if: (build.branch == 'trunk' || build.tag =~ /^v[0-9]+/ || !build.pull_request.draft) && build.pull_request.labels includes 'native-php'
 
+  # Linux E2E tests run on the shared `default` queue inside a Debian Node
+  # container — the same pattern the Linux build/unit-test steps use. Kept as
+  # a separate step (rather than another matrix entry on *e2e_config) because
+  # Mac and Windows share queue/plugin defaults that Linux doesn't.
       # Linux E2E tests run on the shared `default` queue inside a Debian Node
       # container — the same pattern the Linux build/unit-test steps use. Kept as
       # a separate step (rather than another matrix entry on *e2e_config) because
@@ -119,6 +124,7 @@ steps:
           - test-results/**/*.zip
           - test-results/**/*.png
           - test-results/**/*error-context.md
+          - test-results/daemon-logs/**/*.log
         env:
           DEBUG: "pw:browser"
         # TEMP(rsm-2593): if: removed to force E2E on every push while iterating on Linux E2E setup. Revert before merge.
@@ -140,6 +146,7 @@ steps:
           - test-results/**/*.zip
           - test-results/**/*.png
           - test-results/**/*error-context.md
+          - test-results/daemon-logs/**/*.log
         env:
           DEBUG: "pw:browser"
           STUDIO_RUNTIME: native-php

apps/cli/commands/wp.ts

@@ -11,7 +11,8 @@ import { connectToDaemon, disconnectFromDaemon } from 'cli/lib/daemon-client';
 import { getPhpBinaryPath, getWpCliPharPath } from 'cli/lib/dependency-management/paths';
 import { ensurePhpBinaryAvailable } from 'cli/lib/dependency-management/php-binary';
 import { getSiteRuntime } from 'cli/lib/feature-flags';
-import { getDefaultPhpArgs } from 'cli/lib/native-php';
+import { getDefaultPhpArgs } from 'cli/lib/native-php/config';
+import { DETACH_FOR_GROUP_KILL, reapPhpTreeOnInterrupt } from 'cli/lib/native-php/php-process';
 import { runWpCliCommand, runGlobalWpCliCommand, WpCliResponse } from 'cli/lib/run-wp-cli-command';
 import { validatePhpVersion } from 'cli/lib/utils';
 import { isServerRunning, sendWpCliCommand } from 'cli/lib/wordpress-server-manager';
@@ -58,18 +59,28 @@ async function runNativePhpWpCliCommand( site: SiteData, args: string[] ): Promi
 		{
 			cwd: site.path,
 			stdio: 'inherit',
+			detached: DETACH_FOR_GROUP_KILL,
 		}
 	);
 
-	const { code, signal } = await new Promise< {
-		code: number | null;
-		signal: NodeJS.Signals | null;
-	} >( ( resolve, reject ) => {
-		child.once( 'error', reject );
-		child.once( 'exit', ( exitCode, exitSignal ) =>
-			resolve( { code: exitCode, signal: exitSignal } )
-		);
-	} );
+	// Reap php.exe and any subprocess it spawned if this command is interrupted before the child exits.
+	const removeReaper = reapPhpTreeOnInterrupt( child );
+
+	let code: number | null;
+	let signal: NodeJS.Signals | null;
+	try {
+		( { code, signal } = await new Promise< {
+			code: number | null;
+			signal: NodeJS.Signals | null;
+		} >( ( resolve, reject ) => {
+			child.once( 'error', reject );
+			child.once( 'exit', ( exitCode, exitSignal ) =>
+				resolve( { code: exitCode, signal: exitSignal } )
+			);
+		} ) );
+	} finally {
+		removeReaper();
+	}
 
 	if ( signal ) {
 		process.kill( process.pid, signal );

apps/cli/lib/dependency-management/php-binary.ts

@@ -11,7 +11,7 @@ import {
 	type PhpBinaryDownloadInfo,
 	type NativePhpSupportedVersion,
 } from '@studio/common/lib/php-binary-metadata';
-import { ensureNativePhpIniFiles } from '../native-php';
+import { ensureNativePhpIniFiles } from 'cli/lib/native-php/config';
 import { getPhpBinaryPath } from './paths';
 import type { SupportedPHPVersion } from '@studio/common/types/php-versions';
 

apps/cli/lib/native-php/blueprints.ts

@@ -0,0 +1,89 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getBlueprintsPharPath } from 'cli/lib/dependency-management/paths';
+import { runPhpCommand } from './php-process';
+import type { NativePhpSupportedVersion } from '@studio/common/lib/php-binary-metadata';
+import type { ServerConfig } from 'cli/lib/types/wordpress-server-ipc';
+
+export async function runBlueprint(
+	config: ServerConfig,
+	blueprint: NonNullable< ServerConfig[ 'blueprint' ] >,
+	phpVersion: NativePhpSupportedVersion,
+	signal: AbortSignal
+): Promise< void > {
+	// blueprints.phar accepts local paths only; remote URIs need the Playground runtime.
+	if ( blueprint.uri.startsWith( 'http://' ) || blueprint.uri.startsWith( 'https://' ) ) {
+		throw new Error(
+			`Remote blueprint URIs are not supported by the native PHP runtime: ${ blueprint.uri }`
+		);
+	}
+
+	const enableDebugLog = config.enableDebugLog ?? false;
+	const enableDebugDisplay = config.enableDebugDisplay ?? false;
+	const defaultConstants: Record< string, boolean | string > = {
+		// The SQLite driver requires a non-empty DB_NAME at runtime.
+		DB_NAME: 'wordpress',
+		WP_DEBUG: enableDebugLog || enableDebugDisplay,
+		WP_DEBUG_LOG: enableDebugLog,
+		WP_DEBUG_DISPLAY: enableDebugDisplay,
+	};
+
+	blueprint.contents.constants = {
+		...blueprint.contents.constants,
+		...defaultConstants,
+	};
+	// Native PHP selects PHP and installs WordPress before Blueprint execution.
+	// Passing preferredVersions makes blueprints.phar validate versions it does not manage here.
+	delete blueprint.contents.preferredVersions;
+
+	const blueprintDir = path.dirname( blueprint.uri );
+	const tmpPath = path.join( blueprintDir, `studio-blueprint-${ config.siteId }.json` );
+	await fs.promises.writeFile( tmpPath, JSON.stringify( blueprint.contents ) );
+
+	// blueprints.phar detects SQLite under plugins, while Studio installs it under mu-plugins.
+	const muPluginsSqlite = path.join(
+		config.sitePath,
+		'wp-content',
+		'mu-plugins',
+		'sqlite-database-integration'
+	);
+	const pluginsSqlite = path.join(
+		config.sitePath,
+		'wp-content',
+		'plugins',
+		'sqlite-database-integration'
+	);
+	const needsSymlink = fs.existsSync( muPluginsSqlite ) && ! fs.existsSync( pluginsSqlite );
+	let symlinkIno: number | undefined;
+	if ( needsSymlink ) {
+		fs.symlinkSync( muPluginsSqlite, pluginsSqlite, 'junction' );
+		// Remove only the entry created here, not unrelated content that replaced it.
+		symlinkIno = fs.statSync( pluginsSqlite ).ino;
+	}
+
+	try {
+		await runPhpCommand(
+			[
+				getBlueprintsPharPath(),
+				'exec',
+				tmpPath,
+				'--mode=apply-to-existing-site',
+				`--site-path=${ config.sitePath }`,
+				`--site-url=${ config.absoluteUrl ?? `http://localhost:${ config.port }` }`,
+				'--db-engine=sqlite',
+			],
+			{ phpVersion, signal }
+		);
+	} finally {
+		await fs.promises.unlink( tmpPath ).catch( () => {} );
+		if ( needsSymlink ) {
+			try {
+				if ( fs.statSync( pluginsSqlite ).ino === symlinkIno ) {
+					await fs.promises.rm( pluginsSqlite, { recursive: true, force: true } );
+				}
+			} catch {
+				// Best effort - leaving the symlink behind is non-fatal.
+			}
+		}
+	}
+}

apps/cli/lib/native-php.ts apps/cli/lib/native-php/config.tsapps/cli/lib/native-php.ts renamed to apps/cli/lib/native-php/config.ts

@@ -4,7 +4,8 @@ import os from 'os';
 import path from 'path';
 import { NativePhpSupportedVersion } from '@studio/common/lib/php-binary-metadata';
 import { writeFile } from 'atomically';
-import { getPhpBinaryPath } from './dependency-management/paths';
+import semver from 'semver';
+import { getPhpBinaryPath } from '../dependency-management/paths';
 
 // Disabled by default to shrink the attack surface available to PHP code
 // running inside a Studio site. Each entry falls into one of:
@@ -151,9 +152,14 @@ export function getNativePhpIniContents( phpVersion: NativePhpSupportedVersion )
 	if ( process.platform === 'win32' ) {
 		directives.push(
 			`extension_dir="${ toPhpIniPath( getExtensionDir( phpVersion ) ) }"`,
-			'zend_extension=opcache',
 			...WINDOWS_PHP_EXTENSIONS.map( ( extension ) => `extension=${ extension }` )
 		);
+
+		const coercedVersion = semver.coerce( phpVersion );
+		// As of PHP 8.5, the OPcache extension is always bundled with PHP
+		if ( coercedVersion && semver.lt( coercedVersion, '8.5.0' ) ) {
+			directives.push( 'zend_extension=opcache' );
+		}
 	}
 
 	return `${ directives.join( os.EOL ) }${ os.EOL }`;