@php-wasm/web 0.1.9 → 0.1.18

package/index.d.ts

@@ -2,191 +2,256 @@
 
 import * as Comlink from 'comlink';
 
-export type JavascriptRuntime = "NODE" | "WEB" | "WORKER";
-export type PHPRequestHeaders = Record<string, string>;
-export interface FileInfo {
-	key: string;
-	name: string;
-	type: string;
-	data: Uint8Array;
-}
-export interface PHPRequest {
+/**
+ * PHP response. Body is an `ArrayBuffer` because it can
+ * contain binary data.
+ */
+export declare class PHPResponse {
 	/**
-	 * Request path following the domain:port part.
+	 * Response headers.
 	 */
-	relativeUri?: string;
+	readonly headers: Record<string, string[]>;
 	/**
-	 * Path of the .php file to execute.
+	 * Response body. Contains the output from `echo`,
+	 * `print`, inline HTML etc.
 	 */
-	scriptPath?: string;
+	private readonly body;
 	/**
-	 * Request protocol.
+	 * Stderr contents, if any.
 	 */
-	protocol?: string;
+	readonly errors: string;
 	/**
-	 * Request method. Default: `GET`.
+	 * The exit code of the script. `0` is a success, while
+	 * `1` and `2` indicate an error.
 	 */
-	method?: "GET" | "POST" | "HEAD" | "OPTIONS" | "PATCH" | "PUT" | "DELETE";
+	readonly exitCode: number;
 	/**
-	 * Request headers.
+	 * Response HTTP status code, e.g. 200.
 	 */
-	headers?: PHPRequestHeaders;
+	readonly httpStatusCode: number;
+	constructor(httpStatusCode: number, headers: Record<string, string[]>, body: ArrayBuffer, errors?: string, exitCode?: number);
 	/**
-	 * Request body without the files.
+	 * Response body as JSON.
 	 */
-	body?: string;
+	get json(): any;
 	/**
-	 * Uploaded files.
+	 * Response body as text.
 	 */
-	fileInfos?: FileInfo[];
+	get text(): string;
 	/**
-	 * The code snippet to eval instead of a php file.
+	 * Response body as bytes.
 	 */
-	code?: string;
+	get bytes(): ArrayBuffer;
 }
-export interface PHPResponse {
-	/**
-	 * The exit code of the script. `0` is a success, while
-	 * `1` and `2` indicate an error.
-	 */
-	exitCode: number;
-	/**
-	 * Response body. Contains the output from `echo`,
-	 * `print`, inline HTML etc.
-	 */
-	body: ArrayBuffer;
+export type PHPRequest = Pick<PHPRunOptions, "method" | "headers"> & {
+	url: string;
+	files?: Record<string, File>;
+} & ((Pick<PHPRunOptions, "body"> & {
+	formData?: never;
+}) | {
+	body?: never;
+	formData: Record<string, unknown>;
+});
+export interface PHPRequestHandlerConfiguration {
 	/**
-	 * PHP errors.
+	 * The directory in the PHP filesystem where the server will look
+	 * for the files to serve. Default: `/var/www`.
 	 */
-	errors: string;
+	documentRoot?: string;
 	/**
-	 * Response headers.
+	 * Request Handler URL. Used to populate $_SERVER details like HTTP_HOST.
 	 */
-	headers: Record<string, string[]>;
+	absoluteUrl?: string;
 	/**
-	 * Response HTTP status code, e.g. 200.
+	 * Callback used by the PHPRequestHandler to decide whether
+	 * the requested path refers to a PHP file or a static file.
 	 */
-	httpStatusCode: number;
+	isStaticFilePath?: (path: string) => boolean;
 }
-export type PHPRuntimeId = number;
 /**
- * Loads the PHP runtime with the given arguments and data dependencies.
- *
- * This function handles the entire PHP initialization pipeline. In particular, it:
- *
- * * Instantiates the Emscripten PHP module
- * * Wires it together with the data dependencies and loads them
- * * Ensures is all happens in a correct order
- * * Waits until the entire loading sequence is finished
- *
- * Basic usage:
+ * A fake PHP server that handles HTTP requests but does not
+ * bind to any port.
  *
+ * @public
+ * @example Use PHPRequestHandler implicitly with a new PHP instance:
  * ```js
- *  const phpLoaderModule = await getPHPLoaderModule("7.4");
- *  const php = await loadPHPRuntime( phpLoaderModule );
- *  console.log(php.run(`<?php echo "Hello, world!"; `));
- *  // { stdout: ArrayBuffer containing the string "Hello, world!", stderr: [''], exitCode: 0 }
- * ```
- *
- * **The PHP loader module:**
+ * import { PHP } from '@php-wasm/web';
  *
- * In the basic usage example, `phpLoaderModule` is **not** a vanilla Emscripten module. Instead,
- * it's an ESM module that wraps the regular Emscripten output and adds some
- * extra functionality. It's generated by the Dockerfile shipped with this repo.
- * Here's the API it provides:
+ * const php = await PHP.load( '7.4', {
+ *     requestHandler: {
+ *         // PHP FS path to serve the files from:
+ *         documentRoot: '/www',
  *
- * ```js
- * // php.wasm size in bytes:
- * export const dependenciesTotalSize = 5644199;
+ *         // Used to populate $_SERVER['SERVER_NAME'] etc.:
+ *         absoluteUrl: 'http://127.0.0.1'
+ *     }
+ * } );
  *
- * // php.wasm filename:
- * export const dependencyFilename = 'php.wasm';
+ * php.mkdirTree('/www');
+ * php.writeFile('/www/index.php', '<?php echo "Hi from PHP!"; ');
  *
- * // Run Emscripten's generated module:
- * export default function(jsEnv, emscriptenModuleArgs) {}
+ * const response = await php.request({ path: '/index.php' });
+ * console.log(response.text);
+ * // "Hi from PHP!"
  * ```
  *
- * **PHP Filesystem:**
- *
- * Once initialized, the PHP has its own filesystem separate from the project
- * files. It's provided by [Emscripten and uses its FS library](https://emscripten.org/docs/api_reference/Filesystem-API.html).
- *
- * The API exposed to you via the PHP class is succinct and abstracts
- * await certain unintuitive parts of low-level FS interactions.
- *
- * Here's how to use it:
- *
+ * @example Explicitly create a PHPRequestHandler instance and run a PHP script:
  * ```js
- * // Recursively create a /var/www directory
- * php.mkdirTree('/var/www');
- *
- * console.log(php.fileExists('/var/www/file.txt'));
- * // false
- *
- * php.writeFile('/var/www/file.txt', 'Hello from the filesystem!');
- *
- * console.log(php.fileExists('/var/www/file.txt'));
- * // true
- *
- * console.log(php.readFile('/var/www/file.txt'));
- * // "Hello from the filesystem!
- *
- * // Delete the file:
- * php.unlink('/var/www/file.txt');
- * ```
- *
- * For more details consult the PHP class directly.
- *
- * **Data dependencies:**
- *
- * Using existing PHP packages by manually recreating them file-by-file would
- * be quite inconvenient. Fortunately, Emscripten provides a "data dependencies"
- * feature.
- *
- * Data dependencies consist of a `dependency.data` file and a `dependency.js` loader and
- * can be packaged with the [file_packager.py tool]( https://emscripten.org/docs/porting/files/packaging_files.html#packaging-using-the-file-packager-tool).
- * This project requires wrapping the Emscripten-generated `dependency.js` file in an ES
- * module as follows:
- *
- * 1. Prepend `export default function(emscriptenPHPModule) {'; `
- * 2. Prepend `export const dependencyFilename = '<DATA FILE NAME>'; `
- * 3. Prepend `export const dependenciesTotalSize = <DATA FILE SIZE>;`
- * 4. Append `}`
- *
- * Be sure to use the `--export-name="emscriptenPHPModule"` file_packager.py option.
+ * import {
+ *   loadPHPRuntime,
+ *   PHP,
+ *   PHPRequestHandler,
+ *   getPHPLoaderModule,
+ * } from '@php-wasm/web';
  *
- * You want the final output to look as follows:
+ * const runtime = await loadPHPRuntime( await getPHPLoaderModule('7.4') );
+ * const php = new PHP( runtime );
  *
- * ```js
- * export const dependenciesTotalSize = 5644199;
- * export const dependencyFilename = 'dependency.data';
- * export default function(emscriptenPHPModule) {
- *    // Emscripten-generated code:
- *    var Module = typeof emscriptenPHPModule !== 'undefined' ? emscriptenPHPModule : {};
- *    // ... the rest of it ...
- * }
- * ```
+ * php.mkdirTree('/www');
+ * php.writeFile('/www/index.php', '<?php echo "Hi from PHP!"; ');
  *
- * Such a constructions enables loading the `dependency.js` as an ES Module using
- * `import("/dependency.js")`.
+ * const server = new PHPRequestHandler(php, {
+ *     // PHP FS path to serve the files from:
+ *     documentRoot: '/www',
  *
- * Once it's ready, you can load PHP and your data dependencies as follows:
+ *     // Used to populate $_SERVER['SERVER_NAME'] etc.:
+ *     absoluteUrl: 'http://127.0.0.1'
+ * });
  *
- * ```js
- *  const [phpLoaderModule, wordPressLoaderModule] = await Promise.all([
- *    getPHPLoaderModule("7.4"),
- *    import("/wp.js")
- *  ]);
- *  const php = await loadPHPRuntime(phpLoaderModule, {}, [wordPressLoaderModule]);
+ * const response = server.request({ path: '/index.php' });
+ * console.log(response.text);
+ * // "Hi from PHP!"
  * ```
+ */
+export declare class PHPRequestHandler {
+	#private;
+	/**
+	 * The PHP instance
+	 */
+	php: BasePHP;
+	/**
+	 * @param  php    - The PHP instance.
+	 * @param  config - Request Handler configuration.
+	 */
+	constructor(php: BasePHP, config?: PHPRequestHandlerConfiguration);
+	/**
+	 * 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;
+	/**
+	 * 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.
+	 */
+	internalUrlToPath(internalUrl: string): string;
+	get isRequestRunning(): boolean;
+	/**
+	 * The absolute URL of this PHPRequestHandler instance.
+	 */
+	get absoluteUrl(): string;
+	/**
+	 * The absolute URL of this PHPRequestHandler instance.
+	 */
+	get documentRoot(): string;
+	/**
+	 * Serves the request – either by serving a static file, or by
+	 * dispatching it to the PHP runtime.
+	 *
+	 * @param  request - The request.
+	 * @returns The response.
+	 */
+	request(request: PHPRequest): Promise<PHPResponse>;
+}
+export interface PHPBrowserConfiguration {
+	/**
+	 * Should handle redirects internally?
+	 */
+	handleRedirects?: boolean;
+	/**
+	 * The maximum number of redirects to follow internally. Once
+	 * exceeded, request() will return the redirecting response.
+	 */
+	maxRedirects?: number;
+}
+/**
+ * A fake web browser that handles PHPRequestHandler's cookies and redirects
+ * internally without exposing them to the consumer.
  *
  * @public
- * @param  phpLoaderModule         - The ESM-wrapped Emscripten module. Consult the Dockerfile for the build process.
- * @param  phpModuleArgs           - The Emscripten module arguments, see https://emscripten.org/docs/api_reference/module.html#affecting-execution.
- * @param  dataDependenciesModules - A list of the ESM-wrapped Emscripten data dependency modules.
- * @returns Loaded runtime id.
  */
-export declare function loadPHPRuntime(phpLoaderModule: PHPLoaderModule, phpModuleArgs?: EmscriptenOptions, dataDependenciesModules?: DataModule[]): Promise<number>;
+export declare class PHPBrowser implements WithRequestHandler {
+	#private;
+	server: PHPRequestHandler;
+	/**
+	 * @param  server - The PHP server to browse.
+	 * @param  config - The browser configuration.
+	 */
+	constructor(server: PHPRequestHandler, config?: PHPBrowserConfiguration);
+	/**
+	 * Sends the request to the server.
+	 *
+	 * When cookies are present in the response, this method stores
+	 * them and sends them with any subsequent requests.
+	 *
+	 * When a redirection is present in the response, this method
+	 * follows it by discarding a response and sending a subsequent
+	 * request.
+	 *
+	 * @param  request   - The request.
+	 * @param  redirects - Internal. The number of redirects handled so far.
+	 * @returns PHPRequestHandler response.
+	 */
+	request(request: PHPRequest, redirects?: number): Promise<PHPResponse>;
+}
+export type RuntimeType = "NODE" | "WEB" | "WORKER";
+export type PHPRequestHeaders = Record<string, string>;
+export interface FileInfo {
+	key: string;
+	name: string;
+	type: string;
+	data: Uint8Array;
+}
+export interface PHPRunOptions {
+	/**
+	 * Request path following the domain:port part.
+	 */
+	relativeUri?: string;
+	/**
+	 * Path of the .php file to execute.
+	 */
+	scriptPath?: string;
+	/**
+	 * Request protocol.
+	 */
+	protocol?: string;
+	/**
+	 * Request method. Default: `GET`.
+	 */
+	method?: "GET" | "POST" | "HEAD" | "OPTIONS" | "PATCH" | "PUT" | "DELETE";
+	/**
+	 * Request headers.
+	 */
+	headers?: PHPRequestHeaders;
+	/**
+	 * Request body without the files.
+	 */
+	body?: string;
+	/**
+	 * Uploaded files.
+	 */
+	fileInfos?: FileInfo[];
+	/**
+	 * The code snippet to eval instead of a php file.
+	 */
+	code?: string;
+}
+export type PHPRuntimeId = number;
 export interface WithPHPIniBindings {
 	setPhpIniPath(path: string): void;
 	setPhpIniEntry(key: string, value: string): void;
@@ -274,21 +339,30 @@ export interface WithFilesystem {
 	 * @returns True if the file exists, false otherwise.
 	 */
 	fileExists(path: string): boolean;
+	/**
+	 * Changes the current working directory in the PHP filesystem.
+	 * This is the directory that will be used as the base for relative paths.
+	 * For example, if the current working directory is `/root/php`, and the
+	 * path is `data`, the absolute path will be `/root/php/data`.
+	 *
+	 * @param  path - The new working directory.
+	 */
+	chdir(path: string): void;
 }
 export interface WithRun {
 	/**
-	 * Dispatches a PHP request.
+	 * Runs PHP code.
 	 * Cannot be used in conjunction with `cli()`.
 	 *
 	 * @example
 	 * ```js
-	 * const output = php.run('<?php echo "Hello world!";');
+	 * const output = await php.run('<?php echo "Hello world!";');
 	 * console.log(output.stdout); // "Hello world!"
 	 * ```
 	 *
 	 * @example
 	 * ```js
-	 * console.log(php.run(`<?php
+	 * console.log(await php.run(`<?php
 	 *  $fp = fopen('php://stderr', 'w');
 	 *  fwrite($fp, "Hello, world!");
 	 * `));
@@ -297,13 +371,37 @@ export interface WithRun {
 	 *
 	 * @param  request - PHP Request data.
 	 */
-	run(request?: PHPRequest): PHPResponse;
+	run(request?: PHPRunOptions): Promise<PHPResponse>;
+}
+export interface WithRequestHandler {
+	/**
+	 * Dispatches a HTTP request using PHP as a backend.
+	 * Cannot be used in conjunction with `cli()`.
+	 *
+	 * @example
+	 * ```js
+	 * const output = await php.request({
+	 * 	method: 'GET',
+	 * 	url: '/index.php',
+	 * 	headers: {
+	 * 		'X-foo': 'bar',
+	 * 	},
+	 * 	formData: {
+	 * 		foo: 'bar',
+	 * 	},
+	 * });
+	 * console.log(output.stdout); // "Hello world!"
+	 * ```
+	 *
+	 * @param  request - PHP Request data.
+	 */
+	request(request?: PHPRequest): Promise<PHPResponse>;
 }
 export type PHPRuntime = any;
 export type PHPLoaderModule = {
 	dependencyFilename: string;
 	dependenciesTotalSize: number;
-	default: (jsRuntime: string, options: EmscriptenOptions) => PHPRuntime;
+	init: (jsRuntime: string, options: EmscriptenOptions) => PHPRuntime;
 };
 export type DataModule = {
 	dependencyFilename: string;
@@ -323,38 +421,35 @@ export type EmscriptenOptions = {
 } & Record<string, any>;
 export type MountSettings = {
 	root: string;
-	mountpoint: string;
 };
-/**
- * An environment-agnostic wrapper around the Emscripten PHP runtime
- * that abstracts the super low-level API and provides a more convenient
- * higher-level API.
- *
- * It exposes a minimal set of methods to run PHP scripts and to
- * interact with the PHP filesystem.
- *
- * @see {startPHP} This class is not meant to be used directly. Use `startPHP` instead.
- */
-export declare class PHP implements WithPHPIniBindings, WithFilesystem, WithNodeFilesystem, WithCLI, WithRun {
+declare abstract class BasePHP implements WithPHPIniBindings, WithFilesystem, WithNodeFilesystem, WithCLI, WithRequestHandler, WithRun {
 	#private;
+	requestHandler?: PHPBrowser;
 	/**
 	 * Initializes a PHP runtime.
 	 *
 	 * @internal
 	 * @param  PHPRuntime - Optional. PHP Runtime ID as initialized by loadPHPRuntime.
+	 * @param  serverOptions - Optional. Options for the PHPRequestHandler. If undefined, no request handler will be initialized.
 	 */
-	constructor(PHPRuntimeId?: PHPRuntimeId);
+	constructor(PHPRuntimeId?: PHPRuntimeId, serverOptions?: PHPRequestHandlerConfiguration);
 	initializeRuntime(runtimeId: PHPRuntimeId): void;
 	/** @inheritDoc */
 	setPhpIniPath(path: string): void;
 	/** @inheritDoc */
 	setPhpIniEntry(key: string, value: string): void;
 	/** @inheritDoc */
-	run(request?: PHPRequest): PHPResponse;
+	chdir(path: string): void;
+	/** @inheritDoc */
+	request(request: PHPRequest, maxRedirects?: number): Promise<PHPResponse>;
+	/** @inheritDoc */
+	run(request?: PHPRunOptions): Promise<PHPResponse>;
 	cli(argv: string[]): Promise<number>;
 	setSkipShebang(shouldSkip: boolean): void;
 	addServerGlobalEntry(key: string, value: string): void;
+	/** @inheritDoc */
 	mkdirTree(path: string): void;
+	/** @inheritDoc */
 	readFileAsText(path: string): string;
 	/** @inheritDoc */
 	readFileAsBuffer(path: string): Uint8Array;
@@ -364,8 +459,11 @@ export declare class PHP implements WithPHPIniBindings, WithFilesystem, WithNode
 	unlink(path: string): void;
 	/** @inheritDoc */
 	listFiles(path: string): string[];
+	/** @inheritDoc */
 	isDir(path: string): boolean;
+	/** @inheritDoc */
 	fileExists(path: string): boolean;
+	/** @inheritDoc */
 	mount(settings: MountSettings, path: string): void;
 }
 /**
@@ -380,164 +478,149 @@ export interface PHPOutput {
 	stderr: string[];
 }
 /**
- * Emscripten's filesystem-related Exception.
+ * Loads the PHP runtime with the given arguments and data dependencies.
  *
- * @see https://emscripten.org/docs/api_reference/Filesystem-API.html
- * @see https://github.com/emscripten-core/emscripten/blob/main/system/lib/libc/musl/arch/emscripten/bits/errno.h
- */
-export type ErrnoError = Error;
-export type PHPServerRequest = Pick<PHPRequest, "method" | "headers"> & {
-	files?: Record<string, File>;
-} & ({
-	absoluteUrl: string;
-	relativeUrl?: never;
-} | {
-	absoluteUrl?: never;
-	relativeUrl: string;
-}) & ((Pick<PHPRequest, "body"> & {
-	formData?: never;
-}) | {
-	body?: never;
-	formData: Record<string, unknown>;
-});
-/**
- * A fake PHP server that handles HTTP requests but does not
- * bind to any port.
+ * This function handles the entire PHP initialization pipeline. In particular, it:
+ *
+ * * Instantiates the Emscripten PHP module
+ * * Wires it together with the data dependencies and loads them
+ * * Ensures is all happens in a correct order
+ * * Waits until the entire loading sequence is finished
+ *
+ * Basic usage:
  *
- * @public
- * @example
  * ```js
- * import {
- *   loadPHPRuntime,
- *   PHP,
- *   PHPServer,
- *   PHPBrowser,
- *   getPHPLoaderModule,
- * } from '@php-wasm/web';
+ *  const phpLoaderModule = await getPHPLoaderModule("7.4");
+ *  const php = await loadPHPRuntime( phpLoaderModule );
+ *  console.log(php.run(`<?php echo "Hello, world!"; `));
+ *  // { stdout: ArrayBuffer containing the string "Hello, world!", stderr: [''], exitCode: 0 }
+ * ```
  *
- * const runtime = await loadPHPRuntime( await getPHPLoaderModule('7.4') );
- * const php = new PHP( runtime );
+ * **The PHP loader module:**
  *
- * php.mkdirTree('/www');
- * php.writeFile('/www/index.php', '<?php echo "Hi from PHP!"; ');
+ * In the basic usage example, `phpLoaderModule` is **not** a vanilla Emscripten module. Instead,
+ * it's an ESM module that wraps the regular Emscripten output and adds some
+ * extra functionality. It's generated by the Dockerfile shipped with this repo.
+ * Here's the API it provides:
  *
- * const server = new PHPServer(php, {
- *     // PHP FS path to serve the files from:
- *     documentRoot: '/www',
+ * ```js
+ * // php.wasm size in bytes:
+ * export const dependenciesTotalSize = 5644199;
  *
- *     // Used to populate $_SERVER['SERVER_NAME'] etc.:
- *     absoluteUrl: 'http://127.0.0.1'
- * });
+ * // php.wasm filename:
+ * export const dependencyFilename = 'php.wasm';
  *
- * const output = server.request({ path: '/index.php' }).body;
- * console.log(new TextDecoder().decode(output));
- * // "Hi from PHP!"
+ * // Run Emscripten's generated module:
+ * export default function(jsEnv, emscriptenModuleArgs) {}
+ * ```
+ *
+ * **PHP Filesystem:**
+ *
+ * Once initialized, the PHP has its own filesystem separate from the project
+ * files. It's provided by [Emscripten and uses its FS library](https://emscripten.org/docs/api_reference/Filesystem-API.html).
+ *
+ * The API exposed to you via the PHP class is succinct and abstracts
+ * await certain unintuitive parts of low-level FS interactions.
+ *
+ * Here's how to use it:
+ *
+ * ```js
+ * // Recursively create a /var/www directory
+ * php.mkdirTree('/var/www');
+ *
+ * console.log(php.fileExists('/var/www/file.txt'));
+ * // false
+ *
+ * php.writeFile('/var/www/file.txt', 'Hello from the filesystem!');
+ *
+ * console.log(php.fileExists('/var/www/file.txt'));
+ * // true
+ *
+ * console.log(php.readFile('/var/www/file.txt'));
+ * // "Hello from the filesystem!
+ *
+ * // Delete the file:
+ * php.unlink('/var/www/file.txt');
+ * ```
+ *
+ * For more details consult the PHP class directly.
+ *
+ * **Data dependencies:**
+ *
+ * Using existing PHP packages by manually recreating them file-by-file would
+ * be quite inconvenient. Fortunately, Emscripten provides a "data dependencies"
+ * feature.
+ *
+ * Data dependencies consist of a `dependency.data` file and a `dependency.js` loader and
+ * can be packaged with the [file_packager.py tool]( https://emscripten.org/docs/porting/files/packaging_files.html#packaging-using-the-file-packager-tool).
+ * This project requires wrapping the Emscripten-generated `dependency.js` file in an ES
+ * module as follows:
+ *
+ * 1. Prepend `export default function(emscriptenPHPModule) {'; `
+ * 2. Prepend `export const dependencyFilename = '<DATA FILE NAME>'; `
+ * 3. Prepend `export const dependenciesTotalSize = <DATA FILE SIZE>;`
+ * 4. Append `}`
+ *
+ * Be sure to use the `--export-name="emscriptenPHPModule"` file_packager.py option.
+ *
+ * You want the final output to look as follows:
+ *
+ * ```js
+ * export const dependenciesTotalSize = 5644199;
+ * export const dependencyFilename = 'dependency.data';
+ * export default function(emscriptenPHPModule) {
+ *    // Emscripten-generated code:
+ *    var Module = typeof emscriptenPHPModule !== 'undefined' ? emscriptenPHPModule : {};
+ *    // ... the rest of it ...
+ * }
+ * ```
+ *
+ * Such a constructions enables loading the `dependency.js` as an ES Module using
+ * `import("/dependency.js")`.
+ *
+ * Once it's ready, you can load PHP and your data dependencies as follows:
+ *
+ * ```js
+ *  const [phpLoaderModule, wordPressLoaderModule] = await Promise.all([
+ *    getPHPLoaderModule("7.4"),
+ *    import("/wp.js")
+ *  ]);
+ *  const php = await loadPHPRuntime(phpLoaderModule, {}, [wordPressLoaderModule]);
  * ```
+ *
+ * @public
+ * @param  phpLoaderModule         - The ESM-wrapped Emscripten module. Consult the Dockerfile for the build process.
+ * @param  phpModuleArgs           - The Emscripten module arguments, see https://emscripten.org/docs/api_reference/module.html#affecting-execution.
+ * @param  dataDependenciesModules - A list of the ESM-wrapped Emscripten data dependency modules.
+ * @returns Loaded runtime id.
  */
-export declare class PHPServer {
-	#private;
-	/**
-	 * The PHP instance
-	 */
-	php: PHP;
-	/**
-	 * @param  php    - The PHP instance.
-	 * @param  config - Server configuration.
-	 */
-	constructor(php: PHP, config?: PHPServerConfigation);
-	/**
-	 * Converts a path to an absolute URL based at the PHPServer
-	 * root.
-	 *
-	 * @param  path The server path to convert to an absolute URL.
-	 * @returns The absolute URL.
-	 */
-	pathToInternalUrl(path: string): string;
-	/**
-	 * Converts an absolute URL based at the PHPServer to a relative path
-	 * without the server pathname and scope.
-	 *
-	 * @param  internalUrl An absolute URL based at the PHPServer root.
-	 * @returns The relative path.
-	 */
-	internalUrlToPath(internalUrl: string): string;
-	/**
-	 * The absolute URL of this PHPServer instance.
-	 */
-	get absoluteUrl(): string;
-	/**
-	 * The absolute URL of this PHPServer instance.
-	 */
-	get documentRoot(): string;
-	/**
-	 * Serves the request – either by serving a static file, or by
-	 * dispatching it to the PHP runtime.
-	 *
-	 * @param  request - The request.
-	 * @returns The response.
-	 */
-	request(request: PHPServerRequest): Promise<PHPResponse>;
-}
-export interface PHPServerConfigation {
-	/**
-	 * The directory in the PHP filesystem where the server will look
-	 * for the files to serve. Default: `/var/www`.
-	 */
-	documentRoot?: string;
-	/**
-	 * Server URL. Used to populate $_SERVER details like HTTP_HOST.
-	 */
-	absoluteUrl?: string;
-	/**
-	 * Callback used by the PHPServer to decide whether
-	 * the requested path refers to a PHP file or a static file.
-	 */
-	isStaticFilePath?: (path: string) => boolean;
-}
-export interface WithRequest {
-	/**
-	 * Sends the request to the server.
-	 *
-	 * When cookies are present in the response, this method stores
-	 * them and sends them with any subsequent requests.
-	 *
-	 * When a redirection is present in the response, this method
-	 * follows it by discarding a response and sending a subsequent
-	 * request.
-	 *
-	 * @param  request   - The request.
-	 * @param  redirects - Internal. The number of redirects handled so far.
-	 * @returns PHPServer response.
-	 */
-	request(request: PHPServerRequest, redirects?: number): Promise<PHPResponse>;
-}
+export declare function loadPHPRuntime(phpLoaderModule: PHPLoaderModule, phpModuleArgs?: EmscriptenOptions, dataDependenciesModules?: DataModule[]): Promise<number>;
 /**
- * A fake web browser that handles PHPServer's cookies and redirects
- * internally without exposing them to the consumer.
+ * Emscripten's filesystem-related Exception.
  *
- * @public
+ * @see https://emscripten.org/docs/api_reference/Filesystem-API.html
+ * @see https://github.com/emscripten-core/emscripten/blob/main/system/lib/libc/musl/arch/emscripten/bits/errno.h
+ * @see https://github.com/emscripten-core/emscripten/blob/38eedc630f17094b3202fd48ac0c2c585dbea31e/system/include/wasi/api.h#L336
  */
-export declare class PHPBrowser implements WithRequest {
-	#private;
-	server: PHPServer;
-	/**
-	 * @param  server - The PHP server to browse.
-	 * @param  config - The browser configuration.
-	 */
-	constructor(server: PHPServer, config?: PHPBrowserConfiguration);
-	request(request: PHPServerRequest, redirects?: number): Promise<PHPResponse>;
-}
-export interface PHPBrowserConfiguration {
-	/**
-	 * Should handle redirects internally?
-	 */
-	handleRedirects?: boolean;
-	/**
-	 * The maximum number of redirects to follow internally. Once
-	 * exceeded, request() will return the redirecting response.
-	 */
-	maxRedirects?: number;
+export interface ErrnoError extends Error {
+	node?: any;
+	errno: number;
+	message: string;
 }
+export declare const SupportedPHPVersions: readonly [
+	"8.2",
+	"8.1",
+	"8.0",
+	"7.4",
+	"7.3",
+	"7.2",
+	"7.1",
+	"7.0",
+	"5.6"
+];
+export declare const LatestSupportedPHPVersion: "8.2";
+export declare const SupportedPHPVersionsList: string[];
+export type SupportedPHPVersion = (typeof SupportedPHPVersions)[number];
 export type WorkerStartupOptions<T extends Record<string, string> = Record<string, string>> = T;
 export declare function consumeAPI<APIType>(remote: Worker | Window): Comlink.Remote<APIType>;
 export type PublicAPI<Methods, PipedAPI = unknown> = Methods & PipedAPI & {
@@ -554,11 +637,45 @@ export interface MonitoredModule {
 declare class EmscriptenDownloadMonitor extends EventTarget {
 	#private;
 	constructor(modules?: MonitoredModule[]);
-	getEmscriptenArgs(): {
+	getEmscriptenOptions(): {
 		dataFileDownloads: Record<string, any>;
 	};
 	setModules(modules: MonitoredModule[]): void;
 }
+export interface PHPWebLoaderOptions {
+	emscriptenOptions?: EmscriptenOptions;
+	downloadMonitor?: EmscriptenDownloadMonitor;
+	requestHandler?: PHPRequestHandlerConfiguration;
+	dataModules?: Array<DataModule | Promise<DataModule>>;
+}
+export declare class PHP extends BasePHP {
+	/**
+	 * Creates a new PHP instance.
+	 *
+	 * Dynamically imports the PHP module, initializes the runtime,
+	 * and sets up networking. It's a shorthand for the lower-level
+	 * functions like `getPHPLoaderModule`, `loadPHPRuntime`, and
+	 * `PHP.initializeRuntime`
+	 *
+	 * @param phpVersion The PHP Version to load
+	 * @param options The options to use when loading PHP
+	 * @returns A new PHP instance
+	 */
+	static load(phpVersion: SupportedPHPVersion, options?: PHPWebLoaderOptions): Promise<PHP>;
+	/**
+	 * Does what load() does, but synchronously returns
+	 * an object with the PHP instance and a promise that
+	 * resolves when the PHP instance is ready.
+	 *
+	 * @see load
+	 * @inheritdoc load
+	 */
+	static loadSync(phpVersion: SupportedPHPVersion, options?: PHPWebLoaderOptions): {
+		php: PHP;
+		phpReady: Promise<PHP>;
+		dataModules: Promise<DataModule[]>;
+	};
+}
 /** @inheritdoc T */
 export type Promisify<T> = {
 	[P in keyof T]: T[P] extends (...args: infer A) => infer R ? R extends void | Promise<any> ? T[P] : (...args: A) => Promise<ReturnType<T[P]>> : Promise<T[P]>;
@@ -573,22 +690,24 @@ export interface WithProgress {
 /**
  * A PHP client that can be used to run PHP code in the browser.
  */
-export declare class PHPClient implements Promisify<WithRequest & WithPHPIniBindings & WithFilesystem & WithRun & WithProgress & WithPathConversion> {
-	/** @inheritDoc @php-wasm/web!PHPServer.absoluteUrl */
+export declare class PHPClient implements Promisify<WithPHPIniBindings & WithFilesystem & WithRun & WithRequestHandler & WithProgress & WithPathConversion> {
+	/** @inheritDoc @php-wasm/web!PHPRequestHandler.absoluteUrl */
 	absoluteUrl: Promise<string>;
-	/** @inheritDoc @php-wasm/web!PHPServer.documentRoot */
+	/** @inheritDoc @php-wasm/web!PHPRequestHandler.documentRoot */
 	documentRoot: Promise<string>;
 	/** @inheritDoc */
-	constructor(browser: PHPBrowser, monitor?: EmscriptenDownloadMonitor);
-	/** @inheritDoc @php-wasm/web!PHPServer.pathToInternalUrl */
+	constructor(php: BasePHP, monitor?: EmscriptenDownloadMonitor);
+	/** @inheritDoc @php-wasm/web!PHPRequestHandler.pathToInternalUrl */
 	pathToInternalUrl(path: string): Promise<string>;
-	/** @inheritDoc @php-wasm/web!PHPServer.internalUrlToPath */
+	/** @inheritDoc @php-wasm/web!PHPRequestHandler.internalUrlToPath */
 	internalUrlToPath(internalUrl: string): Promise<string>;
 	onDownloadProgress(callback: (progress: CustomEvent<ProgressEvent>) => void): Promise<void>;
-	/** @inheritDoc @php-wasm/web!PHPServer.request */
-	request(request: PHPServerRequest, redirects?: number): Promise<PHPResponse>;
+	/** @inheritDoc @php-wasm/web!PHPRequestHandler.request */
+	request(request: PHPRequest, redirects?: number): Promise<PHPResponse>;
 	/** @inheritDoc @php-wasm/web!PHP.run */
-	run(request?: PHPRequest | undefined): Promise<PHPResponse>;
+	run(request?: PHPRunOptions): Promise<PHPResponse>;
+	/** @inheritDoc @php-wasm/web!PHP.chdir */
+	chdir(path: string): void;
 	/** @inheritDoc @php-wasm/web!PHP.setPhpIniPath */
 	setPhpIniPath(path: string): void;
 	/** @inheritDoc @php-wasm/web!PHP.setPhpIniEntry */
@@ -610,8 +729,18 @@ export declare class PHPClient implements Promisify<WithRequest & WithPHPIniBind
 	/** @inheritDoc @php-wasm/web!PHP.fileExists */
 	fileExists(path: string): Promise<boolean>;
 }
-export declare const isAssignableToRemoteClient: PHPClient;
-export declare function getPHPLoaderModule(version?: string): Promise<PHPLoaderModule>;
+export declare function getPHPLoaderModule(version?: SupportedPHPVersion): Promise<PHPLoaderModule>;
+/**
+ * Run this in the main application to register the service worker or
+ * reload the registered worker if the app expects a different version
+ * than the currently registered one.
+ *
+ * @param {string} scriptUrl       The URL of the service worker script.
+ * @param {string} expectedVersion The expected version of the service worker script. If
+ *                                 mismatched with the actual version, the service worker
+ *                                 will be re-registered.
+ */
+export declare function registerServiceWorker<Client extends PHPClient>(phpApi: Client, scope: string, scriptUrl: string, expectedVersion: string): Promise<void>;
 export declare function parseWorkerStartupOptions<T extends Record<string, string>>(): WorkerStartupOptions<T>;
 /**
  * Recommended Worker Thread backend.
@@ -629,16 +758,5 @@ export declare const recommendedWorkerBackend: string;
  * @returns The spawned Worker Thread.
  */
 export declare function spawnPHPWorkerThread(workerUrl: string, workerBackend?: "webworker" | "iframe", startupOptions?: Record<string, string>): Promise<Window | Worker>;
-/**
- * Run this in the main application to register the service worker or
- * reload the registered worker if the app expects a different version
- * than the currently registered one.
- *
- * @param {string} scriptUrl       The URL of the service worker script.
- * @param {string} expectedVersion The expected version of the service worker script. If
- *                                 mismatched with the actual version, the service worker
- *                                 will be re-registered.
- */
-export declare function registerServiceWorker<Client extends PHPClient>(phpApi: Client, scope: string, scriptUrl: string, expectedVersion: string): Promise<void>;
 
 export {};