[CLI] SinglePHPInstanceManager, spawn OS subprocesses in the spawn handler in Blueprint V2 worker (#3004)

## Motivation

Makes the Blueprints V2 worker spawn a new OS process when PHP calls
`proc_open()`. This enables using OS-level `flock()`, `LockFileEx()`,
etc. Before this PR, `proc_open()` would create a new PHP instance
within the same Node.js worker, which meant all the OS-level file locks
acquired by that "PHP sub-process" would be attributed to the same
OS-level process as the "parent PHP process".

Follows up on the V1 worker PR #3001.

This PR also ships the changes from
#3006:

Introduces `SinglePHPInstanceManager`, a `PHPProcessManager` alternative
to use with `PHPRequestHandler` that uses a single PHP instance without
spawning another one or killing it. Note the internal runtime rotation
after n requests is still supported separately via
`php.enableRuntimeRotation()`. `PHPProcessManager` was designed to use
multiple PHP instances. However, in CLI, we can only use a single PHP
instance per process if we want to support exclusive file locking via
`flock()` and `LockFileEx()`.

## Implementation

### Spawn

The `bootRequestHandler` method now passes a custom PHP-spawning factory
function to `sandboxedSpawnHandlerFactory`.

### Request handler

Introduce a `PHPInstanceManager` interface that abstracts PHP instance
lifecycle management:

```typescript
interface PHPInstanceManager extends AsyncDisposable {
    getPrimaryPhp(): Promise<PHP>;
    acquirePHPInstance(options?: { considerPrimary?: boolean }): Promise<AcquiredPHP>;
}
```

Two implementations:
- **PHPProcessManager**: Multiple instances with semaphore-based
concurrency control (web)
- **SinglePHPInstanceManager**: Single instance, no concurrency overhead
(CLI)


PHPRequestHandler now accepts either configuration:

```typescript
// Option 1: Provide an instance manager directly
const requestHandler = new PHPRequestHandler({
    instanceManager: new SinglePHPInstanceManager({ phpFactory: ... }),
    documentRoot: '/wordpress',
});

// Option 2: Provide a factory (creates PHPProcessManager internally, unchanged from before)
const requestHandler = new PHPRequestHandler({
    phpFactory: async () => loadWebRuntime('8.0'),
    maxPhpInstances: 5,
});
```

## Testing

CI

Author: adamziel

packages/php-wasm/cli/src/main.ts

@@ -129,6 +129,7 @@ ${process.argv[0]} ${process.execArgv.join(' ')} ${process.argv[1]}
 			withXdebug: hasXdebugOption,
 		})
 	);
+	php.setSpawnHandler(require('child_process').spawn);
 
 	useHostFilesystem(php);
 

packages/php-wasm/node/src/test/php-instance-manager.spec.ts

