@php-wasm/web 0.6.16 → 0.7.0

package/index.d.ts

@@ -106,137 +106,17 @@ export type PHPEvent = PHPRequestEndEvent | PHPRequestErrorEvent | PHPRuntimeIni
  * A callback function that handles PHP events.
  */
 export type PHPEventListener = (event: PHPEvent) => void;
-/**
- * Handles HTTP requests using PHP runtime as a backend.
- *
- * @public
- * @example Use PHPRequestHandler implicitly with a new PHP instance:
- * ```js
- * import { PHP } from '@php-wasm/web';
- *
- * const php = await PHP.load( '7.4', {
- *     requestHandler: {
- *         // PHP FS path to serve the files from:
- *         documentRoot: '/www',
- *
- *         // Used to populate $_SERVER['SERVER_NAME'] etc.:
- *         absoluteUrl: 'http://127.0.0.1'
- *     }
- * } );
- *
- * php.mkdirTree('/www');
- * php.writeFile('/www/index.php', '<?php echo "Hi from PHP!"; ');
- *
- * const response = await php.request({ path: '/index.php' });
- * console.log(response.text);
- * // "Hi from PHP!"
- * ```
- *
- * @example Explicitly create a PHPRequestHandler instance and run a PHP script:
- * ```js
- * import {
- *   loadPHPRuntime,
- *   PHP,
- *   PHPRequestHandler,
- *   getPHPLoaderModule,
- * } from '@php-wasm/web';
- *
- * const runtime = await loadPHPRuntime( await getPHPLoaderModule('7.4') );
- * const php = new PHP( runtime );
- *
- * php.mkdirTree('/www');
- * php.writeFile('/www/index.php', '<?php echo "Hi from PHP!"; ');
- *
- * const server = new PHPRequestHandler(php, {
- *     // PHP FS path to serve the files from:
- *     documentRoot: '/www',
- *
- *     // Used to populate $_SERVER['SERVER_NAME'] etc.:
- *     absoluteUrl: 'http://127.0.0.1'
- * });
- *
- * const response = server.request({ path: '/index.php' });
- * console.log(response.text);
- * // "Hi from PHP!"
- * ```
- */
-export interface RequestHandler {
-	/**
-	 * Serves the request – either by serving a static file, or by
-	 * dispatching it to the PHP runtime.
-	 *
-	 * The request() method mode behaves like a web server and only works if
-	 * the PHP was initialized with a `requestHandler` option (which the online version
-	 * of WordPress Playground does by default).
-	 *
-	 * In the request mode, you pass an object containing the request information
-	 * (method, headers, body, etc.) and the path to the PHP file to run:
-	 *
-	 * ```ts
-	 * const php = PHP.load('7.4', {
-	 * 	requestHandler: {
-	 * 		documentRoot: "/www"
-	 * 	}
-	 * })
-	 * php.writeFile("/www/index.php", `<?php echo file_get_contents("php://input");`);
-	 * const result = await php.request({
-	 * 	method: "GET",
-	 * 	headers: {
-	 * 		"Content-Type": "text/plain"
-	 * 	},
-	 * 	body: "Hello world!",
-	 * 	path: "/www/index.php"
-	 * });
-	 * // result.text === "Hello world!"
-	 * ```
-	 *
-	 * The `request()` method cannot be used in conjunction with `cli()`.
-	 *
-	 * @example
-	 * ```js
-	 * const output = await php.request({
-	 * 	method: 'GET',
-	 * 	url: '/index.php',
-	 * 	headers: {
-	 * 		'X-foo': 'bar',
-	 * 	},
-	 * 	body: {
-	 * 		foo: 'bar',
-	 * 	},
-	 * });
-	 * console.log(output.stdout); // "Hello world!"
-	 * ```
-	 *
-	 * @param  request - PHP Request data.
-	 */
-	request(request: PHPRequest, maxRedirects?: number): Promise<PHPResponse>;
-	/**
-	 * Converts a path to an absolute URL based at the PHPRequestHandler
-	 * root.
-	 *
-	 * @param  path The server path to convert to an absolute URL.
-	 * @returns The absolute URL.
-	 */
+export interface IsomorphicLocalPHP {
+	/** @deprecated Use PHPRequestHandler instead. */
+	request(request: PHPRequest): Promise<PHPResponse>;
+	/** @deprecated Use PHPRequestHandler instead. */
 	pathToInternalUrl(path: string): string;
-	/**
-	 * Converts an absolute URL based at the PHPRequestHandler to a relative path
-	 * without the server pathname and scope.
-	 *
-	 * @param  internalUrl An absolute URL based at the PHPRequestHandler root.
-	 * @returns The relative path.
-	 */
+	/** @deprecated Use PHPRequestHandler instead. */
 	internalUrlToPath(internalUrl: string): string;
-	/**
-	 * The absolute URL of this PHPRequestHandler instance.
-	 */
+	/** @deprecated Use PHPRequestHandler instead. */
 	absoluteUrl: string;
-	/**
-	 * The directory in the PHP filesystem where the server will look
-	 * for the files to serve. Default: `/var/www`.
-	 */
+	/** @deprecated Use PHPRequestHandler instead. */
 	documentRoot: string;
-}
-export interface IsomorphicLocalPHP extends RequestHandler {
 	/**
 	 * Sets the SAPI name exposed by the PHP module.
 	 * @param newName - The new SAPI name.
@@ -472,14 +352,6 @@ export interface IsomorphicLocalPHP extends RequestHandler {
 	 * @param listener Callback function to handle the message.
 	 */
 	onMessage(listener: MessageListener): void;
-	/**
-	 * Registers a handler to spawns a child process when
-	 * `proc_open()`, `popen()`, `exec()`, `system()`, or `passthru()`
-	 * is called.
-	 *
-	 * @param handler Callback function to spawn a process.
-	 */
-	setSpawnHandler(handler: SpawnHandler | string): void;
 }
 export type MessageListener = (data: string) => Promise<string | Uint8Array | void> | string | void;
 export interface EventEmitter {
@@ -542,6 +414,10 @@ export interface PHPRunOptions {
 	 * Environment variables to set for this run.
 	 */
 	env?: Record<string, string>;
+	/**
+	 * $_SERVER entries to set for this run.
+	 */
+	$_SERVER?: Record<string, string>;
 	/**
 	 * The code snippet to eval instead of a php file.
 	 */
@@ -592,7 +468,7 @@ export interface PHPRequestHandlerConfiguration {
 	 */
 	rewriteRules?: RewriteRule[];
 }
-declare class PHPRequestHandler implements RequestHandler {
+declare class PHPRequestHandler {
 	#private;
 	rewriteRules: RewriteRule[];
 	/**
@@ -604,62 +480,81 @@ declare class PHPRequestHandler implements RequestHandler {
 	 * @param  config - Request Handler configuration.
 	 */
 	constructor(php: BasePHP, config?: PHPRequestHandlerConfiguration);
-	/** @inheritDoc */
+	/**
+	 * Converts a path to an absolute URL based at the PHPRequestHandler
+	 * root.
+	 *
+	 * @param  path The server path to convert to an absolute URL.
+	 * @returns The absolute URL.
+	 */
 	pathToInternalUrl(path: string): string;
-	/** @inheritDoc */
-	internalUrlToPath(internalUrl: string): string;
-	get isRequestRunning(): boolean;
-	/** @inheritDoc */
-	get absoluteUrl(): string;
-	/** @inheritDoc */
-	get documentRoot(): string;
-	/** @inheritDoc */
-	request(request: PHPRequest): Promise<PHPResponse>;
-}
-export interface PHPBrowserConfiguration {
 	/**
-	 * Should handle redirects internally?
+	 * Converts an absolute URL based at the PHPRequestHandler to a relative path
+	 * without the server pathname and scope.
+	 *
+	 * @param  internalUrl An absolute URL based at the PHPRequestHandler root.
+	 * @returns The relative path.
 	 */
-	handleRedirects?: boolean;
+	internalUrlToPath(internalUrl: string): string;
+	get isRequestRunning(): boolean;
 	/**
-	 * The maximum number of redirects to follow internally. Once
-	 * exceeded, request() will return the redirecting response.
+	 * The absolute URL of this PHPRequestHandler instance.
 	 */
-	maxRedirects?: number;
-}
-declare class PHPBrowser implements RequestHandler {
-	#private;
-	requestHandler: PHPRequestHandler;
+	get absoluteUrl(): string;
 	/**
-	 * @param  server - The PHP server to browse.
-	 * @param  config - The browser configuration.
+	 * The directory in the PHP filesystem where the server will look
+	 * for the files to serve. Default: `/var/www`.
 	 */
-	constructor(requestHandler: PHPRequestHandler, config?: PHPBrowserConfiguration);
+	get documentRoot(): string;
 	/**
-	 * Sends the request to the server.
+	 * Serves the request – either by serving a static file, or by
+	 * dispatching it to the PHP runtime.
+	 *
+	 * The request() method mode behaves like a web server and only works if
+	 * the PHP was initialized with a `requestHandler` option (which the online version
+	 * of WordPress Playground does by default).
+	 *
+	 * In the request mode, you pass an object containing the request information
+	 * (method, headers, body, etc.) and the path to the PHP file to run:
+	 *
+	 * ```ts
+	 * const php = PHP.load('7.4', {
+	 * 	requestHandler: {
+	 * 		documentRoot: "/www"
+	 * 	}
+	 * })
+	 * php.writeFile("/www/index.php", `<?php echo file_get_contents("php://input");`);
+	 * const result = await php.request({
+	 * 	method: "GET",
+	 * 	headers: {
+	 * 		"Content-Type": "text/plain"
+	 * 	},
+	 * 	body: "Hello world!",
+	 * 	path: "/www/index.php"
+	 * });
+	 * // result.text === "Hello world!"
+	 * ```
 	 *
-	 * When cookies are present in the response, this method stores
-	 * them and sends them with any subsequent requests.
+	 * The `request()` method cannot be used in conjunction with `cli()`.
 	 *
-	 * When a redirection is present in the response, this method
-	 * follows it by discarding a response and sending a subsequent
-	 * request.
+	 * @example
+	 * ```js
+	 * const output = await php.request({
+	 * 	method: 'GET',
+	 * 	url: '/index.php',
+	 * 	headers: {
+	 * 		'X-foo': 'bar',
+	 * 	},
+	 * 	body: {
+	 * 		foo: 'bar',
+	 * 	},
+	 * });
+	 * console.log(output.stdout); // "Hello world!"
+	 * ```
 	 *
-	 * @param  request   - The request.
-	 * @param  redirects - Internal. The number of redirects handled so far.
-	 * @returns PHPRequestHandler response.
+	 * @param  request - PHP Request data.
 	 */
-	request(request: PHPRequest, redirects?: number): Promise<PHPResponse>;
-	/** @inheritDoc */
-	pathToInternalUrl(path: string): string;
-	/** @inheritDoc */
-	internalUrlToPath(internalUrl: string): string;
-	/** @inheritDoc */
-	get absoluteUrl(): string;
-	/** @inheritDoc */
-	get documentRoot(): string;
-	setCookies(cookies: string[]): void;
-	serializeCookies(): string;
+	request(request: PHPRequest): Promise<PHPResponse>;
 }
 export type PHPRuntimeId = number;
 export type PHPRuntime = any;
@@ -668,11 +563,6 @@ export type PHPLoaderModule = {
 	dependenciesTotalSize: number;
 	init: (jsRuntime: string, options: EmscriptenOptions) => PHPRuntime;
 };
-export type DataModule = {
-	dependencyFilename: string;
-	dependenciesTotalSize: number;
-	default: (phpRuntime: PHPRuntime) => void;
-};
 export type EmscriptenOptions = {
 	onAbort?: (message: string) => void;
 	/**
@@ -688,16 +578,26 @@ export type EmscriptenOptions = {
 	onRuntimeInitialized?: () => void;
 	monitorRunDependencies?: (left: number) => void;
 	onMessage?: (listener: EmscriptenMessageListener) => void;
+	instantiateWasm?: (info: WebAssembly.Imports, receiveInstance: (instance: WebAssembly.Instance, module: WebAssembly.Module) => void) => void;
 } & Record<string, any>;
 export type EmscriptenMessageListener = (type: string, data: string) => void;
 export interface SemaphoreOptions {
+	/**
+	 * The maximum number of concurrent locks.
+	 */
 	concurrency: number;
+	/**
+	 * The maximum time to wait for a lock to become available.
+	 */
+	timeout?: number;
 }
 declare class Semaphore {
 	private _running;
 	private concurrency;
+	private timeout?;
 	private queue;
-	constructor({ concurrency }: SemaphoreOptions);
+	constructor({ concurrency, timeout }: SemaphoreOptions);
+	get remaining(): number;
 	get running(): number;
 	acquire(): Promise<() => void>;
 	run<T>(fn: () => T | Promise<T>): Promise<T>;
@@ -706,7 +606,7 @@ declare const __private__dont__use: unique symbol;
 declare abstract class BasePHP implements IsomorphicLocalPHP {
 	#private;
 	protected [__private__dont__use]: any;
-	requestHandler?: PHPBrowser;
+	requestHandler?: PHPRequestHandler;
 	/**
 	 * An exclusive lock that prevent multiple requests from running at
 	 * the same time.
@@ -745,10 +645,9 @@ declare abstract class BasePHP implements IsomorphicLocalPHP {
 	/** @inheritDoc */
 	chdir(path: string): void;
 	/** @inheritDoc */
-	request(request: PHPRequest, maxRedirects?: number): Promise<PHPResponse>;
+	request(request: PHPRequest): Promise<PHPResponse>;
 	/** @inheritDoc */
 	run(request: PHPRunOptions): Promise<PHPResponse>;
-	addServerGlobalEntry(key: string, value: string): void;
 	defineConstant(key: string, value: string | boolean | number | null): void;
 	/** @inheritDoc */
 	mkdir(path: string): void;
@@ -777,21 +676,18 @@ declare abstract class BasePHP implements IsomorphicLocalPHP {
 	 * interrupting the operations of this PHP instance.
 	 *
 	 * @param runtime
+	 * @param cwd. Internal, the VFS path to recreate in the new runtime.
+	 *             This arg is temporary and will be removed once BasePHP
+	 *             is fully decoupled from the request handler and
+	 *             accepts a constructor-level cwd argument.
 	 */
-	hotSwapPHPRuntime(runtime: number): void;
+	hotSwapPHPRuntime(runtime: number, cwd?: string): void;
 	exit(code?: number): void;
 }
-declare class EmscriptenDownloadMonitor extends EventTarget {
-	#private;
-	constructor();
-	expectAssets(assets: Record<string, number>): void;
-	monitorFetch(fetchPromise: Promise<Response>): Promise<Response>;
-}
 export interface PHPWebLoaderOptions {
 	emscriptenOptions?: EmscriptenOptions;
-	downloadMonitor?: EmscriptenDownloadMonitor;
 	requestHandler?: PHPRequestHandlerConfiguration;
-	dataModules?: Array<DataModule | Promise<DataModule>>;
+	onPhpLoaderModuleLoaded?: (module: PHPLoaderModule) => void;
 	/** @deprecated To be replaced with `extensions` in the future */
 	loadAllExtensions?: boolean;
 }
@@ -811,6 +707,11 @@ export declare class WebPHP extends BasePHP {
 	static load(phpVersion: SupportedPHPVersion, options?: PHPWebLoaderOptions): Promise<WebPHP>;
 	static loadRuntime(phpVersion: SupportedPHPVersion, options?: PHPWebLoaderOptions): Promise<number>;
 }
+declare class EmscriptenDownloadMonitor extends EventTarget {
+	#private;
+	expectAssets(assets: Record<string, number>): void;
+	monitorFetch(fetchPromise: Promise<Response>): Promise<Response>;
+}
 /**
  * A PHP client that can be used to run PHP code in the browser.
  */
@@ -834,11 +735,9 @@ export declare class WebPHPEndpoint implements IsomorphicLocalPHP {
 	/** @inheritDoc @php-wasm/universal!IsomorphicLocalPHP.rmdir  */
 	rmdir(path: string, options?: RmDirOptions): void;
 	/** @inheritDoc @php-wasm/universal!RequestHandler.request */
-	request(request: PHPRequest, redirects?: number): Promise<PHPResponse>;
+	request(request: PHPRequest): Promise<PHPResponse>;
 	/** @inheritDoc @php-wasm/web!WebPHP.run */
 	run(request: PHPRunOptions): Promise<PHPResponse>;
-	/** @inheritDoc @php-wasm/web!WebPHP.setSpawnHandler */
-	setSpawnHandler(listener: string | SpawnHandler): void;
 	/** @inheritDoc @php-wasm/web!WebPHP.chdir */
 	chdir(path: string): void;
 	/** @inheritDoc @php-wasm/web!WebPHP.setSapiName */