Decouple PHPRequestHandler from PHPProcessManager

Introduces a PHPInstanceManager interface that abstracts PHP instance
lifecycle management. Both PHPProcessManager (for web contexts with
multiple concurrent instances) and the new SinglePHPInstanceManager
(for CLI contexts with a single instance) implement this interface.

PHPRequestHandler now accepts either:
- instanceManager: A pre-built PHPInstanceManager instance
- phpFactory + maxPhpInstances: Creates PHPProcessManager internally

This allows CLI contexts to use a simpler single-instance manager where
runtime rotation is handled separately via php.enableRuntimeRotation(),
while web contexts continue using PHPProcessManager for concurrency.

Author: adamziel

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

@@ -24,6 +24,9 @@ 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 } 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,

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,12 +1,18 @@
 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;
 };
 
 export type PHPFactory = (options: PHPFactoryOptions) => Promise<PHP>;
 
+/**
+ * @deprecated Use AcquiredPHP from './php-instance-manager' instead.
+ */
+export type SpawnedPHP = AcquiredPHP;
+
 export interface ProcessManagerOptions {
 	/**
 	 * The maximum number of PHP instances that can exist at
@@ -33,11 +39,6 @@ export interface ProcessManagerOptions {
 	phpFactory?: PHPFactory;
 }
 
-export interface SpawnedPHP {
-	php: PHP;
-	reap: () => void;
-}
-
 export class MaxPhpInstancesError extends Error {
 	constructor(limit: number) {
 		super(
@@ -71,7 +72,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 PHPInstanceManager {
 	private primaryPhp?: PHP;
 	private primaryPhpPromise?: Promise<SpawnedPHP>;
 	private primaryIdle = true;

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

@@ -10,8 +10,9 @@ 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 type { PHPFactoryOptions } from './php-process-manager';
 import { MaxPhpInstancesError, PHPProcessManager } from './php-process-manager';
+import type { PHPInstanceManager, AcquiredPHP } from './php-instance-manager';
 import { HttpCookieStore } from './http-cookie-store';
 import mimeTypes from './mime-types.json';
 
@@ -85,15 +86,31 @@ export type PHPRequestHandlerFactoryArgs = PHPFactoryOptions & {
 };
 
 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;
-};
+} & (
+		| {
+				/**
+				 * Provide a custom instance manager for advanced use cases.
+				 * Use SinglePHPInstanceManager for CLI contexts with a single PHP instance.
+				 * Use PHPProcessManager for web contexts with multiple concurrent instances.
+				 */
+				instanceManager: PHPInstanceManager;
+		  }
+		| {
+				/**
+				 * Provide a factory function to create PHP instances.
+				 * PHPRequestHandler will create a PHPProcessManager internally.
+				 */
+				phpFactory: (
+					requestHandler: PHPRequestHandlerFactoryArgs
+				) => Promise<PHP>;
+				/**
+				 * The maximum number of PHP instances that can exist at
+				 * the same time. Only used when phpFactory is provided.
+				 */
+				maxPhpInstances?: number;
+		  }
+	);
 
 /**
  * Handles HTTP requests using PHP runtime as a backend.
@@ -159,7 +176,12 @@ export class PHPRequestHandler implements AsyncDisposable {
 	#ABSOLUTE_URL: string;
 	#cookieStore: CookieStore | false;
 	rewriteRules: RewriteRule[];
-	processManager: PHPProcessManager;
+	/**
+	 * The instance manager used for PHP instance lifecycle.
+	 * This is either a provided instanceManager or a PHPProcessManager
+	 * created from the phpFactory.
+	 */
+	processManager: PHPInstanceManager;
 	getFileNotFoundAction: FileNotFoundGetActionCallback;
 
 	/**
@@ -183,25 +205,29 @@ export class PHPRequestHandler implements AsyncDisposable {
 			getFileNotFoundAction = () => ({ type: '404' }),
 		} = config;
 
-		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;
-			},
-			maxPhpInstances: config.maxPhpInstances,
-		});
+		if ('instanceManager' in config) {
+			this.processManager = config.instanceManager;
+		} 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;
+				},
+				maxPhpInstances: config.maxPhpInstances,
+			});
+		}
 
 		/**
 		 * By default, config.cookieStore is undefined, so we use the
@@ -553,7 +579,7 @@ export class PHPRequestHandler implements AsyncDisposable {
 		rewrittenRequestUrl: URL,
 		scriptPath: string
 	): Promise<PHPResponse> {
-		let spawnedPHP: SpawnedPHP | undefined = undefined;
+		let spawnedPHP: AcquiredPHP | undefined = undefined;
 		try {
 			spawnedPHP = await this.processManager!.acquirePHPInstance({
 				considerPrimary: true,

packages/php-wasm/universal/src/lib/sandboxed-spawn-handler-factory.ts

@@ -1,5 +1,5 @@
 import { createSpawnHandler } from '@php-wasm/util';
-import type { PHPProcessManager } from './php-process-manager';
+import type { PHPInstanceManager } from './php-instance-manager';
 
 /**
  * An isomorphic proc_open() handler that implements typical shell in TypeScript
@@ -12,7 +12,7 @@ import type { PHPProcessManager } from './php-process-manager';
  * parser.
  */
 export function sandboxedSpawnHandlerFactory(
-	processManager: PHPProcessManager
+	instanceManager: PHPInstanceManager
 ) {
 	return createSpawnHandler(async function (args, processApi, options) {
 		processApi.notifySpawn();
@@ -63,7 +63,7 @@ export function sandboxedSpawnHandlerFactory(
 			return;
 		}
 
-		const { php, reap } = await processManager.acquirePHPInstance({
+		const { php, reap } = await instanceManager.acquirePHPInstance({
 			considerPrimary: false,
 		});
 

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

@@ -0,0 +1,76 @@
+import type { PHP } from './php';
+import type { PHPInstanceManager, AcquiredPHP } from './php-instance-manager';
+
+export interface SinglePHPInstanceManagerOptions {
+	/**
+	 * Either provide an existing PHP instance...
+	 */
+	php?: PHP;
+	/**
+	 * ...or a factory to create one on demand.
+	 */
+	phpFactory?: () => Promise<PHP>;
+}
+
+/**
+ * A minimal PHP instance manager that manages a single PHP instance.
+ *
+ * Unlike PHPProcessManager, this does not maintain a pool of instances
+ * or implement concurrency control. It simply returns the same PHP
+ * instance for every request.
+ *
+ * This is suitable for CLI contexts where:
+ * - Only one PHP instance is needed
+ * - Runtime rotation is handled separately via php.enableRuntimeRotation()
+ * - Concurrency is not a concern (each worker has its own instance)
+ */
+export class SinglePHPInstanceManager implements PHPInstanceManager {
+	private php: PHP | undefined;
+	private phpPromise: Promise<PHP> | undefined;
+	private phpFactory?: () => Promise<PHP>;
+
+	constructor(options: SinglePHPInstanceManagerOptions) {
+		if (!options.php && !options.phpFactory) {
+			throw new Error(
+				'SinglePHPInstanceManager 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!().then((php) => {
+					this.php = php;
+					this.phpPromise = undefined;
+					return php;
+				});
+			}
+			return this.phpPromise;
+		}
+		return this.php;
+	}
+
+	async acquirePHPInstance(
+		// eslint-disable-next-line @typescript-eslint/no-unused-vars
+		_options: { considerPrimary?: boolean } = {}
+	): Promise<AcquiredPHP> {
+		const php = await this.getPrimaryPhp();
+
+		return {
+			php,
+			reap: () => {
+				// For single-instance manager, reap is a no-op.
+				// The instance is reused for all requests.
+			},
+		};
+	}
+
+	async [Symbol.asyncDispose](): Promise<void> {
+		if (this.php) {
+			this.php.exit();
+		}
+	}
+}