Accept php instance directly in PHPRequestHandler configuration

PHPRequestHandler now supports three configuration options:
- instanceManager: Custom PHPInstanceManager (advanced)
- php: Single PHP instance (creates SinglePHPInstanceManager internally)
- phpFactory + maxPhpInstances: Factory function (creates PHPProcessManager)

When a php instance is provided directly, the same transformations
(mkdir documentRoot, chdir, set requestHandler) are applied as with
phpFactory, keeping the behavior consistent.

Author: adamziel

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

@@ -13,6 +13,7 @@ import { encodeAsMultipart } from './encode-as-multipart';
 import type { PHPFactoryOptions } from './php-process-manager';
 import { MaxPhpInstancesError, PHPProcessManager } from './php-process-manager';
 import type { PHPInstanceManager, AcquiredPHP } from './php-instance-manager';
+import { SinglePHPInstanceManager } from './single-php-instance-manager';
 import { HttpCookieStore } from './http-cookie-store';
 import mimeTypes from './mime-types.json';
 
@@ -96,6 +97,14 @@ export type PHPRequestHandlerConfiguration = BaseConfiguration & {
 				 */
 				instanceManager: PHPInstanceManager;
 		  }
+		| {
+				/**
+				 * Provide a single PHP instance directly.
+				 * PHPRequestHandler will create a SinglePHPInstanceManager internally.
+				 * This is the simplest option for CLI contexts with a single PHP instance.
+				 */
+				php: PHP;
+		  }
 		| {
 				/**
 				 * Provide a factory function to create PHP instances.
@@ -207,6 +216,19 @@ export class PHPRequestHandler implements AsyncDisposable {
 
 		if ('instanceManager' in config) {
 			this.processManager = config.instanceManager;
+		} else if ('php' in config) {
+			const php = config.php;
+
+			// 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;
+
+			this.processManager = new SinglePHPInstanceManager({ php });
 		} else {
 			this.processManager = new PHPProcessManager({
 				phpFactory: async (info) => {