@wp-playground/client 0.5.6 → 0.6.0

package/index.d.ts

@@ -3,17 +3,11 @@
 import * as Comlink from 'comlink';
 import { Remote } from 'comlink';
 
-export interface MonitoredModule {
-	dependencyFilename: string;
-	dependenciesTotalSize: number;
-}
 declare class EmscriptenDownloadMonitor extends EventTarget {
 	#private;
-	constructor(modules?: MonitoredModule[]);
-	getEmscriptenOptions(): {
-		dataFileDownloads: Record<string, any>;
-	};
-	setModules(modules: MonitoredModule[]): void;
+	constructor();
+	expectAssets(assets: Record<string, number>): void;
+	monitorFetch(fetchPromise: Promise<Response>): Promise<Response>;
 }
 /**
  * Options for customizing the progress tracker.
@@ -202,17 +196,29 @@ export declare class PHPResponse implements PHPResponseData {
 	get text(): string;
 }
 /**
- * Represents an event related to the PHP filesystem.
+ * Represents an event related to the PHP request.
  */
 export interface PHPRequestEndEvent {
 	type: "request.end";
 }
+/**
+ * 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;
+export type PHPEvent = PHPRequestEndEvent | PHPRuntimeInitializedEvent | PHPRuntimeBeforeDestroyEvent;
 /**
  * A callback function that handles PHP events.
  */
