@wp-playground/client 0.1.60 → 0.2.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"
@@ -504,7 +504,48 @@ export interface IsomorphicLocalPHP extends RequestHandler {
 	 * @param  options - PHP runtime options.
 	 */
 	run(options: PHPRunOptions): Promise<PHPResponse>;
+	/**
+	 * Listens to message sent by the PHP code.
+	 *
+	 * 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.
+	 */
+	onMessage(listener: MessageListener): void;
 }
+export type MessageListener = (data: string) => void;
 export type IsomorphicRemotePHP = Remote<IsomorphicLocalPHP>;
 export type UniversalPHP = IsomorphicLocalPHP | IsomorphicRemotePHP;
 export type HTTPMethod = "GET" | "POST" | "HEAD" | "OPTIONS" | "PATCH" | "PUT" | "DELETE";
@@ -739,7 +780,9 @@ export type EmscriptenOptions = {
 	quit?: (status: number, toThrow: any) => void;
 	onRuntimeInitialized?: () => void;
 	monitorRunDependencies?: (left: number) => void;
+	onMessage?: (listener: EmscriptenMessageListener) => void;
 } & Record<string, any>;
+export type EmscriptenMessageListener = (type: string, data: string) => void;
 declare const __private__dont__use: unique symbol;
 declare abstract class BasePHP implements IsomorphicLocalPHP {
 	#private;
@@ -754,6 +797,8 @@ declare abstract class BasePHP implements IsomorphicLocalPHP {
 	 */
 	constructor(PHPRuntimeId?: PHPRuntimeId, serverOptions?: PHPRequestHandlerConfiguration);
 	/** @inheritDoc */
+	onMessage(listener: MessageListener): Promise<void>;
+	/** @inheritDoc */
 	get absoluteUrl(): string;
 	/** @inheritDoc */
 	get documentRoot(): string;
@@ -1017,34 +1062,54 @@ export declare class SemaphoreResource<T extends Resource> extends DecoratedReso
 	/** @inheritDoc */
 	resolve(): Promise<File>;
 }
+/**
+ * @inheritDoc activatePlugin
+ */
 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;
+	siteUrl?: string;
 	wordpressPath?: string;
-	patchSqlitePlugin?: boolean;
 	addPhpInfo?: boolean;
-	patchSiteUrl?: boolean;
+	patchSecrets?: boolean;
 	disableSiteHealth?: boolean;
 	disableWpNewBlogNotification?: 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
@@ -1059,20 +1124,31 @@ export declare const defineSiteUrl: StepHandler<DefineSiteUrlStep>;
  * @param playground Playground client.
  */
 export declare function zipEntireSite(playground: UniversalPHP): Promise<File>;
+/**
+ * @inheritDoc replaceSite
+ */
 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
+ */
 export interface UnzipStep {
 	step: "unzip";
+	/** The zip file to extract */
 	zipPath: string;
+	/** The path to extract the zip file to */
 	extractToPath: string;
 }
 /**
@@ -1083,8 +1159,12 @@ export interface UnzipStep {
  * @param extractTo The directory to extract the zip file to.
  */
 export declare const unzip: StepHandler<UnzipStep>;
+/**
+ * @inheritDoc importFile
+ */
 export interface ImportFileStep<ResourceType> {
 	step: "importFile";
+	/** The file to import */
 	file: ResourceType;
 }
 /**
@@ -1226,6 +1306,9 @@ export type LoginStep = {
  * just like a user would.
  */
 export declare const login: StepHandler<LoginStep>;
+/**
+ * @private
+ */
 export interface RunWpInstallationWizardStep {
 	step: "runWpInstallationWizard";
 	options: WordPressInstallationOptions;
@@ -1287,7 +1370,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;
 }
 /**
@@ -1336,6 +1421,9 @@ export declare const runPHP: StepHandler<RunPHPStep>;
  */
 export interface RunPHPWithOptionsStep {
 	step: "runPHPWithOptions";
+	/**
+	 * Run options (See /wordpress-playground/api/universal/interface/PHPRunOptions)
+	 */
 	options: PHPRunOptions;
 }
 /**
@@ -1357,7 +1445,9 @@ export declare const runPHPWithOptions: StepHandler<RunPHPWithOptionsStep>;
  */
 export interface SetPhpIniEntryStep {
 	step: "setPhpIniEntry";
+	/** Entry name e.g. "display_errors" */
 	key: string;
+	/** Entry value as a string e.g. "1" */
 	value: string;
 }
 /**
@@ -1386,6 +1476,9 @@ export declare const setPhpIniEntry: StepHandler<SetPhpIniEntryStep>;
  */
 export interface RequestStep {
 	step: "request";
+	/**
+	 * Request details (See /wordpress-playground/api/universal/interface/PHPRequest)
+	 */
 	request: PHPRequest;
 }
 /**
@@ -1408,7 +1501,9 @@ export declare const request: StepHandler<RequestStep>;
  */
 export interface CpStep {
 	step: "cp";
+	/** Source path */
 	fromPath: string;
+	/** Target path */
 	toPath: string;
 }
 /**
@@ -1431,7 +1526,9 @@ export declare const cp: StepHandler<CpStep>;
  */
 export interface MvStep {
 	step: "mv";
+	/** Source path */
 	fromPath: string;
+	/** Target path */
 	toPath: string;
 }
 /**
@@ -1452,6 +1549,7 @@ export declare const mv: StepHandler<MvStep>;
  */
 export interface MkdirStep {
 	step: "mkdir";
+	/** The path of the directory you want to create */
 	path: string;
 }
 /**
@@ -1473,6 +1571,7 @@ export declare const mkdir: StepHandler<MkdirStep>;
  */
 export interface RmStep {
 	step: "rm";
+	/** The path to remove */
 	path: string;
 }
 /**
@@ -1494,6 +1593,7 @@ export declare const rm: StepHandler<RmStep>;
  */
 export interface RmdirStep {
 	step: "rmdir";
+	/** The path to remove */
 	path: string;
 }
 /**
@@ -1516,7 +1616,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;
 }
 /**
@@ -1524,7 +1626,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";
@@ -1539,19 +1653,24 @@ 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
+ */
 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.
@@ -1611,7 +1730,8 @@ declare const supportedWordPressVersions: readonly [
 	"6.2",
 	"6.1",
 	"6.0",
-	"5.9"
+	"5.9",
+	"nightly"
 ];
 export type supportedWordPressVersion = (typeof supportedWordPressVersions)[number];
 export interface CompiledBlueprint {
@@ -1685,7 +1805,6 @@ declare class WebPHP extends BasePHP {
 	static loadSync(phpVersion: SupportedPHPVersion, options?: PHPWebLoaderOptions): {
 		php: WebPHP;
 		phpReady: Promise<WebPHP>;
-		dataModules: Promise<DataModule[]>;
 	};
 }
 declare class WebPHPEndpoint implements IsomorphicLocalPHP {
@@ -1735,7 +1854,16 @@ declare class WebPHPEndpoint implements IsomorphicLocalPHP {
 	isDir(path: string): boolean;
 	/** @inheritDoc @php-wasm/web!WebPHP.fileExists */
 	fileExists(path: string): boolean;
+	/** @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.
@@ -1754,9 +1882,13 @@ 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;
 	}>;
+	resetVirtualOpfs(): Promise<void>;
+	reloadFilesFromOpfs(): Promise<void>;
+	bindOpfs(opfs: FileSystemDirectoryHandle, onProgress?: SyncProgressCallback): Promise<void>;
 }
 export interface ProgressBarOptions {
 	caption?: string;
@@ -1797,6 +1929,9 @@ export interface WebClientMixin extends ProgressReceiver {
 	 * The onDownloadProgress event listener.
 	 */
 	onDownloadProgress: PlaygroundWorkerEndpoint["onDownloadProgress"];
+	/** @inheritDoc @php-wasm/universal!UniversalPHP.onMessage */
+	onMessage: PlaygroundWorkerEndpoint["onMessage"];
+	bindOpfs(opfs: FileSystemDirectoryHandle, onProgress?: SyncProgressCallback): Promise<void>;
 }
 /**
  * The Playground Client interface.