@wp-playground/client 0.1.61 → 0.3.0

package/index.d.ts

@@ -274,7 +274,7 @@ export interface RequestHandler {
 	 * 	}
 	 * })
 	 * php.writeFile("/www/index.php", `<?php echo file_get_contents("php://input");`);
-	 * const result = await php.run({
+	 * const result = await php.request({
 	 * 	method: "GET",
 	 * 	headers: {
 	 * 		"Content-Type": "text/plain"
@@ -512,7 +512,7 @@ export interface IsomorphicLocalPHP extends RequestHandler {
 	 *     post_message_to_js(string $data)
 	 *
 	 *     Arguments:
-	 *         $data – any extra information as a string
+	 *         $data (string) – Data to pass to JavaScript.
 	 *
 	 * @example
 	 *
@@ -668,6 +668,8 @@ export declare const SupportedPHPVersions: readonly [
 export declare const LatestSupportedPHPVersion: "8.2";
 export declare const SupportedPHPVersionsList: string[];
 export type SupportedPHPVersion = (typeof SupportedPHPVersions)[number];
+export type SupportedPHPExtension = "iconv" | "mbstring" | "xml-bundle" | "gd";
+export type SupportedPHPExtensionBundle = "kitchen-sink";
 export interface PHPRequestHandlerConfiguration {
 	/**
 	 * The directory in the PHP filesystem where the server will look
@@ -678,11 +680,6 @@ export interface PHPRequestHandlerConfiguration {
 	 * Request Handler URL. Used to populate $_SERVER details like HTTP_HOST.
 	 */
 	absoluteUrl?: string;
-	/**
-	 * Callback used by the PHPRequestHandler to decide whether
-	 * the requested path refers to a PHP file or a static file.
-	 */
-	isStaticFilePath?: (path: string) => boolean;
 }
 /** @inheritDoc */
 export declare class PHPRequestHandler implements RequestHandler {
@@ -1062,17 +1059,34 @@ export declare class SemaphoreResource<T extends Resource> extends DecoratedReso
 	/** @inheritDoc */
 	resolve(): Promise<File>;
 }
+/**
+ * @inheritDoc activatePlugin
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "activatePlugin",
+ * 		"pluginName": "Gutenberg",
+ * 		"pluginPath": "/wordpress/wp-content/plugins/gutenberg"
+ * }
+ * </code>
+ */
 export interface ActivatePluginStep {
 	step: "activatePlugin";
+	/** Path to the plugin directory as absolute path (/wordpress/wp-content/plugins/plugin-name); or the plugin entry file relative to the plugins directory (plugin-name/plugin-name.php). */
 	pluginPath: string;
+	/** Optional. Plugin name to display in the progress bar. */
 	pluginName?: string;
 }
 /**
- * Activates a WordPress plugin in the Playground.
+ * Activates a WordPress plugin (if it's installed).
  *
  * @param playground The playground client.
  */
 export declare const activatePlugin: StepHandler<ActivatePluginStep>;
+/**
+ * @private
+ */
 export interface ApplyWordPressPatchesStep {
 	step: "applyWordPressPatches";
 	siteUrl?: string;
@@ -1081,14 +1095,29 @@ export interface ApplyWordPressPatchesStep {
 	patchSecrets?: boolean;
 	disableSiteHealth?: boolean;
 	disableWpNewBlogNotification?: boolean;
+	makeEditorFrameControlled?: boolean;
+	prepareForRunningInsideWebBrowser?: boolean;
 }
 export declare const applyWordPressPatches: StepHandler<ApplyWordPressPatchesStep>;
+/**
+ * @inheritDoc defineSiteUrl
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "defineSiteUrl",
+ * 		"siteUrl": "https://playground.wordpress.net"
+ * }
+ * </code>
+ */
 export interface DefineSiteUrlStep {
 	step: "defineSiteUrl";
+	/** The URL */
 	siteUrl: string;
 }
 /**
- * Sets site URL of the WordPress installation.
+ * Sets WP_HOME and WP_SITEURL constants for the WordPress installation.
  *
  * @param playground The playground client.
  * @param siteUrl
@@ -1103,20 +1132,48 @@ export declare const defineSiteUrl: StepHandler<DefineSiteUrlStep>;
  * @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 the contents of a full site zip file.
+ * 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;
 }
 /**
@@ -1127,8 +1184,20 @@ export interface UnzipStep {
  * @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;
 }
 /**
@@ -1270,6 +1339,9 @@ export type LoginStep = {
  * just like a user would.
  */
 export declare const login: StepHandler<LoginStep>;
+/**
+ * @private
+ */
 export interface RunWpInstallationWizardStep {
 	step: "runWpInstallationWizard";
 	options: WordPressInstallationOptions;
@@ -1331,7 +1403,9 @@ export declare const setSiteOptions: StepHandler<SetSiteOptionsStep>;
  */
 export interface UpdateUserMetaStep {
 	step: "updateUserMeta";
+	/** An object of user meta values to set, e.g. { "first_name": "John" } */
 	meta: Record<string, unknown>;
+	/** User ID */
 	userId: number;
 }
 /**
@@ -1340,210 +1414,225 @@ export interface UpdateUserMetaStep {
  */
 export declare const updateUserMeta: StepHandler<UpdateUserMetaStep>;
 /**
- * @inheritDoc runPHP
+ * @inheritDoc rm
  * @hasRunnableExample
+ * @landingPage /index.php
  * @example
  *
  * <code>
  * {
- * 		"step": "runPHP",
- * 		"code": "<?php echo 'Hello World'; ?>"
+ * 		"step": "rm",
+ * 		"path": "/wordpress/index.php"
  * }
  * </code>
  */
-export interface RunPHPStep {
-	/** The step identifier. */
-	step: "runPHP";
-	/** The PHP code to run. */
-	code: string;
+export interface RmStep {
+	step: "rm";
+	/** The path to remove */
+	path: string;
 }
 /**
- * Runs PHP code.
+ * Removes a file at the specified path.
  */
-export declare const runPHP: StepHandler<RunPHPStep>;
+export declare const rm: StepHandler<RmStep>;
 /**
- * @inheritDoc runPHP
+ * @inheritDoc cp
  * @hasRunnableExample
+ * @landingPage /index2.php
  * @example
  *
  * <code>
  * {
- * 		"step": "runPHP",
- * 		"options": {
- * 			"code": "<?php echo $_SERVER['CONTENT_TYPE']; ?>",
- * 			"headers": {
- * 				"Content-type": "text/plain"
- * 			}
- * 		}
+ * 		"step": "cp",
+ * 		"fromPath": "/wordpress/index.php",
+ * 		"toPath": "/wordpress/index2.php"
  * }
  * </code>
  */
-export interface RunPHPWithOptionsStep {
-	step: "runPHPWithOptions";
-	options: PHPRunOptions;
+export interface CpStep {
+	step: "cp";
+	/** Source path */
+	fromPath: string;
+	/** Target path */
+	toPath: string;
 }
 /**
- * Runs PHP code with the given options.
+ * Copies a file from one path to another.
  */
-export declare const runPHPWithOptions: StepHandler<RunPHPWithOptionsStep>;
+export declare const cp: StepHandler<CpStep>;
 /**
- * @inheritDoc setPhpIniEntry
+ * @inheritDoc rmdir
  * @hasRunnableExample
+ * @landingPage /wp-admin/
  * @example
  *
  * <code>
  * {
- * 		"step": "setPhpIniEntry",
- * 		"key": "display_errors",
- * 		"value": "1"
+ * 		"step": "rmdir",
+ * 		"path": "/wordpress/wp-admin"
  * }
  * </code>
  */
-export interface SetPhpIniEntryStep {
-	step: "setPhpIniEntry";
-	key: string;
-	value: string;
+export interface RmdirStep {
+	step: "rmdir";
+	/** The path to remove */
+	path: string;
 }
 /**
- * Sets a PHP ini entry.
+ * Removes a directory at the specified path.
  */
-export declare const setPhpIniEntry: StepHandler<SetPhpIniEntryStep>;
+export declare const rmdir: StepHandler<RmdirStep>;
 /**
- * @inheritDoc request
- * @needsLogin
+ * @inheritDoc mkdir
  * @hasRunnableExample
  * @example
  *
  * <code>
  * {
- * 		"step": "request",
- * 		"request": {
- * 			"method": "POST",
- * 			"url": "/wp-admin/admin-ajax.php",
- * 			"formData": {
- * 				"action": "my_action",
- * 				"foo": "bar"
- * 			}
- * 		}
+ * 		"step": "mkdir",
+ * 		"path": "/wordpress/my-new-folder"
  * }
  * </code>
  */
-export interface RequestStep {
-	step: "request";
-	request: PHPRequest;
+export interface MkdirStep {
+	step: "mkdir";
+	/** The path of the directory you want to create */
+	path: string;
 }
 /**
- * Sends a HTTP request to the Playground.
+ * Creates a directory at the specified path.
  */
-export declare const request: StepHandler<RequestStep>;
+export declare const mkdir: StepHandler<MkdirStep>;
 /**
- * @inheritDoc cp
+ * @inheritDoc mv
  * @hasRunnableExample
  * @landingPage /index2.php
  * @example
  *
  * <code>
  * {
- * 		"step": "cp",
+ * 		"step": "mv",
  * 		"fromPath": "/wordpress/index.php",
  * 		"toPath": "/wordpress/index2.php"
  * }
  * </code>
  */
-export interface CpStep {
-	step: "cp";
+export interface MvStep {
+	step: "mv";
+	/** Source path */
 	fromPath: string;
+	/** Target path */
 	toPath: string;
 }
 /**
- * Copies a file from one path to another.
+ * Moves a file or directory from one path to another.
  */
-export declare const cp: StepHandler<CpStep>;
+export declare const mv: StepHandler<MvStep>;
 /**
- * @inheritDoc mv
+ * @inheritDoc setPhpIniEntry
  * @hasRunnableExample
- * @landingPage /index2.php
  * @example
  *
  * <code>
  * {
- * 		"step": "mv",
- * 		"fromPath": "/wordpress/index.php",
- * 		"toPath": "/wordpress/index2.php"
+ * 		"step": "setPhpIniEntry",
+ * 		"key": "display_errors",
+ * 		"value": "1"
  * }
  * </code>
  */
-export interface MvStep {
-	step: "mv";
-	fromPath: string;
-	toPath: string;
+export interface SetPhpIniEntryStep {
+	step: "setPhpIniEntry";
+	/** Entry name e.g. "display_errors" */
+	key: string;
+	/** Entry value as a string e.g. "1" */
+	value: string;
 }
 /**
- * Moves a file or directory from one path to another.
+ * Sets a PHP ini entry.
  */
-export declare const mv: StepHandler<MvStep>;
+export declare const setPhpIniEntry: StepHandler<SetPhpIniEntryStep>;
 /**
- * @inheritDoc mkdir
+ * @inheritDoc runPHP
  * @hasRunnableExample
  * @example
  *
  * <code>
  * {
- * 		"step": "mkdir",
- * 		"path": "/wordpress/my-new-folder"
+ * 		"step": "runPHP",
+ * 		"code": "<?php require_once 'wordpress/wp-load.php'; wp_insert_post(array('post_title' => 'wp-load.php required for WP functionality', 'post_status' => 'publish')); ?>"
  * }
  * </code>
  */
-export interface MkdirStep {
-	step: "mkdir";
-	path: string;
+export interface RunPHPStep {
+	/** The step identifier. */
+	step: "runPHP";
+	/** The PHP code to run. */
+	code: string;
 }
 /**
- * Creates a directory at the specified path.
+ * Runs PHP code.
  */
-export declare const mkdir: StepHandler<MkdirStep>;
+export declare const runPHP: StepHandler<RunPHPStep>;
 /**
- * @inheritDoc rm
+ * @inheritDoc runPHP
  * @hasRunnableExample
- * @landingPage /index.php
  * @example
  *
  * <code>
  * {
- * 		"step": "rm",
- * 		"path": "/wordpress/index.php"
+ * 		"step": "runPHP",
+ * 		"options": {
+ * 			"code": "<?php echo $_SERVER['CONTENT_TYPE']; ?>",
+ * 			"headers": {
+ * 				"Content-type": "text/plain"
+ * 			}
+ * 		}
  * }
  * </code>
  */
-export interface RmStep {
-	step: "rm";
-	path: string;
+export interface RunPHPWithOptionsStep {
+	step: "runPHPWithOptions";
+	/**
+	 * Run options (See /wordpress-playground/api/universal/interface/PHPRunOptions)
+	 */
+	options: PHPRunOptions;
 }
 /**
- * Removes a file at the specified path.
+ * Runs PHP code with the given options.
  */
-export declare const rm: StepHandler<RmStep>;
+export declare const runPHPWithOptions: StepHandler<RunPHPWithOptionsStep>;
 /**
- * @inheritDoc rmdir
+ * @inheritDoc request
+ * @needsLogin
  * @hasRunnableExample
- * @landingPage /wp-admin/
  * @example
  *
  * <code>
  * {
- * 		"step": "rm",
- * 		"path": "/wordpress/wp-admin"
+ * 		"step": "request",
+ * 		"request": {
+ * 			"method": "POST",
+ * 			"url": "/wp-admin/admin-ajax.php",
+ * 			"formData": {
+ * 				"action": "my_action",
+ * 				"foo": "bar"
+ * 			}
+ * 		}
  * }
  * </code>
  */
-export interface RmdirStep {
-	step: "rmdir";
-	path: string;
+export interface RequestStep {
+	step: "request";
+	/**
+	 * Request details (See /wordpress-playground/api/universal/interface/PHPRequest)
+	 */
+	request: PHPRequest;
 }
 /**
- * Removes a directory at the specified path.
+ * Sends a HTTP request to the Playground.
  */
-export declare const rmdir: StepHandler<RmdirStep>;
+export declare const request: StepHandler<RequestStep>;
 /**
  * @inheritDoc writeFile
  * @hasRunnableExample
@@ -1560,7 +1649,9 @@ export declare const rmdir: StepHandler<RmdirStep>;
  */
 export interface WriteFileStep<ResourceType> {
 	step: "writeFile";
+	/** The path of the file to write to */
 	path: string;
+	/** The data to write */
 	data: ResourceType | string | Uint8Array;
 }
 /**
@@ -1568,7 +1659,19 @@ export interface WriteFileStep<ResourceType> {
  */
 export declare const writeFile: StepHandler<WriteFileStep<File>>;
 /**
- * The step object for defining constants in the wp-config.php file of a WordPress installation.
+ * @inheritDoc defineWpConfigConsts
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "defineWpConfigConsts",
+ * 		"consts": {
+ *          "WP_DEBUG": true
+ *      },
+ *      "virtualize": true
+ * }
+ * </code>
  */
 export interface DefineWpConfigConstsStep {
 	step: "defineWpConfigConsts";
@@ -1583,19 +1686,33 @@ export interface DefineWpConfigConstsStep {
 	virtualize?: boolean;
 }
 /**
- * Sets site URL of the WordPress installation.
+ * Defines the wp-config.php constants
  *
  * @param playground The playground client.
- * @param wpConfigConst An object containing the constants to be defined and the optional virtual file system configuration file path.
- * @returns Returns the virtual file system configuration file path.
+ * @param wpConfigConst
  */
 export declare const defineWpConfigConsts: StepHandler<DefineWpConfigConstsStep>;
+/**
+ * @inheritDoc activateTheme
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "activateTheme",
+ * 		"pluginName": "Storefront",
+ * 		"pluginPath": "/wordpress/wp-content/themes/storefront"
+ * }
+ * </code>
+ */
 export interface ActivateThemeStep {
 	step: "activateTheme";
+	/**
+	 * The name of the theme folder inside wp-content/themes/
+	 */
 	themeFolderName: string;
 }
 /**
- * Activates a WordPress theme in the Playground.
+ * Activates a WordPress theme (if it's installed).
  *
  * @param playground The playground client.
  * @param themeFolderName The theme folder name.
@@ -1645,25 +1762,24 @@ export interface Blueprint {
 		 */
 		wp: string | "latest";
 	};
+	/**
+	 * The PHP extensions to use.
+	 */
+	phpExtensionBundles?: SupportedPHPExtensionBundle[];
 	/**
 	 * The steps to run.
 	 */
 	steps?: Array<StepDefinition | string | undefined | false | null>;
 }
 export type CompiledStep = (php: UniversalPHP) => Promise<void> | void;
-declare const supportedWordPressVersions: readonly [
-	"6.2",
-	"6.1",
-	"6.0",
-	"5.9"
-];
-export type supportedWordPressVersion = (typeof supportedWordPressVersions)[number];
 export interface CompiledBlueprint {
 	/** The requested versions of PHP and WordPress for the blueprint */
 	versions: {
 		php: SupportedPHPVersion;
-		wp: supportedWordPressVersion;
+		wp: string;
 	};
+	/** The requested PHP extensions to load */
+	phpExtensions: SupportedPHPExtension[];
 	/** The compiled steps for the blueprint */
 	run: (playground: UniversalPHP) => Promise<void>;
 }
@@ -1704,6 +1820,8 @@ export interface PHPWebLoaderOptions {
 	downloadMonitor?: EmscriptenDownloadMonitor;
 	requestHandler?: PHPRequestHandlerConfiguration;
 	dataModules?: Array<DataModule | Promise<DataModule>>;
+	/** @deprecated To be replaced with `extensions` in the future */
+	loadAllExtensions?: boolean;
 }
 declare class WebPHP extends BasePHP {
 	/**
@@ -1781,6 +1899,13 @@ declare class WebPHPEndpoint implements IsomorphicLocalPHP {
 	/** @inheritDoc @php-wasm/web!WebPHP.onMessage */
 	onMessage(listener: MessageListener): void;
 }
+export type SyncProgress = {
+	/** The number of files that have been synced. */
+	files: number;
+	/** The number of all files that need to be synced. */
+	total: number;
+};
+export type SyncProgressCallback = (progress: SyncProgress) => void;
 declare class PlaygroundWorkerEndpoint extends WebPHPEndpoint {
 	/**
 	 * A string representing the scope of the Playground instance.
@@ -1799,10 +1924,23 @@ declare class PlaygroundWorkerEndpoint extends WebPHPEndpoint {
 	 * @returns WordPress module details, including the static assets directory and default theme.
 	 */
 	getWordPressModuleDetails(): Promise<{
+		majorVersion: string;
 		staticAssetsDirectory: string;
-		defaultTheme: any;
 	}>;
-	resetOpfs(): Promise<void>;
+	getSupportedWordPressVersions(): Promise<{
+		all: {
+			nightly: string;
+			beta: string;
+			"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>;
 }
 export interface ProgressBarOptions {
 	caption?: string;
@@ -1845,6 +1983,7 @@ export interface WebClientMixin extends ProgressReceiver {
 	onDownloadProgress: PlaygroundWorkerEndpoint["onDownloadProgress"];
 	/** @inheritDoc @php-wasm/universal!UniversalPHP.onMessage */
 	onMessage: PlaygroundWorkerEndpoint["onMessage"];
+	bindOpfs(opfs: FileSystemDirectoryHandle, onProgress?: SyncProgressCallback): Promise<void>;
 }
 /**
  * The Playground Client interface.