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/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,13 @@ 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 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();
+		}
+	}
+}

packages/php-wasm/universal/src/lib/php-request-handler.ts

@@ -10,8 +10,16 @@ import { normalizeHeaders } from './php';
 import { PHPResponse } from './php-response';
 import type { PHPRequest, PHPRunOptions } from './universal-php';
 import { encodeAsMultipart } from './encode-as-multipart';
-import type { PHPFactoryOptions, SpawnedPHP } from './php-process-manager';
-import { MaxPhpInstancesError, PHPProcessManager } from './php-process-manager';
+import type {
+	PHPFactoryOptions,
+	PHPProcessManagerInterface,
+	SpawnedPHP,
+} from './php-process-manager';
+import {
+	MaxPhpInstancesError,
+	PHPProcessManager,
+	SingularPHPProcessManager,
+} from './php-process-manager';
 import { HttpCookieStore } from './http-cookie-store';
 import mimeTypes from './mime-types.json';
 
@@ -84,35 +92,16 @@ export type PHPRequestHandlerFactoryArgs = PHPFactoryOptions & {
 	requestHandler: PHPRequestHandler;
 };
 
-export type PHPRequestHandlerConfiguration = BaseConfiguration &
-	(
-		| {
-				/**
-				 * PHPProcessManager is required because the request handler needs
-				 * to make a decision for each request.
-				 *
-				 * Static assets are served using the primary PHP's filesystem, even
-				 * when serving 100 static files concurrently. No new PHP interpreter
-				 * is ever created as there's no need for it.
-				 *
-				 * Dynamic PHP requests, however, require grabbing an available PHP
-				 * interpreter, and that's where the PHPProcessManager comes in.
-				 */
-				processManager: PHPProcessManager;
-		  }
-		| {
-				phpFactory: (
-					requestHandler: PHPRequestHandlerFactoryArgs
-				) => Promise<PHP>;
-				/**
-				 * The maximum number of PHP instances that can exist at
-				 * the same time.
-				 */
-				maxPhpInstances?: number;
-		  }
-	) & {
-		cookieStore?: CookieStore | false;
-	};
+export type PHPRequestHandlerConfiguration = BaseConfiguration & {
+	phpFactory: (requestHandler: PHPRequestHandlerFactoryArgs) => Promise<PHP>;
+	/**
+	 * The maximum number of PHP instances that can exist at
+	 * the same time.
+	 */
+	maxPhpInstances?: number;
+} & {
+	cookieStore?: CookieStore | false;
+};
 
 /**
  * Handles HTTP requests using PHP runtime as a backend.
@@ -178,7 +167,7 @@ export class PHPRequestHandler implements AsyncDisposable {
 	#ABSOLUTE_URL: string;
 	#cookieStore: CookieStore | false;
 	rewriteRules: RewriteRule[];
-	processManager: PHPProcessManager;
+	processManager: PHPProcessManagerInterface;
 	getFileNotFoundAction: FileNotFoundGetActionCallback;
 
 	/**
@@ -202,26 +191,28 @@ export class PHPRequestHandler implements AsyncDisposable {
 			getFileNotFoundAction = () => ({ type: '404' }),
 		} = config;
 
-		if ('processManager' in config) {
-			this.processManager = config.processManager;
+		const phpFactory = async (info: PHPFactoryOptions) => {
+			const php = await config.phpFactory!({
+				...info,
+				requestHandler: this,
+			});
+
+			// Always set managed PHP's cwd to the document root.
+			if (!php.isDir(documentRoot)) {
+				php.mkdir(documentRoot);
+			}
+			php.chdir(documentRoot);
+
+			// @TODO: Decouple PHP and request handler
+			(php as any).requestHandler = this;
+			return php;
+		};
+
+		if (config.maxPhpInstances === 1) {
+			this.processManager = new SingularPHPProcessManager({ phpFactory });
 		} else {
 			this.processManager = new PHPProcessManager({
-				phpFactory: async (info) => {
-					const php = await config.phpFactory!({
-						...info,
-						requestHandler: this,
-					});
-
-					// Always set managed PHP's cwd to the document root.
-					if (!php.isDir(documentRoot)) {
-						php.mkdir(documentRoot);
-					}
-					php.chdir(documentRoot);
-
-					// @TODO: Decouple PHP and request handler
-					(php as any).requestHandler = this;
-					return php;
-				},
+				phpFactory,
 				maxPhpInstances: config.maxPhpInstances,
 			});
 		}
@@ -245,8 +236,8 @@ export class PHPRequestHandler implements AsyncDisposable {
 		this.#PORT = url.port
 			? Number(url.port)
 			: url.protocol === 'https:'
-			? 443
-			: 80;
+				? 443
+				: 80;
 		this.#PROTOCOL = (url.protocol || '').replace(':', '');
 		const isNonStandardPort = this.#PORT !== 443 && this.#PORT !== 80;
 		this.#HOST = [
@@ -578,7 +569,7 @@ export class PHPRequestHandler implements AsyncDisposable {
 	): Promise<PHPResponse> {
 		let spawnedPHP: SpawnedPHP | undefined = undefined;
 		try {
-			spawnedPHP = await this.processManager!.acquirePHPInstance({
+			spawnedPHP = await this.processManager.acquirePHPInstance({
 				considerPrimary: true,
 			});
 		} catch (e) {

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

@@ -229,9 +229,10 @@ export class PHPWorker implements LimitedPHPApi, AsyncDisposable {
 	 * @returns A PHP instance with a consistent chroot.
 	 */
 	private async acquirePHPInstance() {
-		const { php, reap } = await _private
-			.get(this)!
-			.requestHandler!.processManager.acquirePHPInstance();
+		const requestHandler = _private.get(this)!.requestHandler!;
+		const { php, reap } =
+			await requestHandler.processManager.acquirePHPInstance();
+
 		if (this.chroot !== null) {
 			php.chdir(this.chroot);
 		}