@wp-playground/blueprints 0.7.19 → 0.9.1

package/index.d.ts

@@ -182,169 +182,607 @@ declare class PHPResponse implements PHPResponseData {
 	 */
 	get text(): string;
 }
-/**
- * Represents an event related to the PHP request.
- */
-export interface PHPRequestEndEvent {
-	type: "request.end";
+export type PHPRuntimeId = number;
+/** Other WebAssembly declarations, for compatibility with older versions of Typescript */
+export declare namespace Emscripten {
+	export interface RootFS extends Emscripten.FileSystemInstance {
+		filesystems: Record<string, Emscripten.FileSystemType>;
+	}
+	export interface FileSystemType {
+		mount(mount: FS.Mount): FS.FSNode;
+		syncfs(mount: FS.Mount, populate: () => unknown, done: (err?: number | null) => unknown): void;
+	}
+	export type EnvironmentType = "WEB" | "NODE" | "SHELL" | "WORKER";
+	export type JSType = "number" | "string" | "array" | "boolean";
+	export type TypeCompatibleWithC = number | string | any[] | boolean;
+	export type CIntType = "i8" | "i16" | "i32" | "i64";
+	export type CFloatType = "float" | "double";
+	export type CPointerType = "i8*" | "i16*" | "i32*" | "i64*" | "float*" | "double*" | "*";
+	export type CType = CIntType | CFloatType | CPointerType;
+	export interface CCallOpts {
+		async?: boolean | undefined;
+	}
+	type NamespaceToInstance<T> = {
+		[K in keyof T]: T[K] extends (...args: any[]) => any ? T[K] : never;
+	};
+	export type FileSystemInstance = NamespaceToInstance<typeof FS> & {
+		mkdirTree(path: string): void;
+		lookupPath(path: string, opts?: any): FS.Lookup;
+	};
+	export interface EmscriptenModule {
+		print(str: string): void;
+		printErr(str: string): void;
+		arguments: string[];
+		environment: Emscripten.EnvironmentType;
+		preInit: Array<{
+			(): void;
+		}>;
+		preRun: Array<{
+			(): void;
+		}>;
+		postRun: Array<{
+			(): void;
+		}>;
+		onAbort: {
+			(what: any): void;
+		};
+		onRuntimeInitialized: {
+			(): void;
+		};
+		preinitializedWebGLContext: WebGLRenderingContext;
+		noInitialRun: boolean;
+		noExitRuntime: boolean;
+		logReadFiles: boolean;
+		filePackagePrefixURL: string;
+		wasmBinary: ArrayBuffer;
+		destroy(object: object): void;
+		getPreloadedPackage(remotePackageName: string, remotePackageSize: number): ArrayBuffer;
+		instantiateWasm(imports: WebAssembly.Imports, successCallback: (module: WebAssembly.Instance) => void): WebAssembly.Exports | undefined;
+		locateFile(url: string, scriptDirectory: string): string;
+		onCustomMessage(event: MessageEvent): void;
+		HEAP: Int32Array;
+		IHEAP: Int32Array;
+		FHEAP: Float64Array;
+		HEAP8: Int8Array;
+		HEAP16: Int16Array;
+		HEAP32: Int32Array;
+		HEAPU8: Uint8Array;
+		HEAPU16: Uint16Array;
+		HEAPU32: Uint32Array;
+		HEAPF32: Float32Array;
+		HEAPF64: Float64Array;
+		HEAP64: BigInt64Array;
+		HEAPU64: BigUint64Array;
+		TOTAL_STACK: number;
+		TOTAL_MEMORY: number;
+		FAST_MEMORY: number;
+		addOnPreRun(cb: () => any): void;
+		addOnInit(cb: () => any): void;
+		addOnPreMain(cb: () => any): void;
+		addOnExit(cb: () => any): void;
+		addOnPostRun(cb: () => any): void;
+		preloadedImages: any;
+		preloadedAudios: any;
+		_malloc(size: number): number;
+		_free(ptr: number): void;
+	}
+	/**
+	 * A factory function is generated when setting the `MODULARIZE` build option
+	 * to `1` in your Emscripten build. It return a Promise that resolves to an
+	 * initialized, ready-to-call `EmscriptenModule` instance.
+	 *
+	 * By default, the factory function will be named `Module`. It's recommended to
+	 * use the `EXPORT_ES6` option, in which the factory function will be the
+	 * default export. If used without `EXPORT_ES6`, the factory function will be a
+	 * global variable. You can rename the variable using the `EXPORT_NAME` build
+	 * option. It's left to you to export any global variables as needed in your
+	 * application's types.
+	 * @param moduleOverrides Default properties for the initialized module.
+	 */
+	export type EmscriptenModuleFactory<T extends EmscriptenModule = EmscriptenModule> = (moduleOverrides?: Partial<T>) => Promise<T>;
+	export namespace FS {
+		interface Lookup {
+			path: string;
+			node: FSNode;
+		}
+		interface Analyze {
+			isRoot: boolean;
+			exists: boolean;
+			error: Error;
+			name: string;
+			path: Lookup["path"];
+			object: Lookup["node"];
+			parentExists: boolean;
+			parentPath: Lookup["path"];
+			parentObject: Lookup["node"];
+		}
+		interface Mount {
+			type: Emscripten.FileSystemType;
+			opts: object;
+			mountpoint: string;
+			mounts: Mount[];
+			root: FSNode;
+		}
+		class FSStream {
+			constructor();
+			object: FSNode;
+			readonly isRead: boolean;
+			readonly isWrite: boolean;
+			readonly isAppend: boolean;
+			flags: number;
+			position: number;
+		}
+		class FSNode {
+			parent: FSNode;
+			mount: Mount;
+			mounted?: Mount;
+			id: number;
+			name: string;
+			mode: number;
+			rdev: number;
+			readMode: number;
+			writeMode: number;
+			constructor(parent: FSNode, name: string, mode: number, rdev: number);
+			read: boolean;
+			write: boolean;
+			readonly isFolder: boolean;
+			readonly isDevice: boolean;
+		}
+		interface ErrnoError extends Error {
+			name: "ErronoError";
+			errno: number;
+			code: string;
+		}
+		function lookupPath(path: string, opts: any): Lookup;
+		function getPath(node: FSNode): string;
+		function analyzePath(path: string, dontResolveLastLink?: boolean): Analyze;
+		function isFile(mode: number): boolean;
+		function isDir(mode: number): boolean;
+		function isLink(mode: number): boolean;
+		function isChrdev(mode: number): boolean;
+		function isBlkdev(mode: number): boolean;
+		function isFIFO(mode: number): boolean;
+		function isSocket(mode: number): boolean;
+		function major(dev: number): number;
+		function minor(dev: number): number;
+		function makedev(ma: number, mi: number): number;
+		function registerDevice(dev: number, ops: any): void;
+		function syncfs(populate: boolean, callback: (e: any) => any): void;
+		function syncfs(callback: (e: any) => any, populate?: boolean): void;
+		function mount(type: Emscripten.FileSystemType, opts: any, mountpoint: string): any;
+		function unmount(mountpoint: string): void;
+		function mkdir(path: string, mode?: number): any;
+		function mkdev(path: string, mode?: number, dev?: number): any;
+		function symlink(oldpath: string, newpath: string): any;
+		function rename(old_path: string, new_path: string): void;
+		function rmdir(path: string): void;
+		function readdir(path: string): any;
+		function unlink(path: string): void;
+		function readlink(path: string): string;
+		function stat(path: string, dontFollow?: boolean): any;
+		function lstat(path: string): any;
+		function chmod(path: string, mode: number, dontFollow?: boolean): void;
+		function lchmod(path: string, mode: number): void;
+		function fchmod(fd: number, mode: number): void;
+		function chown(path: string, uid: number, gid: number, dontFollow?: boolean): void;
+		function lchown(path: string, uid: number, gid: number): void;
+		function fchown(fd: number, uid: number, gid: number): void;
+		function truncate(path: string, len: number): void;
+		function ftruncate(fd: number, len: number): void;
+		function utime(path: string, atime: number, mtime: number): void;
+		function open(path: string, flags: string, mode?: number, fd_start?: number, fd_end?: number): FSStream;
+		function close(stream: FSStream): void;
+		function llseek(stream: FSStream, offset: number, whence: number): any;
+		function read(stream: FSStream, buffer: ArrayBufferView, offset: number, length: number, position?: number): number;
+		function write(stream: FSStream, buffer: ArrayBufferView, offset: number, length: number, position?: number, canOwn?: boolean): number;
+		function allocate(stream: FSStream, offset: number, length: number): void;
+		function mmap(stream: FSStream, buffer: ArrayBufferView, offset: number, length: number, position: number, prot: number, flags: number): any;
+		function ioctl(stream: FSStream, cmd: any, arg: any): any;
+		function readFile(path: string, opts: {
+			encoding: "binary";
+			flags?: string | undefined;
+		}): Uint8Array;
+		function readFile(path: string, opts: {
+			encoding: "utf8";
+			flags?: string | undefined;
+		}): string;
+		function readFile(path: string, opts?: {
+			flags?: string | undefined;
+		}): Uint8Array;
+		function writeFile(path: string, data: string | ArrayBufferView, opts?: {
+			flags?: string | undefined;
+		}): void;
+		function cwd(): string;
+		function chdir(path: string): void;
+		function init(input: null | (() => number | null), output: null | ((c: number) => any), error: null | ((c: number) => any)): void;
+		function createLazyFile(parent: string | FSNode, name: string, url: string, canRead: boolean, canWrite: boolean): FSNode;
+		function createPreloadedFile(parent: string | FSNode, name: string, url: string, canRead: boolean, canWrite: boolean, onload?: () => void, onerror?: () => void, dontCreateFile?: boolean, canOwn?: boolean): void;
+		function createDataFile(parent: string | FSNode, name: string, data: ArrayBufferView, canRead: boolean, canWrite: boolean, canOwn: boolean): FSNode;
+	}
+	export const MEMFS: Emscripten.FileSystemType;
+	export const NODEFS: Emscripten.FileSystemType;
+	export const IDBFS: Emscripten.FileSystemType;
+	type StringToType<R> = R extends Emscripten.JSType ? {
+		number: number;
+		string: string;
+		array: number[] | string[] | boolean[] | Uint8Array | Int8Array;
+		boolean: boolean;
+		null: null;
+	}[R] : never;
+	type ArgsToType<T extends Array<Emscripten.JSType | null>> = Extract<{
+		[P in keyof T]: StringToType<T[P]>;
+	}, any[]>;
+	type ReturnToType<R extends Emscripten.JSType | null> = R extends null ? null : StringToType<Exclude<R, null>>;
+	export function cwrap<I extends Array<Emscripten.JSType | null> | [
+	], R extends Emscripten.JSType | null>(ident: string, returnType: R, argTypes: I, opts?: Emscripten.CCallOpts): (...arg: ArgsToType<I>) => ReturnToType<R>;
+	export function ccall<I extends Array<Emscripten.JSType | null> | [
+	], R extends Emscripten.JSType | null>(ident: string, returnType: R, argTypes: I, args: ArgsToType<I>, opts?: Emscripten.CCallOpts): ReturnToType<R>;
+	export function setValue(ptr: number, value: any, type: Emscripten.CType, noSafe?: boolean): void;
+	export function getValue(ptr: number, type: Emscripten.CType, noSafe?: boolean): number;
+	export function allocate(slab: number[] | ArrayBufferView | number, types: Emscripten.CType | Emscripten.CType[], allocator: number, ptr?: number): number;
+	export function stackAlloc(size: number): number;
+	export function stackSave(): number;
+	export function stackRestore(ptr: number): void;
+	export function UTF8ToString(ptr: number, maxBytesToRead?: number): string;
+	export function stringToUTF8(str: string, outPtr: number, maxBytesToRead?: number): void;
+	export function lengthBytesUTF8(str: string): number;
+	export function allocateUTF8(str: string): number;
+	export function allocateUTF8OnStack(str: string): number;
+	export function UTF16ToString(ptr: number): string;
+	export function stringToUTF16(str: string, outPtr: number, maxBytesToRead?: number): void;
+	export function lengthBytesUTF16(str: string): number;
+	export function UTF32ToString(ptr: number): string;
+	export function stringToUTF32(str: string, outPtr: number, maxBytesToRead?: number): void;
+	export function lengthBytesUTF32(str: string): number;
+	export function intArrayFromString(stringy: string, dontAddNull?: boolean, length?: number): number[];
+	export function intArrayToString(array: number[]): string;
+	export function writeStringToMemory(str: string, buffer: number, dontAddNull: boolean): void;
+	export function writeArrayToMemory(array: number[], buffer: number): void;
+	export function writeAsciiToMemory(str: string, buffer: number, dontAddNull: boolean): void;
+	export function addRunDependency(id: any): void;
+	export function removeRunDependency(id: any): void;
+	export function addFunction(func: (...args: any[]) => any, signature?: string): number;
+	export function removeFunction(funcPtr: number): void;
+	export const ALLOC_NORMAL: number;
+	export const ALLOC_STACK: number;
+	export const ALLOC_STATIC: number;
+	export const ALLOC_DYNAMIC: number;
+	export const ALLOC_NONE: number;
+	export {};
 }
-/**
- * Represents an error event related to the PHP request.
- */
-export interface PHPRequestErrorEvent {
-	type: "request.error";
-	error: Error;
-	source?: "request" | "php-wasm";
+export interface RmDirOptions {
+	/**
+	 * If true, recursively removes the directory and all its contents.
+	 * Default: true.
+	 */
+	recursive?: boolean;
 }
-/**
- * Represents a PHP runtime initialization event.
- */
-export interface PHPRuntimeInitializedEvent {
-	type: "runtime.initialized";
+export interface ListFilesOptions {
+	/**
+	 * If true, prepend given folder path to all file names.
+	 * Default: false.
+	 */
+	prependPath: boolean;
 }
-/**
- * Represents a PHP runtime destruction event.
- */
-export interface PHPRuntimeBeforeDestroyEvent {
-	type: "runtime.beforedestroy";
+export interface SemaphoreOptions {
+	/**
+	 * The maximum number of concurrent locks.
+	 */
+	concurrency: number;
+	/**
+	 * The maximum time to wait for a lock to become available.
+	 */
+	timeout?: number;
 }
-/**
- * Represents an event related to the PHP instance.
- * This is intentionally not an extension of CustomEvent
- * to make it isomorphic between different JavaScript runtimes.
- */
-export type PHPEvent = PHPRequestEndEvent | PHPRequestErrorEvent | PHPRuntimeInitializedEvent | PHPRuntimeBeforeDestroyEvent;
-/**
- * A callback function that handles PHP events.
- */
-export type PHPEventListener = (event: PHPEvent) => void;
-export interface IsomorphicLocalPHP {
-	/** @deprecated Use PHPRequestHandler instead. */
-	request(request: PHPRequest): Promise<PHPResponse>;
-	/** @deprecated Use PHPRequestHandler instead. */
-	pathToInternalUrl(path: string): string;
-	/** @deprecated Use PHPRequestHandler instead. */
-	internalUrlToPath(internalUrl: string): string;
-	/** @deprecated Use PHPRequestHandler instead. */
-	absoluteUrl: string;
-	/** @deprecated Use PHPRequestHandler instead. */
-	documentRoot: string;
+declare class Semaphore {
+	private _running;
+	private concurrency;
+	private timeout?;
+	private queue;
+	constructor({ concurrency, timeout }: SemaphoreOptions);
+	get remaining(): number;
+	get running(): number;
+	acquire(): Promise<() => void>;
+	run<T>(fn: () => T | Promise<T>): Promise<T>;
+}
+export type PHPFactoryOptions = {
+	isPrimary: boolean;
+};
+export type PHPFactory = (options: PHPFactoryOptions) => Promise<PHP>;
+export interface ProcessManagerOptions {
 	/**
-	 * Sets the SAPI name exposed by the PHP module.
-	 * @param newName - The new SAPI name.
+	 * The maximum number of PHP instances that can exist at
+	 * the same time.
 	 */
-	setSapiName(newName: string): void;
+	maxPhpInstances?: number;
 	/**
-	 * Defines a constant in the PHP runtime.
-	 * @param key - The name of the constant.
-	 * @param value - The value of the constant.
+	 * The number of milliseconds to wait for a PHP instance when
+	 * we have reached the maximum number of PHP instances and
+	 * cannot spawn a new one. If the timeout is reached, we assume
+	 * all the PHP instances are deadlocked and a throw MaxPhpInstancesError.
+	 *
+	 * Default: 5000
 	 */
-	defineConstant(key: string, value: boolean | string | number | null): void;
+	timeout?: number;
 	/**
-	 * Adds an event listener for a PHP event.
-	 * @param eventType - The type of event to listen for.
-	 * @param listener - The listener function to be called when the event is triggered.
+	 * The primary PHP instance that's never killed. This instance
+	 * contains the reference filesystem used by all other PHP instances.
 	 */
-	addEventListener(eventType: PHPEvent["type"], listener: PHPEventListener): void;
+	primaryPhp?: PHP;
 	/**
-	 * Removes an event listener for a PHP event.
-	 * @param eventType - The type of event to remove the listener from.
-	 * @param listener - The listener function to be removed.
+	 * A factory function used for spawning new PHP instances.
 	 */
-	removeEventListener(eventType: PHPEvent["type"], listener: PHPEventListener): void;
+	phpFactory?: PHPFactory;
+}
+export interface SpawnedPHP {
+	php: PHP;
+	reap: () => void;
+}
+declare class PHPProcessManager implements AsyncDisposable {
+	private primaryPhp?;
+	private primaryIdle;
+	private nextInstance;
 	/**
-	 * Sets the path to the php.ini file to use for the PHP instance.
-	 *
-	 * @param path - The path to the php.ini file.
+	 * All spawned PHP instances, including the primary PHP instance.
+	 * Used for bookkeeping and reaping all instances on dispose.
 	 */
-	setPhpIniPath(path: string): void;
+	private allInstances;
+	private phpFactory?;
+	private maxPhpInstances;
+	private semaphore;
+	constructor(options?: ProcessManagerOptions);
 	/**
-	 * Sets a value for a specific key in the php.ini file for the PHP instance.
+	 * Get the primary PHP instance.
 	 *
-	 * @param key - The key to set the value for.
-	 * @param value - The value to set for the key.
+	 * If the primary PHP instance is not set, it will be spawned
+	 * using the provided phpFactory.
+	 *
+	 * @throws {Error} when called twice before the first call is resolved.
 	 */
-	setPhpIniEntry(key: string, value: string): void;
+	getPrimaryPhp(): Promise<PHP>;
 	/**
-	 * Recursively creates a directory with the given path in the PHP filesystem.
-	 * For example, if the path is `/root/php/data`, and `/root` already exists,
-	 * it will create the directories `/root/php` and `/root/php/data`.
+	 * Get a PHP instance.
 	 *
-	 * @param  path - The directory path to create.
+	 * It could be either the primary PHP instance, an idle disposable PHP instance,
+	 * or a newly spawned PHP instance – depending on the resource availability.
+	 *
+	 * @throws {MaxPhpInstancesError} when the maximum number of PHP instances is reached
+	 *                                and the waiting timeout is exceeded.
 	 */
-	mkdir(path: string): void;
+	acquirePHPInstance(): Promise<SpawnedPHP>;
 	/**
-	 * @deprecated Use mkdir instead.
+	 * Initiated spawning of a new PHP instance.
+	 * This function is synchronous on purpose – it needs to synchronously
+	 * add the spawn promise to the allInstances array without waiting
+	 * for PHP to spawn.
 	 */
-	mkdirTree(path: string): void;
+	private spawn;
 	/**
-	 * Reads a file from the PHP filesystem and returns it as a string.
-	 *
-	 * @throws {@link @php-wasm/universal:ErrnoError} – If the file doesn't exist.
-	 * @param  path - The file path to read.
-	 * @returns The file contents.
+	 * Actually acquires the lock and spawns a new PHP instance.
 	 */
-	readFileAsText(path: string): string;
+	private doSpawn;
+	[Symbol.asyncDispose](): Promise<void>;
+}
+export type RewriteRule = {
+	match: RegExp;
+	replacement: string;
+};
+export interface BaseConfiguration {
 	/**
-	 * Reads a file from the PHP filesystem and returns it as an array buffer.
-	 *
-	 * @throws {@link @php-wasm/universal:ErrnoError} – If the file doesn't exist.
-	 * @param  path - The file path to read.
-	 * @returns The file contents.
+	 * The directory in the PHP filesystem where the server will look
+	 * for the files to serve. Default: `/var/www`.
 	 */
-	readFileAsBuffer(path: string): Uint8Array;
+	documentRoot?: string;
 	/**
-	 * Overwrites data in a file in the PHP filesystem.
-	 * Creates a new file if one doesn't exist yet.
-	 *
-	 * @param  path - The file path to write to.
-	 * @param  data - The data to write to the file.
+	 * Request Handler URL. Used to populate $_SERVER details like HTTP_HOST.
 	 */
-	writeFile(path: string, data: string | Uint8Array): void;
+	absoluteUrl?: string;
 	/**
-	 * Removes a file from the PHP filesystem.
+	 * Rewrite rules
+	 */
+	rewriteRules?: RewriteRule[];
+}
+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.
 	 *
-	 * @throws {@link @php-wasm/universal:ErrnoError} – If the file doesn't exist.
-	 * @param  path - The file path to remove.
+	 * 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;
+});
+declare class PHPRequestHandler {
+	#private;
+	rewriteRules: RewriteRule[];
+	processManager: PHPProcessManager;
+	/**
+	 * The request handler needs to decide whether to serve a static asset or
+	 * run the PHP interpreter. For static assets it should just reuse the primary
+	 * PHP even if there's 50 concurrent requests to serve. However, for
+	 * dynamic PHP requests, it needs to grab an available interpreter.
+	 * Therefore, it cannot just accept PHP as an argument as serving requests
+	 * requires access to ProcessManager.
+	 *
+	 * @param  php    - The PHP instance.
+	 * @param  config - Request Handler configuration.
 	 */
-	unlink(path: string): void;
+	constructor(config: PHPRequestHandlerConfiguration);
+	getPrimaryPhp(): Promise<PHP>;
 	/**
-	 * Moves a file or directory in the PHP filesystem to a
-	 * new location.
+	 * Converts a path to an absolute URL based at the PHPRequestHandler
+	 * root.
 	 *
-	 * @param oldPath The path to rename.
-	 * @param newPath The new path.
+	 * @param  path The server path to convert to an absolute URL.
+	 * @returns The absolute URL.
 	 */
-	mv(oldPath: string, newPath: string): void;
+	pathToInternalUrl(path: string): string;
 	/**
-	 * Removes a directory from the PHP filesystem.
+	 * Converts an absolute URL based at the PHPRequestHandler to a relative path
+	 * without the server pathname and scope.
 	 *
-	 * @param path The directory path to remove.
-	 * @param options Options for the removal.
+	 * @param  internalUrl An absolute URL based at the PHPRequestHandler root.
+	 * @returns The relative path.
 	 */
-	rmdir(path: string, options?: RmDirOptions): void;
+	internalUrlToPath(internalUrl: string): string;
 	/**
-	 * Lists the files and directories in the given directory.
+	 * The absolute URL of this PHPRequestHandler instance.
+	 */
+	get absoluteUrl(): string;
+	/**
+	 * The directory in the PHP filesystem where the server will look
+	 * for the files to serve. Default: `/var/www`.
+	 */
+	get documentRoot(): string;
+	/**
+	 * Serves the request – either by serving a static file, or by
+	 * dispatching it to the PHP runtime.
 	 *
-	 * @param  path - The directory path to list.
-	 * @param  options - Options for the listing.
-	 * @returns The list of files and directories in the given directory.
+	 * 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.
 	 */
-	listFiles(path: string, options?: ListFilesOptions): string[];
+	request(request: PHPRequest): Promise<PHPResponse>;
+}
+declare const __private__dont__use: unique symbol;
+export type UnmountFunction = (() => Promise<any>) | (() => any);
+export type MountHandler = (php: PHP, FS: Emscripten.RootFS, vfsMountPoint: string) => UnmountFunction | Promise<UnmountFunction>;
+declare class PHP implements Disposable {
+	#private;
+	protected [__private__dont__use]: any;
+	requestHandler?: PHPRequestHandler;
 	/**
-	 * Checks if a directory exists in the PHP filesystem.
+	 * An exclusive lock that prevent multiple requests from running at
+	 * the same time.
+	 */
+	semaphore: Semaphore;
+	/**
+	 * Initializes a PHP runtime.
 	 *
-	 * @param  path – The path to check.
-	 * @returns True if the path is a directory, false otherwise.
+	 * @internal
+	 * @param  PHPRuntime - Optional. PHP Runtime ID as initialized by loadPHPRuntime.
+	 * @param  requestHandlerOptions - Optional. Options for the PHPRequestHandler. If undefined, no request handler will be initialized.
 	 */
-	isDir(path: string): boolean;
+	constructor(PHPRuntimeId?: PHPRuntimeId);
 	/**
-	 * Checks if a file (or a directory) exists in the PHP filesystem.
+	 * Adds an event listener for a PHP event.
+	 * @param eventType - The type of event to listen for.
+	 * @param listener - The listener function to be called when the event is triggered.
+	 */
+	addEventListener(eventType: PHPEvent["type"], listener: PHPEventListener): void;
+	/**
+	 * Removes an event listener for a PHP event.
+	 * @param eventType - The type of event to remove the listener from.
+	 * @param listener - The listener function to be removed.
+	 */
+	removeEventListener(eventType: PHPEvent["type"], listener: PHPEventListener): void;
+	dispatchEvent<Event extends PHPEvent>(event: Event): void;
+	/**
+	 * Listens to message sent by the PHP code.
 	 *
-	 * @param  path - The file path to check.
-	 * @returns True if the file exists, false otherwise.
+	 * To dispatch messages, call:
+	 *
+	 *     post_message_to_js(string $data)
+	 *
+	 *     Arguments:
+	 *         $data (string) – Data to pass to JavaScript.
+	 *
+	 * @example
+	 *
+	 * ```ts
+	 * const php = await PHP.load('8.0');
+	 *
+	 * php.onMessage(
+	 *     // The data is always passed as a string
+	 *     function (data: string) {
+	 *         // Let's decode and log the data:
+	 *         console.log(JSON.parse(data));
+	 *     }
+	 * );
+	 *
+	 * // Now that we have a listener in place, let's
+	 * // dispatch a message:
+	 * await php.run({
+	 *     code: `<?php
+	 *         post_message_to_js(
+	 *             json_encode([
+	 *                 'post_id' => '15',
+	 *                 'post_title' => 'This is a blog post!'
+	 *             ])
+	 *         ));
+	 *     `,
+	 * });
+	 * ```
+	 *
+	 * @param listener Callback function to handle the message.
 	 */
-	fileExists(path: string): boolean;
+	onMessage(listener: MessageListener): void;
+	setSpawnHandler(handler: SpawnHandler | string): Promise<void>;
+	/** @deprecated Use PHPRequestHandler instead. */
+	get absoluteUrl(): string;
+	/** @deprecated Use PHPRequestHandler instead. */
+	get documentRoot(): string;
+	/** @deprecated Use PHPRequestHandler instead. */
+	pathToInternalUrl(path: string): string;
+	/** @deprecated Use PHPRequestHandler instead. */
+	internalUrlToPath(internalUrl: string): string;
+	initializeRuntime(runtimeId: PHPRuntimeId): void;
+	/** @inheritDoc */
+	setSapiName(newName: string): Promise<void>;
 	/**
 	 * Changes the current working directory in the PHP filesystem.
 	 * This is the directory that will be used as the base for relative paths.
@@ -354,6 +792,11 @@ export interface IsomorphicLocalPHP {
 	 * @param  path - The new working directory.
 	 */
 	chdir(path: string): void;
+	/**
+	 * Do not use. Use new PHPRequestHandler() instead.
+	 * @deprecated
+	 */
+	request(request: PHPRequest): Promise<PHPResponse>;
 	/**
 	 * Runs PHP code.
 	 *
@@ -423,57 +866,181 @@ export interface IsomorphicLocalPHP {
 	 *
 	 * @param  options - PHP runtime options.
 	 */
-	run(options: PHPRunOptions): Promise<PHPResponse>;
+	run(request: PHPRunOptions): Promise<PHPResponse>;
 	/**
-	 * Listens to message sent by the PHP code.
+	 * Defines a constant in the PHP runtime.
+	 * @param key - The name of the constant.
+	 * @param value - The value of the constant.
+	 */
+	defineConstant(key: string, value: string | boolean | number | null): void;
+	/**
+	 * Recursively creates a directory with the given path in the PHP filesystem.
+	 * For example, if the path is `/root/php/data`, and `/root` already exists,
+	 * it will create the directories `/root/php` and `/root/php/data`.
 	 *
-	 * To dispatch messages, call:
+	 * @param  path - The directory path to create.
+	 */
+	mkdir(path: string): void;
+	/**
+	 * @deprecated Use mkdir instead.
+	 */
+	mkdirTree(path: string): void;
+	/**
+	 * Reads a file from the PHP filesystem and returns it as a string.
 	 *
-	 *     post_message_to_js(string $data)
+	 * @throws {@link @php-wasm/universal:ErrnoError} – If the file doesn't exist.
+	 * @param  path - The file path to read.
+	 * @returns The file contents.
+	 */
+	readFileAsText(path: string): string;
+	/**
+	 * Reads a file from the PHP filesystem and returns it as an array buffer.
 	 *
-	 *     Arguments:
-	 *         $data (string) – Data to pass to JavaScript.
+	 * @throws {@link @php-wasm/universal:ErrnoError} – If the file doesn't exist.
+	 * @param  path - The file path to read.
+	 * @returns The file contents.
+	 */
+	readFileAsBuffer(path: string): Uint8Array;
+	/**
+	 * Overwrites data in a file in the PHP filesystem.
+	 * Creates a new file if one doesn't exist yet.
 	 *
-	 * @example
+	 * @param  path - The file path to write to.
+	 * @param  data - The data to write to the file.
+	 */
+	writeFile(path: string, data: string | Uint8Array): void;
+	/**
+	 * Removes a file from the PHP filesystem.
 	 *
-	 * ```ts
-	 * const php = await PHP.load('8.0');
+	 * @throws {@link @php-wasm/universal:ErrnoError} – If the file doesn't exist.
+	 * @param  path - The file path to remove.
+	 */
+	unlink(path: string): void;
+	/**
+	 * Moves a file or directory in the PHP filesystem to a
+	 * new location.
 	 *
-	 * php.onMessage(
-	 *     // The data is always passed as a string
-	 *     function (data: string) {
-	 *         // Let's decode and log the data:
-	 *         console.log(JSON.parse(data));
-	 *     }
-	 * );
+	 * @param oldPath The path to rename.
+	 * @param newPath The new path.
+	 */
+	mv(fromPath: string, toPath: string): void;
+	/**
+	 * Removes a directory from the PHP filesystem.
 	 *
-	 * // Now that we have a listener in place, let's
-	 * // dispatch a message:
-	 * await php.run({
-	 *     code: `<?php
-	 *         post_message_to_js(
-	 *             json_encode([
-	 *                 'post_id' => '15',
-	 *                 'post_title' => 'This is a blog post!'
-	 *             ])
-	 *         ));
-	 *     `,
-	 * });
-	 * ```
+	 * @param path The directory path to remove.
+	 * @param options Options for the removal.
+	 */
+	rmdir(path: string, options?: RmDirOptions): void;
+	/**
+	 * Lists the files and directories in the given directory.
 	 *
-	 * @param listener Callback function to handle the message.
+	 * @param  path - The directory path to list.
+	 * @param  options - Options for the listing.
+	 * @returns The list of files and directories in the given directory.
 	 */
-	onMessage(listener: MessageListener): void;
+	listFiles(path: string, options?: ListFilesOptions): string[];
+	/**
+	 * Checks if a directory exists in the PHP filesystem.
+	 *
+	 * @param  path – The path to check.
+	 * @returns True if the path is a directory, false otherwise.
+	 */
+	isDir(path: string): boolean;
+	/**
+	 * Checks if a file (or a directory) exists in the PHP filesystem.
+	 *
+	 * @param  path - The file path to check.
+	 * @returns True if the file exists, false otherwise.
+	 */
+	fileExists(path: string): boolean;
+	/**
+	 * Hot-swaps the PHP runtime for a new one without
+	 * 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, cwd?: string): void;
+	/**
+	 * Mounts a filesystem to a given path in the PHP filesystem.
+	 *
+	 * @param  virtualFSPath - Where to mount it in the PHP virtual filesystem.
+	 * @param  mountHandler - The mount handler to use.
+	 * @return Unmount function to unmount the filesystem.
+	 */
+	mount(virtualFSPath: string, mountHandler: MountHandler): Promise<UnmountFunction>;
+	/**
+	 * Starts a PHP CLI session with given arguments.
+	 *
+	 * This method can only be used when PHP was compiled with the CLI SAPI
+	 * and it cannot be used in conjunction with `run()`.
+	 *
+	 * Once this method finishes running, the PHP instance is no
+	 * longer usable and should be discarded. This is because PHP
+	 * internally cleans up all the resources and calls exit().
+	 *
+	 * @param  argv - The arguments to pass to the CLI.
+	 * @returns The exit code of the CLI session.
+	 */
+	cli(argv: string[]): Promise<number>;
+	setSkipShebang(shouldSkip: boolean): void;
+	exit(code?: number): void;
+	[Symbol.dispose](): void;
 }
-export type MessageListener = (data: string) => Promise<string | Uint8Array | void> | string | void;
+export type LimitedPHPApi = Pick<PHP, "request" | "defineConstant" | "addEventListener" | "removeEventListener" | "mkdir" | "mkdirTree" | "readFileAsText" | "readFileAsBuffer" | "writeFile" | "unlink" | "mv" | "rmdir" | "listFiles" | "isDir" | "fileExists" | "chdir" | "run" | "onMessage"> & {
+	documentRoot: PHP["documentRoot"];
+	absoluteUrl: PHP["absoluteUrl"];
+};
 /**
- * The omited methods must either be called synchronously before
- * the PHP internal state is initialized, or with a complex argument
- * that can't be serialized over a remote connection. Therefeore,
- * they don't make sense in a remote PHP instance.
+ * Represents an event related to the PHP request.
+ */
+export interface PHPRequestEndEvent {
+	type: "request.end";
+}
+/**
+ * Represents an error event related to the PHP request.
  */
-export type IsomorphicRemotePHP = Remote<Omit<IsomorphicLocalPHP, "setSapiName" | "setPhpIniEntry" | "setPhpIniPath">>;
-export type UniversalPHP = IsomorphicLocalPHP | IsomorphicRemotePHP;
+export interface PHPRequestErrorEvent {
+	type: "request.error";
+	error: Error;
+	source?: "request" | "php-wasm";
+}
+/**
+ * Represents a PHP runtime initialization event.
+ */
+export interface PHPRuntimeInitializedEvent {
+	type: "runtime.initialized";
+}
+/**
+ * Represents a PHP runtime destruction event.
+ */
+export interface PHPRuntimeBeforeDestroyEvent {
+	type: "runtime.beforedestroy";
+}
+/**
+ * Represents an event related to the PHP instance.
+ * This is intentionally not an extension of CustomEvent
+ * to make it isomorphic between different JavaScript runtimes.
+ */
+export type PHPEvent = PHPRequestEndEvent | PHPRequestErrorEvent | PHPRuntimeInitializedEvent | PHPRuntimeBeforeDestroyEvent;
+/**
+ * A callback function that handles PHP events.
+ */
+export type PHPEventListener = (event: PHPEvent) => void;
+export type UniversalPHP = LimitedPHPApi | Remote<LimitedPHPApi>;
+export type MessageListener = (data: string) => Promise<string | Uint8Array | void> | string | void;
+export interface EventEmitter {
+	on(event: string, listener: (...args: any[]) => void): this;
+	emit(event: string, ...args: any[]): boolean;
+}
+export type ChildProcess = EventEmitter & {
+	stdout: EventEmitter;
+	stderr: EventEmitter;
+};
+export type SpawnHandler = (command: string, args: string[]) => ChildProcess;
 export type HTTPMethod = "GET" | "POST" | "HEAD" | "OPTIONS" | "PATCH" | "PUT" | "DELETE";
 export type PHPRequestHeaders = Record<string, string>;
 export interface PHPRequest {
@@ -534,41 +1101,6 @@ export interface PHPRunOptions {
 	 */
 	code?: string;
 }
-export interface RmDirOptions {
-	/**
-	 * If true, recursively removes the directory and all its contents.
-	 * Default: true.
-	 */
-	recursive?: boolean;
-}
-export interface ListFilesOptions {
-	/**
-	 * If true, prepend given folder path to all file names.
-	 * Default: false.
-	 */
-	prependPath: boolean;
-}
-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, timeout }: SemaphoreOptions);
-	get remaining(): number;
-	get running(): number;
-	acquire(): Promise<() => void>;
-	run<T>(fn: () => T | Promise<T>): Promise<T>;
-}
 declare const SupportedPHPVersions: readonly [
 	"8.3",
 	"8.2",
@@ -825,10 +1357,10 @@ export interface DefineSiteUrlStep {
 	siteUrl: string;
 }
 /**
- * Sets WP_HOME and WP_SITEURL constants for the WordPress installation.
+ * Sets [`WP_HOME`](https://developer.wordpress.org/advanced-administration/wordpress/wp-config/#blog-address-url) and [`WP_SITEURL`](https://developer.wordpress.org/advanced-administration/wordpress/wp-config/#wp-siteurl) constants for the WordPress installation.
  *
- * Beware: Using this step makes no sense on playground.wordpress.net.
- * It is useful when you're building a custom Playground-based tool like wp-now,
+ * Using this step on playground.wordpress.net is moot.
+ * It is useful when building a custom Playground-based tool, like [`wp-now`](https://www.npmjs.com/package/@wp-now/wp-now),
  * or deploying Playground on a custom domain.
  *
  * @param playground The playground client.
@@ -979,8 +1511,8 @@ export type LoginStep = {
 	password?: string;
 };
 /**
- * Logs in to the Playground.
- * Under the hood, this function submits the wp-login.php form
+ * Logs in to Playground.
+ * Under the hood, this function submits the [`wp-login.php`](https://developer.wordpress.org/reference/files/wp-login.php/) [form](https://developer.wordpress.org/reference/functions/wp_login_form/)
  * just like a user would.
  */
 export declare const login: StepHandler<LoginStep>;
@@ -1025,8 +1557,8 @@ export type SetSiteOptionsStep = {
 	options: Record<string, unknown>;
 };
 /**
- * Sets site options. This is equivalent to calling `update_option` for each
- * option in the `options` object.
+ * Sets site options. This is equivalent to calling [`update_option`](https://developer.wordpress.org/reference/functions/update_option/) for each
+ * option in the [`options`](https://developer.wordpress.org/apis/options/#available-options-by-category) object.
  */
 export declare const setSiteOptions: StepHandler<SetSiteOptionsStep>;
 /**
@@ -1054,7 +1586,7 @@ export interface UpdateUserMetaStep {
 	userId: number;
 }
 /**
- * Updates user meta. This is equivalent to calling `update_user_meta` for each
+ * Updates user meta. This is equivalent to calling [`update_user_meta`](https://developer.wordpress.org/reference/functions/update_user_meta/) for each
  * meta value in the `meta` object.
  */
 export declare const updateUserMeta: StepHandler<UpdateUserMetaStep>;
@@ -1227,6 +1759,7 @@ export interface RunPHPStep {
 }
 /**
  * Runs PHP code.
+ * When running WordPress functions, the `code` key must first load [`wp-load.php`](https://github.com/WordPress/WordPress/blob/master/wp-load.php) and start with `"<?php require_once 'wordpress/wp-load.php'; "`.
  */
 export declare const runPHP: StepHandler<RunPHPStep, Promise<PHPResponse>>;
 /**
@@ -1249,7 +1782,7 @@ export declare const runPHP: StepHandler<RunPHPStep, Promise<PHPResponse>>;
 export interface RunPHPWithOptionsStep {
 	step: "runPHPWithOptions";
 	/**
-	 * Run options (See /wordpress-playground/api/universal/interface/PHPRunOptions)
+	 * Run options (See /wordpress-playground/api/universal/interface/PHPRunOptions/))
 	 */
 	options: PHPRunOptions;
 }
@@ -1286,7 +1819,7 @@ export interface RequestStep {
 	request: PHPRequest;
 }
 /**
- * Sends a HTTP request to the Playground.
+ * Sends a HTTP request to Playground.
  */
 export declare const request: StepHandler<RequestStep, Promise<PHPResponse>>;
 /**
@@ -1333,13 +1866,14 @@ export interface DefineWpConfigConstsStep {
 	/** The constants to define */
 	consts: Record<string, unknown>;
 	/**
-	 * The method of defining the constants. Possible values are:
+	 * The method of defining the constants in wp-config.php. Possible values are:
 	 *
 	 * - rewrite-wp-config: Default. Rewrites the wp-config.php file to
 	 *                      explicitly call define() with the requested
 	 *                      name and value. This method alters the file
 	 *                      on the disk, but it doesn't conflict with
 	 *                      existing define() calls in wp-config.php.
+	 *
 	 * - define-before-run: Defines the constant before running the requested
 	 *                      script. It doesn't alter any files on the disk, but
 	 *                      constants defined this way may conflict with existing
@@ -1354,7 +1888,7 @@ export interface DefineWpConfigConstsStep {
 	virtualize?: boolean;
 }
 /**
- * Defines constants in a wp-config.php file.
+ * Defines constants in a [`wp-config.php`](https://developer.wordpress.org/advanced-administration/wordpress/wp-config/) file.
  *
  * This step can be called multiple times, and the constants will be merged.
  *
@@ -1450,9 +1984,9 @@ export interface ImportWordPressFilesStep<ResourceType> {
 }
 /**
  * Imports top-level WordPress files from a given zip file into
- * the documentRoot. For example, if a zip file contains the
+ * the `documentRoot`. For example, if a zip file contains the
  * `wp-content` and `wp-includes` directories, they will replace
- * the corresponding directories in Playground's documentRoot.
+ * the corresponding directories in Playground's `documentRoot`.
  *
  * Any files that Playground recognizes as "excluded from the export"
  * will carry over from the existing document root into the imported
@@ -1503,7 +2037,7 @@ export interface EnableMultisiteStep {
 	step: "enableMultisite";
 }
 /**
- * Defines constants in a wp-config.php file.
+ * Defines the [Multisite](https://developer.wordpress.org/advanced-administration/multisite/create-network/) constants in a `wp-config.php` file.
  *
  * This step can be called multiple times, and the constants will be merged.
  *
@@ -1532,9 +2066,31 @@ export interface WPCLIStep {
 	wpCliPath?: string;
 }
 /**
- * Runs PHP code.
+ * Runs PHP code using [WP-CLI](https://developer.wordpress.org/cli/commands/).
  */
 export declare const wpCLI: StepHandler<WPCLIStep, Promise<PHPResponse>>;
+/**
+ * Deletes WordPress posts and comments and sets the auto increment sequence for the
+ * posts and comments tables to 0.
+ *
+ * @private
+ * @internal
+ * @inheritDoc resetData
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "resetData"
+ * }
+ * </code>
+ */
+export interface ResetDataStep {
+	step: "resetData";
+}
+/**
+ * @param playground Playground client.
+ */
+export declare const resetData: StepHandler<ResetDataStep>;
 /**
  * Used by the export step to exclude the Playground-specific files
  * from the zip file. Keep it in sync with the list of files created
@@ -1552,7 +2108,7 @@ export type StepDefinition = Step & {
  * If you add a step here, make sure to also
  * add it to the exports below.
  */
-export type GenericStep<Resource> = ActivatePluginStep | ActivateThemeStep | CpStep | DefineWpConfigConstsStep | DefineSiteUrlStep | EnableMultisiteStep | ImportWxrStep<Resource> | ImportWordPressFilesStep<Resource> | InstallPluginStep<Resource> | InstallThemeStep<Resource> | LoginStep | MkdirStep | MvStep | RequestStep | RmStep | RmdirStep | RunPHPStep | RunPHPWithOptionsStep | RunWpInstallationWizardStep | RunSqlStep<Resource> | SetSiteOptionsStep | UnzipStep<Resource> | UpdateUserMetaStep | WriteFileStep<Resource> | WPCLIStep;
+export type GenericStep<Resource> = ActivatePluginStep | ActivateThemeStep | CpStep | DefineWpConfigConstsStep | DefineSiteUrlStep | EnableMultisiteStep | ImportWxrStep<Resource> | ImportWordPressFilesStep<Resource> | InstallPluginStep<Resource> | InstallThemeStep<Resource> | LoginStep | MkdirStep | MvStep | ResetDataStep | RequestStep | RmStep | RmdirStep | RunPHPStep | RunPHPWithOptionsStep | RunWpInstallationWizardStep | RunSqlStep<Resource> | SetSiteOptionsStep | UnzipStep<Resource> | UpdateUserMetaStep | WriteFileStep<Resource> | WPCLIStep;
 /**
  * Progress reporting details.
  */