Enforce single PHP instance per CLI worker for correct file locking

When PHP acquires file locks via flock(), the locks are managed at the kernel
level per-process. Multiple PHP WASM instances within the same OS process would
share those locks, defeating the purpose of file locking for concurrent access
control.

This change ensures CLI workers use exactly one PHP instance by:

- Adding maxPhpInstances option to PHPRequestHandler that, when set to 1,
  bypasses PHPProcessManager entirely and uses a single PHP instance
- Refactoring spawn handler into a unified createPhpSpawnHandler() that accepts
  a configurable phpCliHandler for subprocess spawning
- CLI workers now use createPhpSpawnHandler without a PHP CLI handler, meaning
  proc_open('php ...') returns exit code 127 instead of spawning in-process
- Web environments continue using sandboxedSpawnHandlerFactory which spawns
  PHP instances via PHPProcessManager

The spawn handler API is now:
- createPhpSpawnHandler({ getPrimaryPhp, phpCliHandler? }) - core handler
- createProcessManagerCliHandler(acquirePHPInstance) - for multi-instance mode
- sandboxedSpawnHandlerFactory(requestHandler) - legacy wrapper

Author: adamziel

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

@@ -6,3 +6,4 @@ export * from './node-fs-mount';
 export * from './file-lock-manager';
 export * from './file-lock-manager-for-node';
 export * from './xdebug/with-xdebug';
+export * from './node-php-cli-handler';

packages/php-wasm/node/src/lib/node-php-cli-handler.ts

@@ -0,0 +1,121 @@
+import { spawn } from 'child_process';
+import type { PHPCliHandler, ProcessOptions } from '@php-wasm/universal';
+import type { ProcessApi } from '@php-wasm/util';
+
+export interface NodePhpCliHandlerOptions {
+	/**
+	 * Path to the Node.js binary.
+	 * Defaults to process.execPath.
+	 */
+	nodePath?: string;
+
+	/**
+	 * Node.js flags to pass to the Node.js binary.
+	 * Defaults to process.execArgv.
+	 */
+	nodeArgs?: string[];
+
+	/**
+	 * Path to the php-wasm CLI entry point script.
+	 * This should be the path to the compiled php-wasm CLI binary.
+	 */
+	phpWasmEntryPoint: string;
+}
+
+/**
+ * Creates a PHP CLI handler for Node.js environments that spawns
+ * a new OS process for each PHP subprocess.
+ *
+ * This is essential for CLI environments where each PHP instance needs
+ * its own OS process for correct file locking behavior. Kernel-level
+ * file locks (flock) are per-process, so multiple PHP WASM instances
+ * in the same OS process would share locks and defeat the purpose of locking.
+ *
+ * When PHP calls proc_open('php ...'), this handler spawns a completely
+ * separate OS process running the php-wasm CLI, ensuring proper isolation.
+ *
+ * @example
+ * ```ts
+ * const phpCliHandler = createNodePhpCliHandler({
+ *   phpWasmEntryPoint: '/path/to/php-wasm-cli/main.js',
+ * });
+ *
+ * const spawnHandler = createPhpSpawnHandler({
+ *   getPrimaryPhp: () => requestHandler.getPrimaryPhp(),
+ *   phpCliHandler,
+ * });
+ * ```
+ */
+export function createNodePhpCliHandler(
+	options: NodePhpCliHandlerOptions
+): PHPCliHandler {
+	const {
+		nodePath = process.execPath,
+		nodeArgs = process.execArgv,
+		phpWasmEntryPoint,
+	} = options;
+
+	return async (
+		args: string[],
+		processApi: ProcessApi,
+		processOptions: ProcessOptions
+	) => {
+		// Skip 'php' from args since we're invoking the php-wasm CLI directly
+		const phpArgs = args.slice(1);
+
+		const child = spawn(
+			nodePath,
+			[...nodeArgs, phpWasmEntryPoint, ...phpArgs],
+			{
+				cwd: processOptions.cwd,
+				env: {
+					...process.env,
+					...processOptions.env,
+					// Set SHELL_PIPE to 0 to ensure WP-CLI formats
+					// the output as ASCII tables.
+					// @see https://github.com/wp-cli/wp-cli/issues/1102
+					SHELL_PIPE: '0',
+				},
+				stdio: ['pipe', 'pipe', 'pipe'],
+			}
+		);
+
+		// Handle stdin from the parent process
+		processApi.on('stdin', (data: Uint8Array | string) => {
+			if (child.stdin && !child.stdin.destroyed) {
+				child.stdin.write(data);
+			}
+		});
+
+		// When the parent process closes stdin, close child's stdin too
+		processApi.childProcess.stdin?.on('finish', () => {
+			child.stdin?.end();
+		});
+
+		// Stream stdout to the parent process
+		child.stdout?.on('data', (chunk: Buffer) => {
+			processApi.stdout(chunk);
+		});
+
+		// Stream stderr to the parent process
+		child.stderr?.on('data', (chunk: Buffer) => {
+			processApi.stderr(chunk);
+		});
+
+		// Wait for the child process to exit
+		await new Promise<void>((resolve) => {
+			child.on('close', (code) => {
+				processApi.exit(code ?? 0);
+				resolve();
+			});
+
+			child.on('error', (error) => {
+				processApi.stderr(
+					`Failed to spawn PHP process: ${error.message}\n`
+				);
+				processApi.exit(1);
+				resolve();
+			});
+		});
+	};
+}

