@wp-playground/client 0.3.1 → 0.5.2

package/index.d.ts

@@ -201,6 +201,22 @@ export declare class PHPResponse implements PHPResponseData {
 	 */
 	get text(): string;
 }
+/**
+ * Represents an event related to the PHP filesystem.
+ */
+export interface PHPRequestEndEvent {
+	type: "request.end";
+}
+/**
+ * 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;
+/**
+ * A callback function that handles PHP events.
+ */
+export type PHPEventListener = (event: PHPEvent) => void;
 /**
  * Handles HTTP requests using PHP runtime as a backend.
  *
@@ -332,6 +348,24 @@ export interface RequestHandler {
 	documentRoot: string;
 }
 export interface IsomorphicLocalPHP extends RequestHandler {
+	/**
+	 * 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 | number | null): void;
+	/**
+	 * 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;
 	/**
 	 * Sets the path to the php.ini file to use for the PHP instance.
 	 *
@@ -544,8 +578,25 @@ export interface IsomorphicLocalPHP extends RequestHandler {
 	 * @param listener Callback function to handle the message.
 	 */
 	onMessage(listener: MessageListener): void;
+	/**
+	 * Registers a handler to spawns a child process when
+	 * `proc_open()`, `popen()`, `exec()`, `system()`, or `passthru()`
+	 * is called.
+	 *
+	 * @param handler Callback function to spawn a process.
+	 */
+	setSpawnHandler(handler: SpawnHandler): void;
 }
-export type MessageListener = (data: string) => void;
+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) => ChildProcess;
 export type IsomorphicRemotePHP = Remote<IsomorphicLocalPHP>;
 export type UniversalPHP = IsomorphicLocalPHP | IsomorphicRemotePHP;
 export type HTTPMethod = "GET" | "POST" | "HEAD" | "OPTIONS" | "PATCH" | "PUT" | "DELETE";