@@ -0,0 +1,203 @@
+import { RecommendedPHPVersion } from '@wp-playground/common';
+import { loadNodeRuntime } from '..';
+import { PHP, PHPProcessManager, SinglePHPInstanceManager } from '@php-wasm/universal';
+
+describe('SinglePHPInstanceManager', () => {
+	it('should return the PHP instance passed in the constructor', async () => {
+		const php = new PHP(await loadNodeRuntime(RecommendedPHPVersion));
+		const mgr = new SinglePHPInstanceManager({ php });
+
+		const primaryPhp = await mgr.getPrimaryPhp();
+		expect(primaryPhp).toBe(php);
+	});
+
+	it('should create a PHP instance using the factory when no instance is provided', async () => {
+		const phpFactory = vitest.fn(
+			async () => new PHP(await loadNodeRuntime(RecommendedPHPVersion))
+		);
+		const mgr = new SinglePHPInstanceManager({ phpFactory });
+
+		expect(phpFactory).not.toHaveBeenCalled();
+		const php = await mgr.getPrimaryPhp();
+		expect(phpFactory).toHaveBeenCalledTimes(1);
+		expect(php).toBeInstanceOf(PHP);
+	});
+
+	it('should return the same PHP instance on subsequent getPrimaryPhp calls', async () => {
+		const phpFactory = vitest.fn(
+			async () => new PHP(await loadNodeRuntime(RecommendedPHPVersion))
+		);
+		const mgr = new SinglePHPInstanceManager({ phpFactory });
+
+		const php1 = await mgr.getPrimaryPhp();
+		const php2 = await mgr.getPrimaryPhp();
+		expect(php1).toBe(php2);
+		expect(phpFactory).toHaveBeenCalledTimes(1);
+	});
+
+	it('should acquire and release the PHP instance', async () => {
+		const php = new PHP(await loadNodeRuntime(RecommendedPHPVersion));
+		const mgr = new SinglePHPInstanceManager({ php });
+
+		const acquired = await mgr.acquirePHPInstance();
+		expect(acquired.php).toBe(php);
+
+		acquired.reap();
+
+		// Should be able to acquire again after reaping
+		const acquired2 = await mgr.acquirePHPInstance();
+		expect(acquired2.php).toBe(php);
+	});
+
+	it('should throw an error when trying to acquire twice without reaping', async () => {
+		const php = new PHP(await loadNodeRuntime(RecommendedPHPVersion));
+		const mgr = new SinglePHPInstanceManager({ php });
+
+		await mgr.acquirePHPInstance();
+		await expect(() => mgr.acquirePHPInstance()).rejects.toThrowError(
+			/already acquired/
+		);
+	});
+
+	it('should throw an error when neither php nor phpFactory is provided', () => {
+		expect(
+			() => new SinglePHPInstanceManager({})
+		).toThrowError(/requires either php or phpFactory/);
+	});
+
+	it('should only call the factory once even with concurrent getPrimaryPhp calls', async () => {
+		const phpFactory = vitest.fn(
+			async () => new PHP(await loadNodeRuntime(RecommendedPHPVersion))
+		);
+		const mgr = new SinglePHPInstanceManager({ phpFactory });
+
+		// Make concurrent calls
+		const [php1, php2, php3] = await Promise.all([
+			mgr.getPrimaryPhp(),
+			mgr.getPrimaryPhp(),
+			mgr.getPrimaryPhp(),
+		]);
+
+		expect(phpFactory).toHaveBeenCalledTimes(1);
+		expect(php1).toBe(php2);
+		expect(php2).toBe(php3);
+	});
+});
+
+describe('PHPProcessManager', () => {
+	it('should return the primary PHP instance', async () => {
+		const mgr = new PHPProcessManager({
+			phpFactory: async () =>
+				new PHP(await loadNodeRuntime(RecommendedPHPVersion)),
+			maxPhpInstances: 4,
+		});
+
+		const php = await mgr.getPrimaryPhp();
+		expect(php).toBeInstanceOf(PHP);
+	});
+
+	it('should spawn new PHP instances', async () => {
+		const mgr = new PHPProcessManager({
+			phpFactory: async () =>
+				new PHP(await loadNodeRuntime(RecommendedPHPVersion)),
+			maxPhpInstances: 4,
+		});
+
+		const php1 = await mgr.acquirePHPInstance();
+		expect(php1.php).toBeInstanceOf(PHP);
+
+		const php2 = await mgr.acquirePHPInstance();
+		expect(php1.php).not.toBe(php2.php);
+	});
+
+	it('should not spawn primary PHP until the first acquire call', async () => {
+		const phpFactory = vitest.fn(
+			async () => new PHP(await loadNodeRuntime(RecommendedPHPVersion))
+		);
+		const mgr = new PHPProcessManager({
+			phpFactory,
+			maxPhpInstances: 4,
+		});
+
+		expect(phpFactory).not.toHaveBeenCalled();
+		await mgr.acquirePHPInstance();
+		expect(phpFactory).toHaveBeenCalled();
+	});
+
+	it('should refuse to spawn more PHP instances than the maximum (limit=2)', async () => {
+		const mgr = new PHPProcessManager({
+			phpFactory: async () =>
+				new PHP(await loadNodeRuntime(RecommendedPHPVersion)),
+			maxPhpInstances: 2,
+			timeout: 100,
+		});
+
+		await mgr.acquirePHPInstance({ considerPrimary: true });
+		await mgr.acquirePHPInstance({ considerPrimary: true });
+		await expect(() =>
+			mgr.acquirePHPInstance({ considerPrimary: true })
+		).rejects.toThrowError(/Requested more concurrent PHP instances/);
+	});
+
+	it('should refuse to spawn more PHP instances than the maximum (limit=3)', async () => {
+		const mgr = new PHPProcessManager({
+			phpFactory: async () =>
+				new PHP(await loadNodeRuntime(RecommendedPHPVersion)),
+			maxPhpInstances: 3,
+			timeout: 100,
+		});
+
+		await mgr.acquirePHPInstance({ considerPrimary: true });
+		await mgr.acquirePHPInstance({ considerPrimary: true });
+		await mgr.acquirePHPInstance({ considerPrimary: true });
+		await expect(() =>
+			mgr.acquirePHPInstance({ considerPrimary: true })
+		).rejects.toThrowError(/Requested more concurrent PHP instances/);
+	});
+
+	it('should not start a second PHP instance until the first getInstance() call when the primary instance is busy', async () => {
+		const phpFactory = vitest.fn(
+			async () => new PHP(await loadNodeRuntime(RecommendedPHPVersion))
+		);
+		const mgr = new PHPProcessManager({
+			phpFactory,
+			maxPhpInstances: 5,
+		});
+
+		expect(phpFactory).not.toHaveBeenCalled();
+		const php1 = await mgr.acquirePHPInstance({ considerPrimary: true });
+		expect(phpFactory).toHaveBeenCalledTimes(1);
+		php1.reap();
+
+		const php2 = await mgr.acquirePHPInstance({ considerPrimary: true });
+		expect(phpFactory).toHaveBeenCalledTimes(1);
+		php2.reap();
+
+		await mgr.acquirePHPInstance({ considerPrimary: true });
+		await mgr.acquirePHPInstance({ considerPrimary: true });
+		expect(phpFactory).toHaveBeenCalledTimes(3);
+	});
+
+	it('should refuse to spawn two primary PHP instances', async () => {
+		const mgr = new PHPProcessManager({
+			phpFactory: async () =>
+				new PHP(await loadNodeRuntime(RecommendedPHPVersion)),
+			maxPhpInstances: 5,
+		});
+
+		// A synchronous call. Do not await this promise on purpose.
+		mgr.getPrimaryPhp();
+
+		// No await here, because we want to check if a second,
+		// synchronous call throws an error if issued before
+		// the first call completes asynchronously.
+		try {
+			mgr.getPrimaryPhp();
+		} catch (e) {
+			expect(e).toBeInstanceOf(Error);
+			expect((e as Error).message).toContain(
+				'Requested spawning a primary PHP instance'
+			);
+		}
+	});
+});