packages/php-wasm/node/src/test/php-part-1.spec.ts

@@ -1,7 +1,7 @@
 import {
 	getPhpIniEntries,
 	PHP,
-	PHPProcessManager,
+	PHPRequestHandler,
 	sandboxedSpawnHandlerFactory,
 	setPhpIniEntries,
 	type SpawnedPHP,
@@ -1830,9 +1830,9 @@ describe('sandboxedSpawnHandlerFactory', () => {
 	const phpVersion = RecommendedPHPVersion;
 	let php: PHP;
 	let spawnedPhp: SpawnedPHP;
-	let processManager: PHPProcessManager;
+	let requestHandler: PHPRequestHandler;
 	beforeEach(async () => {
-		processManager = new PHPProcessManager({
+		requestHandler = new PHPRequestHandler({
 			phpFactory: async () => {
 				const php = new PHP(
 					await loadNodeRuntime(phpVersion as any, {})
@@ -1850,17 +1850,19 @@ describe('sandboxedSpawnHandlerFactory', () => {
 					'Hello, world!'
 				);
 				await php.setSpawnHandler(
-					sandboxedSpawnHandlerFactory(processManager)
+					sandboxedSpawnHandlerFactory(requestHandler)
 				);
 				return php;
 			},
 			maxPhpInstances: 5,
+			documentRoot: '/tmp/shared-test-directory',
+			absoluteUrl: 'http://localhost',
 		});
-		spawnedPhp = await processManager.acquirePHPInstance();
+		spawnedPhp = await requestHandler.processManager!.acquirePHPInstance();
 		php = spawnedPhp.php;
 	});
 	afterEach(async () => {
-		await processManager[Symbol.asyncDispose]();
+		await requestHandler[Symbol.asyncDispose]();
 		spawnedPhp?.reap();
 	});
 	it.each([

packages/php-wasm/node/src/test/php-part-2.spec.ts

@@ -2,7 +2,7 @@ import {
 	__private__dont__use,
 	loadPHPRuntime,
 	PHP,
-	PHPProcessManager,
+	PHPRequestHandler,
 	sandboxedSpawnHandlerFactory,
 	setPhpIniEntries,
 	type SpawnedPHP,
@@ -1160,9 +1160,9 @@ describe('sandboxedSpawnHandlerFactory', () => {
 	const phpVersion = RecommendedPHPVersion;
 	let php: PHP;
 	let spawnedPhp: SpawnedPHP;
-	let processManager: PHPProcessManager;
+	let requestHandler: PHPRequestHandler;
 	beforeEach(async () => {
-		processManager = new PHPProcessManager({
+		requestHandler = new PHPRequestHandler({
 			phpFactory: async () => {
 				const php = new PHP(
 					await loadNodeRuntime(phpVersion as any, {})
@@ -1180,17 +1180,19 @@ describe('sandboxedSpawnHandlerFactory', () => {
 					'Hello, world!'
 				);
 				await php.setSpawnHandler(
-					sandboxedSpawnHandlerFactory(processManager)
+					sandboxedSpawnHandlerFactory(requestHandler)
 				);
 				return php;
 			},
 			maxPhpInstances: 5,
+			documentRoot: '/tmp/shared-test-directory',
+			absoluteUrl: 'http://localhost',
 		});
-		spawnedPhp = await processManager.acquirePHPInstance();
+		spawnedPhp = await requestHandler.processManager!.acquirePHPInstance();
 		php = spawnedPhp.php;
 	});
 	afterEach(async () => {
-		await processManager[Symbol.asyncDispose]();
+		await requestHandler[Symbol.asyncDispose]();
 		spawnedPhp?.reap();
 	});
 	it.each([

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

@@ -24,11 +24,15 @@ 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 { PHPProcessManager } from './php-process-manager';
+export {
+	PHPProcessManager,
+	SingularPHPProcessManager,
+} from './php-process-manager';
 export type {
 	MaxPhpInstancesError,
 	PHPFactory,
 	PHPFactoryOptions,
+	PHPProcessManagerInterface,
 	ProcessManagerOptions,
 	SpawnedPHP,
 } from './php-process-manager';
@@ -84,7 +88,14 @@ export {
 
 export { isExitCode } from './is-exit-code';
 export { proxyFileSystem, isPathToSharedFS } from './proxy-file-system';
-export { sandboxedSpawnHandlerFactory } from './sandboxed-spawn-handler-factory';
+export {
+	createPhpSpawnHandler,
+	createProcessManagerCliHandler,
+	sandboxedSpawnHandlerFactory,
+	type PHPCliHandler,
+	type ProcessOptions,
+	type SpawnHandlerOptions,
+} from './sandboxed-spawn-handler-factory';
 
 export * from './api';
 export type { WithAPIState as WithIsReady } from './api';

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

@@ -7,6 +7,16 @@ export type PHPFactoryOptions = {
 
 export type PHPFactory = (options: PHPFactoryOptions) => Promise<PHP>;
 
+/**
+ * Common interface for PHP process managers.
+ */
+export interface PHPProcessManagerInterface extends AsyncDisposable {
+	getPrimaryPhp(): Promise<PHP>;
+	acquirePHPInstance(options?: {
+		considerPrimary?: boolean;
+	}): Promise<SpawnedPHP>;
+}
+
 export interface ProcessManagerOptions {
 	/**
 	 * The maximum number of PHP instances that can exist at
@@ -71,7 +81,7 @@ 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 PHPProcessManagerInterface {
 	private primaryPhp?: PHP;
 	private primaryPhpPromise?: Promise<SpawnedPHP>;
 	private primaryIdle = true;
@@ -266,3 +276,66 @@ export class PHPProcessManager implements AsyncDisposable {
 		);
 	}
 }
+
+/**
+ * A PHP Process manager that manages exactly one PHP instance.
+ *
+ * This is useful for CLI environments where we want each OS process to have
+ * exactly one PHP instance for correct file locking behavior. Kernel-level
+ * file locks are per-process, so multiple PHP instances in the same process
+ * would share locks and defeat the purpose of locking.
+ *
+ * Unlike PHPProcessManager which can spawn multiple instances, this manager:
+ * - Never creates or destroys PHP instances (the instance is provided at construction)
+ * - Refuses to acquire if the instance is already acquired
+ * - Implements the same interface as PHPProcessManager for compatibility
+ */
+export class SingularPHPProcessManager implements PHPProcessManagerInterface {
+	private php: PHP;
+	private phpPromise?: Promise<PHP>;
+	private phpFactory?: PHPFactory;
+	private acquired = false;
+
+	constructor(options: { php?: PHP; phpFactory?: PHPFactory }) {
+		if (!options.php && !options.phpFactory) {
+			throw new Error(
+				'SingularPHPProcessManager requires either php or phpFactory'
+			);
+		}
+		this.php = options.php!;
+		this.phpFactory = options.phpFactory;
+	}
+
+	async getPrimaryPhp(): Promise<PHP> {
+		if (!this.php) {
+			if (!this.phpPromise) {
+				this.phpPromise = this.phpFactory!({ isPrimary: true });
+			}
+			this.php = await this.phpPromise;
+			this.phpPromise = undefined;
+		}
+		return this.php;
+	}
+
+	async acquirePHPInstance(): Promise<SpawnedPHP> {
+		if (this.acquired) {
+			throw new AcquireTimeoutError(
+				'SingularPHPProcessManager: Cannot acquire PHP instance - already in use. ' +
+					'This manager only supports one concurrent acquisition.'
+			);
+		}
+		this.acquired = true;
+		return {
+			php: await this.getPrimaryPhp(),
+			reap: () => {
+				this.acquired = false;
+			},
+		};
+	}
+
+	async [Symbol.asyncDispose]() {
+		if (this.php) {
+			this.php.exit();
+		}
+	}
+}