@@ -348,6 +354,11 @@ export interface RequestHandler {
 	documentRoot: string;
 }
 export interface IsomorphicLocalPHP extends RequestHandler {
+	/**
+	 * Sets the SAPI name exposed by the PHP module.
+	 * @param newName - The new SAPI name.
+	 */
+	setSapiName(newName: string): void;
 	/**
 	 * Defines a constant in the PHP runtime.
 	 * @param key - The name of the constant.
@@ -585,7 +596,7 @@ export interface IsomorphicLocalPHP extends RequestHandler {
 	 *
 	 * @param handler Callback function to spawn a process.
 	 */
-	setSpawnHandler(handler: SpawnHandler): void;
+	setSpawnHandler(handler: SpawnHandler | string): void;
 }
 export type MessageListener = (data: string) => Promise<string | Uint8Array | void> | string | void;
 export interface EventEmitter {
@@ -596,7 +607,7 @@ export type ChildProcess = EventEmitter & {
 	stdout: EventEmitter;
 	stderr: EventEmitter;
 };
-export type SpawnHandler = (command: string) => ChildProcess;
+export type SpawnHandler = (command: string, args: string[]) => ChildProcess;
 export type IsomorphicRemotePHP = Remote<IsomorphicLocalPHP>;
 export type UniversalPHP = IsomorphicLocalPHP | IsomorphicRemotePHP;
 export type HTTPMethod = "GET" | "POST" | "HEAD" | "OPTIONS" | "PATCH" | "PUT" | "DELETE";
@@ -661,6 +672,11 @@ export interface PHPRunOptions {
 	 * The code snippet to eval instead of a php file.
 	 */
 	code?: string;
+	/**
+	 * Whether to throw an error if the PHP process exits with a non-zero code
+	 * or outputs to stderr.
+	 */
+	throwOnError?: boolean;
 }
 /**
  * Output of the PHP.wasm runtime.
@@ -824,7 +840,6 @@ export type EmscriptenOptions = {
 	ENV?: Record<string, string>;
 	locateFile?: (path: string) => string;
 	noInitialRun?: boolean;
-	dataFileDownloads?: Record<string, number>;
 	print?: (message: string) => void;
 	printErr?: (message: string) => void;
 	quit?: (status: number, toThrow: any) => void;
@@ -833,11 +848,30 @@ export type EmscriptenOptions = {
 	onMessage?: (listener: EmscriptenMessageListener) => void;
 } & Record<string, any>;
 export type EmscriptenMessageListener = (type: string, data: string) => void;
+export interface SemaphoreOptions {
+	concurrency: number;
+}
+declare class Semaphore {
+	private _running;
+	private concurrency;
+	private queue;
+	constructor({ concurrency }: SemaphoreOptions);
+	get running(): number;
+	acquire(): Promise<() => void>;
+	run<T>(fn: () => T | Promise<T>): Promise<T>;
+}
+export declare function phpVar(value: unknown): string;
+export declare function phpVars<T extends Record<string, unknown>>(vars: T): Record<keyof T, string>;
 declare const __private__dont__use: unique symbol;
 declare abstract class BasePHP implements IsomorphicLocalPHP {
 	#private;
 	protected [__private__dont__use]: any;
 	requestHandler?: PHPBrowser;
+	/**
+	 * An exclusive lock that prevent multiple requests from running at
+	 * the same time.
+	 */
+	semaphore: Semaphore;
 	/**
 	 * Initializes a PHP runtime.
 	 *
@@ -852,7 +886,7 @@ declare abstract class BasePHP implements IsomorphicLocalPHP {
 	/** @inheritDoc */
 	onMessage(listener: MessageListener): Promise<void>;
 	/** @inheritDoc */
-	setSpawnHandler(handler: SpawnHandler): Promise<void>;
+	setSpawnHandler(handler: SpawnHandler | string): Promise<void>;
 	/** @inheritDoc */
 	get absoluteUrl(): string;
 	/** @inheritDoc */
@@ -863,6 +897,8 @@ declare abstract class BasePHP implements IsomorphicLocalPHP {
 	internalUrlToPath(internalUrl: string): string;
 	initializeRuntime(runtimeId: PHPRuntimeId): void;
 	/** @inheritDoc */
+	setSapiName(newName: string): Promise<void>;
+	/** @inheritDoc */
 	setPhpIniPath(path: string): void;
 	/** @inheritDoc */
 	setPhpIniEntry(key: string, value: string): void;
@@ -873,7 +909,7 @@ declare abstract class BasePHP implements IsomorphicLocalPHP {
 	/** @inheritDoc */
 	run(request: PHPRunOptions): Promise<PHPResponse>;
 	addServerGlobalEntry(key: string, value: string): void;
-	defineConstant(key: string, value: string | number | null): void;
+	defineConstant(key: string, value: string | boolean | number | null): void;
 	/** @inheritDoc */
 	mkdir(path: string): void;
 	/** @inheritDoc */
@@ -896,22 +932,15 @@ declare abstract class BasePHP implements IsomorphicLocalPHP {
 	isDir(path: string): boolean;
 	/** @inheritDoc */
 	fileExists(path: string): boolean;
-	exit(code?: number): any;
-}
-export interface SemaphoreOptions {
-	concurrency: number;
-}
-declare class Semaphore {
-	private _running;
-	private concurrency;
-	private queue;
-	constructor({ concurrency }: SemaphoreOptions);
-	get running(): number;
-	acquire(): Promise<() => void>;
-	run<T>(fn: () => Promise<T>): Promise<T>;
+	/**
+	 * Hot-swaps the PHP runtime for a new one without
+	 * interrupting the operations of this PHP instance.
+	 *
+	 * @param runtime
+	 */
+	hotSwapPHPRuntime(runtime: number): void;
+	exit(code?: number): void;
 }
-export declare function phpVar(value: unknown): string;
-export declare function phpVars<T extends Record<string, unknown>>(vars: T): Record<keyof T, string>;
 export declare const ResourceTypes: readonly [
 	"vfs",
 	"literal",
@@ -1580,7 +1609,7 @@ export interface RunPHPStep {
 /**
  * Runs PHP code.
  */
-export declare const runPHP: StepHandler<RunPHPStep>;
+export declare const runPHP: StepHandler<RunPHPStep, Promise<PHPResponse>>;
 /**
  * @inheritDoc runPHP
  * @hasRunnableExample
@@ -1639,7 +1668,7 @@ export interface RequestStep {
 /**
  * Sends a HTTP request to the Playground.
  */
-export declare const request: StepHandler<RequestStep>;
+export declare const request: StepHandler<RequestStep, Promise<PHPResponse>>;
 /**
  * @inheritDoc writeFile
  * @hasRunnableExample
@@ -1746,15 +1775,23 @@ export declare const activateTheme: StepHandler<ActivateThemeStep>;
  * <code>
  * {
  * 		"step": "unzip",
- * 		"zipPath": "/wordpress/data.zip",
+ * 		"zipFile": {
+ * 			"resource": "vfs",
+ * 			"path": "/wordpress/data.zip"
+ * 		},
  * 		"extractToPath": "/wordpress"
  * }
  * </code>
  */
-export interface UnzipStep {
+export interface UnzipStep<ResourceType> {
 	step: "unzip";
 	/** The zip file to extract */
-	zipPath: string;
+	zipFile?: ResourceType;
+	/**
+	 * The path of the zip file to extract
+	 * @deprecated Use zipFile instead.
+	 */
+	zipPath?: string;
 	/** The path to extract the zip file to */
 	extractToPath: string;
 }
@@ -1765,7 +1802,7 @@ export interface UnzipStep {
  * @param zipPath The zip file to unzip.
  * @param extractTo The directory to extract the zip file to.
  */
-export declare const unzip: StepHandler<UnzipStep>;
+export declare const unzip: StepHandler<UnzipStep<File>>;
 /**
  * @inheritDoc importWordPressFiles
  * @example
@@ -1834,6 +1871,29 @@ export interface ImportFileStep<ResourceType> {
  * @param file The file to import.
  */
 export declare const importFile: StepHandler<ImportFileStep<File>>;
+/**
+ * @inheritDoc enableMultisite
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "enableMultisite",
+ * }
+ * </code>
+ */
+export interface EnableMultisiteStep {
+	step: "enableMultisite";
+}
+/**
+ * Defines constants in a wp-config.php file.
+ *
+ * This step can be called multiple times, and the constants will be merged.
+ *
+ * @param playground The playground client.
+ * @param enableMultisite
+ */
+export declare const enableMultisite: StepHandler<EnableMultisiteStep>;
 /**
  * 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
@@ -1851,7 +1911,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 | ApplyWordPressPatchesStep | CpStep | DefineWpConfigConstsStep | DefineSiteUrlStep | ImportFileStep<Resource> | ImportWordPressFilesStep<Resource> | InstallPluginStep<Resource> | InstallThemeStep<Resource> | LoginStep | MkdirStep | MvStep | RequestStep | RmStep | RmdirStep | RunPHPStep | RunPHPWithOptionsStep | RunWpInstallationWizardStep | RunSqlStep<Resource> | SetPhpIniEntryStep | SetSiteOptionsStep | UnzipStep | UpdateUserMetaStep | WriteFileStep<Resource>;
+export type GenericStep<Resource> = ActivatePluginStep | ActivateThemeStep | ApplyWordPressPatchesStep | CpStep | DefineWpConfigConstsStep | DefineSiteUrlStep | EnableMultisiteStep | ImportFileStep<Resource> | ImportWordPressFilesStep<Resource> | InstallPluginStep<Resource> | InstallThemeStep<Resource> | LoginStep | MkdirStep | MvStep | RequestStep | RmStep | RmdirStep | RunPHPStep | RunPHPWithOptionsStep | RunWpInstallationWizardStep | RunSqlStep<Resource> | SetPhpIniEntryStep | SetSiteOptionsStep | UnzipStep<Resource> | UpdateUserMetaStep | WriteFileStep<Resource>;
 /**
  * Progress reporting details.
  */
@@ -1859,11 +1919,11 @@ export type StepProgress = {
 	tracker: ProgressTracker;
 	initialCaption?: string;
 };
-export type StepHandler<S extends GenericStep<File>> = (
+export type StepHandler<S extends GenericStep<File>, Return = any> = (
 /**
  * A PHP instance or Playground client.
  */
-php: UniversalPHP, args: Omit<S, "step">, progressArgs?: StepProgress) => any;
+php: UniversalPHP, args: Omit<S, "step">, progressArgs?: StepProgress) => Return;
 /**
  * Exports the WordPress database as a WXR file using
  * the core WordPress export tool.
@@ -2039,17 +2099,7 @@ declare class WebPHP extends BasePHP {
 	 * @returns A new PHP instance
 	 */
 	static load(phpVersion: SupportedPHPVersion, options?: PHPWebLoaderOptions): Promise<WebPHP>;
-	/**
-	 * 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
-	 */
-	static loadSync(phpVersion: SupportedPHPVersion, options?: PHPWebLoaderOptions): {
-		php: WebPHP;
-		phpReady: Promise<WebPHP>;
-	};
+	static loadRuntime(phpVersion: SupportedPHPVersion, options?: PHPWebLoaderOptions): Promise<number>;
 }
 declare class WebPHPEndpoint implements IsomorphicLocalPHP {
 	/** @inheritDoc @php-wasm/universal!RequestHandler.absoluteUrl  */
@@ -2075,9 +2125,11 @@ declare class WebPHPEndpoint implements IsomorphicLocalPHP {
 	/** @inheritDoc @php-wasm/web!WebPHP.run */
 	run(request: PHPRunOptions): Promise<PHPResponse>;
 	/** @inheritDoc @php-wasm/web!WebPHP.setSpawnHandler */
-	setSpawnHandler(listener: SpawnHandler): void;
+	setSpawnHandler(listener: string | SpawnHandler): void;
 	/** @inheritDoc @php-wasm/web!WebPHP.chdir */
 	chdir(path: string): void;
+	/** @inheritDoc @php-wasm/web!WebPHP.setSapiName */
+	setSapiName(newName: string): void;
 	/** @inheritDoc @php-wasm/web!WebPHP.setPhpIniPath */
 	setPhpIniPath(path: string): void;
 	/** @inheritDoc @php-wasm/web!WebPHP.setPhpIniEntry */
@@ -2103,7 +2155,7 @@ declare class WebPHPEndpoint implements IsomorphicLocalPHP {
 	/** @inheritDoc @php-wasm/web!WebPHP.onMessage */
 	onMessage(listener: MessageListener): void;
 	/** @inheritDoc @php-wasm/web!WebPHP.defineConstant */
-	defineConstant(key: string, value: string | number | null): void;
+	defineConstant(key: string, value: string | boolean | number | null): void;
 	/** @inheritDoc @php-wasm/web!WebPHP.addEventListener */
 	addEventListener(eventType: PHPEvent["type"], listener: PHPEventListener): void;
 	/** @inheritDoc @php-wasm/web!WebPHP.removeEventListener */
@@ -2194,14 +2246,13 @@ declare class PlaygroundWorkerEndpoint extends WebPHPEndpoint {
 			"6.3": string;
 			"6.2": string;
 			"6.1": string;
-			"6.0": string;
 		};
 		latest: string;
 	}>;
 	resetVirtualOpfs(): Promise<void>;
 	reloadFilesFromOpfs(): Promise<void>;
 	bindOpfs(opfs: FileSystemDirectoryHandle, onProgress?: SyncProgressCallback): Promise<void>;
-	journalFSEvents(root: string, callback: (op: FilesystemOperation) => void): Promise<() => void>;
+	journalFSEvents(root: string, callback: (op: FilesystemOperation) => void): Promise<() => any>;
 	replayFSJournal(events: FilesystemOperation[]): Promise<void>;
 }
 export interface ProgressBarOptions {
@@ -2243,6 +2294,7 @@ export interface WebClientMixin extends ProgressReceiver {
 	 * The onDownloadProgress event listener.
 	 */
 	onDownloadProgress: PlaygroundWorkerEndpoint["onDownloadProgress"];
+	setSpawnHandler: PlaygroundWorkerEndpoint["setSpawnHandler"];
 	journalFSEvents: PlaygroundWorkerEndpoint["journalFSEvents"];
 	replayFSJournal: PlaygroundWorkerEndpoint["replayFSJournal"];
 	addEventListener: PlaygroundWorkerEndpoint["addEventListener"];
@@ -2263,6 +2315,12 @@ export interface StartPlaygroundOptions {
 	disableProgressBar?: boolean;
 	blueprint?: Blueprint;
 	onBlueprintStepCompleted?: OnStepCompleted;
+	/**
+	 * The SAPI name PHP will use.
+	 * @internal
+	 * @private
+	 */
+	sapiName?: string;
 }
 /**
  * Loads playground in iframe and returns a PlaygroundClient instance.
@@ -2271,7 +2329,7 @@ export interface StartPlaygroundOptions {
  * @param options Options for loading the playground.
  * @returns A PlaygroundClient instance.
  */
-export declare function startPlaygroundWeb({ iframe, blueprint, remoteUrl, progressTracker, disableProgressBar, onBlueprintStepCompleted, }: StartPlaygroundOptions): Promise<PlaygroundClient>;
+export declare function startPlaygroundWeb({ iframe, blueprint, remoteUrl, progressTracker, disableProgressBar, onBlueprintStepCompleted, sapiName, }: StartPlaygroundOptions): Promise<PlaygroundClient>;
 /**
  * @deprecated Use `startPlayground` instead.
  *