packages/php-wasm/node/src/test/php-request-handler.spec.ts

@@ -277,7 +277,7 @@ describe.each(configsForRequestTests)(
 						: joinPaths(
 								new URL(absoluteUrl as string).pathname,
 								nonExistentFileUri
-						  );
+							);
 				expect(response).toEqual({
 					httpStatusCode: 200,
 					headers: expect.any(Object),
@@ -989,7 +989,7 @@ describe('PHPRequestHandler – Loopback call', () => {
 						);
 					}
 					const { php, reap } =
-						await handler.processManager.acquirePHPInstance();
+						await handler.instanceManager.acquirePHPInstance();
 					const result = await php.run({
 						scriptPath: args[1],
 						env: options.env,

packages/php-wasm/node/src/test/php-worker.spec.ts

@@ -37,7 +37,7 @@ describe('PHP Worker', () => {
 			 * Block the primary PHP instance to ensure run()
 			 * creates a fresh PHP instance.
 			 */
-			const { reap } = await handler.processManager.acquirePHPInstance({
+			const { reap } = await handler.instanceManager.acquirePHPInstance({
 				considerPrimary: instanceType === 'primary',
 			});
 			try {

packages/php-wasm/universal/src/lib/index.ts

@@ -24,13 +24,22 @@ export { HttpCookieStore } from './http-cookie-store';
 export type { IteratePhpFilesOptions as IterateFilesOptions } from './iterate-files';
 export { iteratePhpFiles as iterateFiles } from './iterate-files';
 export { writeFilesStreamToPhp } from './write-files-stream-to-php';
+export type {
+	PHPInstanceManager,
+	AcquiredPHP,
+	/**
+	 * Backwards compatibility alias.
+	 */
+	AcquiredPHP as SpawnedPHP,
+} from './php-instance-manager';
+export { SinglePHPInstanceManager } from './single-php-instance-manager';
+export type { SinglePHPInstanceManagerOptions } from './single-php-instance-manager';
 export { PHPProcessManager } from './php-process-manager';
 export type {
 	MaxPhpInstancesError,
 	PHPFactory,
 	PHPFactoryOptions,
 	ProcessManagerOptions,
-	SpawnedPHP,
 } from './php-process-manager';
 
 export { PHPResponse, StreamedPHPResponse } from './php-response';

packages/php-wasm/universal/src/lib/php-instance-manager.ts

@@ -0,0 +1,41 @@
+import type { PHP } from './php';
+
+/**
+ * Result of acquiring a PHP instance.
+ * The `reap` function should be called when done with the instance.
+ */
+export interface AcquiredPHP {
+	php: PHP;
+	/**
+	 * Release the PHP instance back to the pool (for multi-instance managers)
+	 * or mark it as idle (for single-instance managers).
+	 */
+	reap: () => void;
+}
+
+/**
+ * Minimal interface for managing PHP instances.
+ *
+ * This interface allows PHPRequestHandler to work with different
+ * instance management strategies:
+ * - PHPProcessManager: Multiple PHP instances with concurrency control
+ * - SinglePHPInstanceManager: Single PHP instance for CLI contexts
+ */
+export interface PHPInstanceManager extends AsyncDisposable {
+	/**
+	 * Get the primary PHP instance.
+	 * This instance is persistent and never killed.
+	 */
+	getPrimaryPhp(): Promise<PHP>;
+
+	/**
+	 * Acquire a PHP instance for processing a request.
+	 *
+	 * @param options.considerPrimary - Whether the primary instance can be used.
+	 *        Set to false for operations that would corrupt the primary (e.g., CLI commands).
+	 * @returns An acquired PHP instance with a reap function.
+	 */
+	acquirePHPInstance(options?: {
+		considerPrimary?: boolean;
+	}): Promise<AcquiredPHP>;
+}

packages/php-wasm/universal/src/lib/php-process-manager.ts

@@ -1,5 +1,6 @@
 import { AcquireTimeoutError, Semaphore } from '@php-wasm/util';
 import type { PHP } from './php';
+import type { PHPInstanceManager, AcquiredPHP } from './php-instance-manager';
 
 export type PHPFactoryOptions = {
 	isPrimary: boolean;
@@ -33,11 +34,6 @@ export interface ProcessManagerOptions {
 	phpFactory?: PHPFactory;
 }
 
-export interface SpawnedPHP {
-	php: PHP;
-	reap: () => void;
-}
-
 export class MaxPhpInstancesError extends Error {
 	constructor(limit: number) {
 		super(
@@ -71,16 +67,16 @@ export class MaxPhpInstancesError extends Error {
  * requests requires extra time to spin up a few PHP instances. This is a more
  * resource-friendly tradeoff than keeping 5 idle instances at all times.
  */
-export class PHPProcessManager implements AsyncDisposable {
+export class PHPProcessManager implements PHPInstanceManager {
 	private primaryPhp?: PHP;
-	private primaryPhpPromise?: Promise<SpawnedPHP>;
+	private primaryPhpPromise?: Promise<AcquiredPHP>;
 	private primaryIdle = true;
-	private nextInstance: Promise<SpawnedPHP> | null = null;
+	private nextInstance: Promise<AcquiredPHP> | null = null;
 	/**
 	 * All spawned PHP instances, including the primary PHP instance.
 	 * Used for bookkeeping and reaping all instances on dispose.
 	 */
-	private allInstances: Promise<SpawnedPHP>[] = [];
+	private allInstances: Promise<AcquiredPHP>[] = [];
 	private phpFactory?: PHPFactory;
 	private maxPhpInstances: number;
 	private semaphore: Semaphore;
@@ -147,7 +143,7 @@ export class PHPProcessManager implements AsyncDisposable {
 		considerPrimary = false,
 	}: {
 		considerPrimary?: boolean;
-	} = {}): Promise<SpawnedPHP> {
+	} = {}): Promise<AcquiredPHP> {
 		/**
 		 * First and foremost, make sure we have the primary PHP instance in place.
 		 * We may not actually acquire it. We just need it to exist.
@@ -178,7 +174,7 @@ export class PHPProcessManager implements AsyncDisposable {
 		 *   budget left to optimistically start spawning the next
 		 *   instance.
 		 */
-		const spawnedPhp =
+		const acquiredPHP =
 			this.nextInstance || this.spawn({ isPrimary: false });
 
 		/**
@@ -191,7 +187,7 @@ export class PHPProcessManager implements AsyncDisposable {
 		} else {
 			this.nextInstance = null;
 		}
-		return await spawnedPhp;
+		return await acquiredPHP;
 	}
 
 	/**
@@ -200,7 +196,7 @@ export class PHPProcessManager implements AsyncDisposable {
 	 * add the spawn promise to the allInstances array without waiting
 	 * for PHP to spawn.
 	 */
-	private spawn(factoryArgs: PHPFactoryOptions): Promise<SpawnedPHP> {
+	private spawn(factoryArgs: PHPFactoryOptions): Promise<AcquiredPHP> {
 		if (factoryArgs.isPrimary && this.allInstances.length > 0) {
 			throw new Error(
 				'Requested spawning a primary PHP instance when another primary instance already started spawning.'
@@ -230,7 +226,9 @@ export class PHPProcessManager implements AsyncDisposable {
 	/**
 	 * Actually acquires the lock and spawns a new PHP instance.
 	 */
-	private async doSpawn(factoryArgs: PHPFactoryOptions): Promise<SpawnedPHP> {
+	private async doSpawn(
+		factoryArgs: PHPFactoryOptions
+	): Promise<AcquiredPHP> {
 		let release: () => void;
 		try {
 			release = await this.semaphore.acquire();