@@ -655,6 +706,7 @@ export interface ErrnoError extends Error {
 	message: string;
 }
 export declare const SupportedPHPVersions: readonly [
+	"8.3",
 	"8.2",
 	"8.1",
 	"8.0",
@@ -662,10 +714,9 @@ export declare const SupportedPHPVersions: readonly [
 	"7.3",
 	"7.2",
 	"7.1",
-	"7.0",
-	"5.6"
+	"7.0"
 ];
-export declare const LatestSupportedPHPVersion: "8.2";
+export declare const LatestSupportedPHPVersion: "8.3";
 export declare const SupportedPHPVersionsList: string[];
 export type SupportedPHPVersion = (typeof SupportedPHPVersions)[number];
 export type SupportedPHPExtension = "iconv" | "mbstring" | "xml-bundle" | "gd";
@@ -753,6 +804,8 @@ export declare class PHPBrowser implements RequestHandler {
 	get absoluteUrl(): string;
 	/** @inheritDoc */
 	get documentRoot(): string;
+	setCookies(cookies: string[]): void;
+	serializeCookies(): string;
 }
 export type RuntimeType = "NODE" | "WEB" | "WORKER";
 export type PHPRuntimeId = number;
@@ -793,9 +846,14 @@ declare abstract class BasePHP implements IsomorphicLocalPHP {
 	 * @param  serverOptions - Optional. Options for the PHPRequestHandler. If undefined, no request handler will be initialized.
 	 */
 	constructor(PHPRuntimeId?: PHPRuntimeId, serverOptions?: PHPRequestHandlerConfiguration);
+	addEventListener(eventType: PHPEvent["type"], listener: PHPEventListener): void;
+	removeEventListener(eventType: PHPEvent["type"], listener: PHPEventListener): void;
+	dispatchEvent<Event extends PHPEvent>(event: Event): void;
 	/** @inheritDoc */
 	onMessage(listener: MessageListener): Promise<void>;
 	/** @inheritDoc */
+	setSpawnHandler(handler: SpawnHandler): Promise<void>;
+	/** @inheritDoc */
 	get absoluteUrl(): string;
 	/** @inheritDoc */
 	get documentRoot(): string;
@@ -815,6 +873,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;
 	/** @inheritDoc */
 	mkdir(path: string): void;
 	/** @inheritDoc */
@@ -837,6 +896,7 @@ declare abstract class BasePHP implements IsomorphicLocalPHP {
 	isDir(path: string): boolean;
 	/** @inheritDoc */
 	fileExists(path: string): boolean;
+	exit(code?: number): any;
 }
 export interface SemaphoreOptions {
 	concurrency: number;
@@ -1096,6 +1156,7 @@ export interface ApplyWordPressPatchesStep {
 	disableWpNewBlogNotification?: boolean;
 	makeEditorFrameControlled?: boolean;
 	prepareForRunningInsideWebBrowser?: boolean;
+	addFetchNetworkTransport?: boolean;
 }
 export declare const applyWordPressPatches: StepHandler<ApplyWordPressPatchesStep>;
 /**
@@ -1122,92 +1183,6 @@ export interface DefineSiteUrlStep {
  * @param siteUrl
  */
 export declare const defineSiteUrl: StepHandler<DefineSiteUrlStep>;
-/**
- * Full site export support:
- */
-/**
- * Export the current site as a zip file.
- *
- * @param playground Playground client.
- */
-export declare function zipEntireSite(playground: UniversalPHP): Promise<File>;
-/**
- * @inheritDoc replaceSite
- * @example
- *
- * <code>
- * {
- * 		"step": "replaceSite",
- * 		"fullSiteZip": "https://mysite.com/import.zip"
- * }
- * </code>
- */
-export interface ReplaceSiteStep<ResourceType> {
-	step: "replaceSite";
-	/** The zip file containing the new WordPress site */
-	fullSiteZip: ResourceType;
-}
-/**
- * Replace the current site with a site from the provided zip file.
- * Remember to install the SQLite integration plugin in the zipped site:
- * https://wordpress.org/plugins/sqlite-database-integration.
- *
- * @param playground Playground client.
- * @param fullSiteZip Zipped WordPress site.
- */
-export declare const replaceSite: StepHandler<ReplaceSiteStep<File>>;
-/**
- * @inheritDoc unzip
- * @example
- *
- * <code>
- * {
- * 		"step": "unzip",
- * 		"zipPath": "/wordpress/data.zip",
- * 		"extractToPath": "/wordpress"
- * }
- * </code>
- */
-export interface UnzipStep {
-	step: "unzip";
-	/** The zip file to extract */
-	zipPath: string;
-	/** The path to extract the zip file to */
-	extractToPath: string;
-}
-/**
- * Unzip a zip file.
- *
- * @param playground Playground client.
- * @param zipPath The zip file to unzip.
- * @param extractTo The directory to extract the zip file to.
- */
-export declare const unzip: StepHandler<UnzipStep>;
-/**
- * @inheritDoc importFile
- * @example
- *
- * <code>
- * {
- * 		"step": "importFile",
- * 		"file": "https://mysite.com/import.WXR"
- * }
- * </code>
- */
-export interface ImportFileStep<ResourceType> {
-	step: "importFile";
-	/** The file to import */
-	file: ResourceType;
-}
-/**
- * Uploads a file to the WordPress importer and returns the response.
- * Supports both WXR and WXZ files.
- *
- * @see https://github.com/WordPress/wordpress-importer/compare/master...akirk:wordpress-importer:import-wxz.patch
- * @param playground Playground client.
- * @param file The file to import.
- */
-export declare const importFile: StepHandler<ImportFileStep<File>>;
 /**
  * @inheritDoc installPlugin
  * @hasRunnableExample
@@ -1481,6 +1456,40 @@ export interface RmdirStep {
  * Removes a directory at the specified path.
  */
 export declare const rmdir: StepHandler<RmdirStep>;
+/**
+ * @inheritDoc runSql
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ *		"step": "runSql",
+ *		"sql": {
+ *			"resource": "literal",
+ *			"name": "schema.sql",
+ *			"contents": "DELETE FROM wp_posts"
+ *		}
+ * }
+ * </code>
+ */
+export interface RunSqlStep<ResourceType> {
+	/**
+	 * The step identifier.
+	 */
+	step: "runSql";
+	/**
+	 * The SQL to run. Each non-empty line must contain a valid SQL query.
+	 */
+	sql: ResourceType;
+}
+/**
+ * Run one or more SQL queries.
+ *
+ * This step will treat each non-empty line in the input SQL as a query and
+ * try to execute it using `$wpdb`. Queries spanning multiple lines are not
+ * yet supported.
+ */
+export declare const runSql: StepHandler<RunSqlStep<File>>;
 /**
  * @inheritDoc mkdir
  * @hasRunnableExample
@@ -1667,8 +1676,7 @@ export declare const writeFile: StepHandler<WriteFileStep<File>>;
  * 		"step": "defineWpConfigConsts",
  * 		"consts": {
  *          "WP_DEBUG": true
- *      },
- *      "virtualize": true
+ *      }
  * }
  * </code>
  */
@@ -1677,15 +1685,16 @@ export interface DefineWpConfigConstsStep {
 	/** The constants to define */
 	consts: Record<string, unknown>;
 	/**
-	 * Enables the virtualization of wp-config.php and playground-consts.json files, leaving the local system files untouched.
-	 * The variables defined in the /vfs-blueprints/playground-consts.json file are loaded via the auto_prepend_file directive in the php.ini file.
-	 * @default false
-	 * @see https://www.php.net/manual/en/ini.core.php#ini.auto-prepend-file
+	 * @deprecated This option is noop and will be removed in a future version.
+	 * This option is only kept in here to avoid breaking Blueprint schema validation
+	 * for existing apps using this option.
 	 */
 	virtualize?: boolean;
 }
 /**
- * Defines the wp-config.php constants
+ * Defines constants to be used in wp-config.php file.
+ *
+ * This step can be called multiple times, and the constants will be merged.
  *
  * @param playground The playground client.
  * @param wpConfigConst
@@ -1717,6 +1726,107 @@ export interface ActivateThemeStep {
  * @param themeFolderName The theme folder name.
  */
 export declare const activateTheme: StepHandler<ActivateThemeStep>;
+/**
+ * @inheritDoc unzip
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "unzip",
+ * 		"zipPath": "/wordpress/data.zip",
+ * 		"extractToPath": "/wordpress"
+ * }
+ * </code>
+ */
+export interface UnzipStep {
+	step: "unzip";
+	/** The zip file to extract */
+	zipPath: string;
+	/** The path to extract the zip file to */
+	extractToPath: string;
+}
+/**
+ * Unzip a zip file.
+ *
+ * @param playground Playground client.
+ * @param zipPath The zip file to unzip.
+ * @param extractTo The directory to extract the zip file to.
+ */
+export declare const unzip: StepHandler<UnzipStep>;
+/**
+ * @inheritDoc importWordPressFiles
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "importWordPressFilesStep",
+ * 		"wordPressFilesZip": {
+ * 		"resource": "fetch",
+ * 		"url": "https://mysite.com/import.zip"
+ *      }
+ * }
+ * </code>
+ */
+export interface ImportWordPressFilesStep<ResourceType> {
+	step: "importWordPressFiles";
+	/**
+	 * The zip file containing the top-level WordPress files and
+	 * directories.
+	 */
+	wordPressFilesZip: ResourceType;
+	/**
+	 * The path inside the zip file where the WordPress files are.
+	 */
+	pathInZip?: string;
+}
+/**
+ * Imports top-level WordPress files from a given zip file into
+ * 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.
+ *
+ * Any files that Playground recognizes as "excluded from the export"
+ * will carry over from the existing document root into the imported
+ * directories. For example, the sqlite-database-integration plugin.
+ *
+ * @param playground Playground client.
+ * @param wordPressFilesZip Zipped WordPress site.
+ */
+export declare const importWordPressFiles: StepHandler<ImportWordPressFilesStep<File>>;
+/**
+ * @inheritDoc importFile
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "importFile",
+ * 		"file": {
+ * 			"resource": "url",
+ * 			"url": "https://your-site.com/starter-content.wxz"
+ * 		}
+ * }
+ * </code>
+ */
+export interface ImportFileStep<ResourceType> {
+	step: "importFile";
+	/** The file to import */
+	file: ResourceType;
+}
+/**
+ * Uploads a file to the WordPress importer and returns the response.
+ * Supports both WXR and WXZ files.
+ *
+ * @see https://github.com/WordPress/wordpress-importer/compare/master...akirk:wordpress-importer:import-wxz.patch
+ * @param playground Playground client.
+ * @param file The file to import.
+ */
+export declare const importFile: StepHandler<ImportFileStep<File>>;
+/**
+ * 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
+ * by WordPressPatcher.
+ */
+export declare const wpContentFilesExcludedFromExport: string[];
 export type Step = GenericStep<FileReference>;
 export type StepDefinition = Step & {
 	progress?: {
@@ -1728,7 +1838,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> | InstallPluginStep<Resource> | InstallThemeStep<Resource> | LoginStep | MkdirStep | MvStep | RequestStep | ReplaceSiteStep<Resource> | RmStep | RmdirStep | RunPHPStep | RunPHPWithOptionsStep | RunWpInstallationWizardStep | SetPhpIniEntryStep | SetSiteOptionsStep | UnzipStep | UpdateUserMetaStep | WriteFileStep<Resource>;
+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>;
 /**
  * Progress reporting details.
  */
@@ -1741,11 +1851,48 @@ export type StepHandler<S extends GenericStep<File>> = (
  * A PHP instance or Playground client.
  */
 php: UniversalPHP, args: Omit<S, "step">, progressArgs?: StepProgress) => any;
+/**
+ * Exports the WordPress database as a WXR file using
+ * the core WordPress export tool.
+ *
+ * @param playground Playground client
+ * @returns WXR file
+ */
+export declare function exportWXR(playground: UniversalPHP): Promise<File>;
+/**
+ * Exports the WordPress database as a WXZ file using
+ * the export-wxz plugin from https://github.com/akirk/export-wxz.
+ *
+ * @param playground Playground client
+ * @returns WXZ file
+ */
+export declare function exportWXZ(playground: UniversalPHP): Promise<File>;
+export interface ZipWpContentOptions {
+	/**
+	 * @private
+	 * A temporary workaround to enable including the WordPress default theme
+	 * in the exported zip file.
+	 */
+	selfContained?: boolean;
+}
+/**
+ * Replace the current wp-content directory with one from the provided zip file.
+ *
+ * @param playground Playground client.
+ * @param wpContentZip Zipped WordPress site.
+ */
+export declare const zipWpContent: (playground: UniversalPHP, { selfContained }?: ZipWpContentOptions) => Promise<Uint8Array>;
 export interface Blueprint {
 	/**
 	 * The URL to navigate to after the blueprint has been run.
 	 */
 	landingPage?: string;
+	/**
+	 * Optional description. It doesn't do anything but is exposed as
+	 * a courtesy to developers who may want to document which blueprint
+	 * file does what.
+	 */
+	description?: string;
 	/**
 	 * The preferred PHP and WordPress versions to use.
 	 */
@@ -1761,12 +1908,46 @@ export interface Blueprint {
 		 */
 		wp: string | "latest";
 	};
+	features?: {
+		/** Should boot with support for network request via wp_safe_remote_get? */
+		networking?: boolean;
+	};
+	/**
+	 * PHP Constants to define on every request
+	 * @deprecated This experimental option will change without warning.
+	 *             Use `steps` instead.
+	 */
+	constants?: Record<string, string>;
+	/**
+	 * WordPress plugins to install and activate
+	 * @deprecated This experimental option will change without warning.
+	 *             Use `steps` instead.
+	 */
+	plugins?: Array<string | FileReference>;
+	/**
+	 * WordPress site options to define
+	 * @deprecated This experimental option will change without warning.
+	 *             Use `steps` instead.
+	 */
+	siteOptions?: Record<string, string> & {
+		/** The site title */
+		blogname?: string;
+	};
+	/**
+	 * User to log in as.
+	 * If true, logs the user in as admin/password.
+	 */
+	login?: boolean | {
+		username: string;
+		password: string;
+	};
 	/**
 	 * The PHP extensions to use.
 	 */
 	phpExtensionBundles?: SupportedPHPExtensionBundle[];
 	/**
-	 * The steps to run.
+	 * The steps to run after every other operation in this Blueprint was
+	 * executed.
 	 */
 	steps?: Array<StepDefinition | string | undefined | false | null>;
 }
@@ -1779,6 +1960,10 @@ export interface CompiledBlueprint {
 	};
 	/** The requested PHP extensions to load */
 	phpExtensions: SupportedPHPExtension[];
+	features: {
+		/** Should boot with support for network request via wp_safe_remote_get? */
+		networking: boolean;
+	};
 	/** The compiled steps for the blueprint */
 	run: (playground: UniversalPHP) => Promise<void>;
 }
@@ -1876,6 +2061,8 @@ declare class WebPHPEndpoint implements IsomorphicLocalPHP {
 	request(request: PHPRequest, redirects?: number): Promise<PHPResponse>;
 	/** @inheritDoc @php-wasm/web!WebPHP.run */
 	run(request: PHPRunOptions): Promise<PHPResponse>;
+	/** @inheritDoc @php-wasm/web!WebPHP.setSpawnHandler */
+	setSpawnHandler(listener: SpawnHandler): void;
 	/** @inheritDoc @php-wasm/web!WebPHP.chdir */
 	chdir(path: string): void;
 	/** @inheritDoc @php-wasm/web!WebPHP.setPhpIniPath */
@@ -1902,7 +2089,62 @@ declare class WebPHPEndpoint implements IsomorphicLocalPHP {
 	fileExists(path: string): boolean;
 	/** @inheritDoc @php-wasm/web!WebPHP.onMessage */
 	onMessage(listener: MessageListener): void;
+	/** @inheritDoc @php-wasm/web!WebPHP.defineConstant */
+	defineConstant(key: string, value: string | number | null): void;
+	/** @inheritDoc @php-wasm/web!WebPHP.addEventListener */
+	addEventListener(eventType: PHPEvent["type"], listener: PHPEventListener): void;
+	/** @inheritDoc @php-wasm/web!WebPHP.removeEventListener */
+	removeEventListener(eventType: PHPEvent["type"], listener: PHPEventListener): void;
 }
+/**
+ * Represents the type of node in PHP file system.
+ */
+export type FSNodeType = "file" | "directory";
+/**
+ * Represents an update operation on a file system node.
+ */
+export type UpdateFileOperation = {
+	/** The type of operation being performed. */
+	operation: "WRITE";
+	/** The path of the node being updated. */
+	path: string;
+	/** Optional. The new contents of the file. */
+	data?: Uint8Array;
+	nodeType: "file";
+};
+/**
+ * Represents a directory operation.
+ */
+export type CreateOperation = {
+	/** The type of operation being performed. */
+	operation: "CREATE";
+	/** The path of the node being created. */
+	path: string;
+	/** The type of the node being created. */
+	nodeType: FSNodeType;
+};
+export type DeleteOperation = {
+	/** The type of operation being performed. */
+	operation: "DELETE";
+	/** The path of the node being updated. */
+	path: string;
+	/** The type of the node being updated. */
+	nodeType: FSNodeType;
+};
+/**
+ * Represents a rename operation on a file or directory in PHP file system.
+ */
+export type RenameOperation = {
+	/** The type of operation being performed. */
+	operation: "RENAME";
+	/** The original path of the file or directory being renamed. */
+	path: string;
+	/** The new path of the file or directory after the rename operation. */
+	toPath: string;
+	/** The type of node being renamed (file or directory). */
+	nodeType: FSNodeType;
+};
+export type FilesystemOperation = CreateOperation | UpdateFileOperation | DeleteOperation | RenameOperation;
 export type SyncProgress = {
 	/** The number of files that have been synced. */
 	files: number;
@@ -1935,6 +2177,7 @@ declare class PlaygroundWorkerEndpoint extends WebPHPEndpoint {
 		all: {
 			nightly: string;
 			beta: string;
+			"6.4": string;
 			"6.3": string;
 			"6.2": string;
 			"6.1": string;
@@ -1945,6 +2188,8 @@ declare class PlaygroundWorkerEndpoint extends WebPHPEndpoint {
 	resetVirtualOpfs(): Promise<void>;
 	reloadFilesFromOpfs(): Promise<void>;
 	bindOpfs(opfs: FileSystemDirectoryHandle, onProgress?: SyncProgressCallback): Promise<void>;
+	journalFSEvents(root: string, callback: (op: FilesystemOperation) => void): Promise<() => void>;
+	replayFSJournal(events: FilesystemOperation[]): Promise<void>;
 }
 export interface ProgressBarOptions {
 	caption?: string;
@@ -1985,6 +2230,10 @@ export interface WebClientMixin extends ProgressReceiver {
 	 * The onDownloadProgress event listener.
 	 */
 	onDownloadProgress: PlaygroundWorkerEndpoint["onDownloadProgress"];
+	journalFSEvents: PlaygroundWorkerEndpoint["journalFSEvents"];
+	replayFSJournal: PlaygroundWorkerEndpoint["replayFSJournal"];
+	addEventListener: PlaygroundWorkerEndpoint["addEventListener"];
+	removeEventListener: PlaygroundWorkerEndpoint["removeEventListener"];
 	/** @inheritDoc @php-wasm/universal!UniversalPHP.onMessage */
 	onMessage: PlaygroundWorkerEndpoint["onMessage"];
 	bindOpfs(opfs: FileSystemDirectoryHandle, onProgress?: SyncProgressCallback): Promise<void>;