@wp-playground/client 0.1.61 → 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"
@@ -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
 	 *
@@ -1062,17 +1062,25 @@ 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;
@@ -1083,12 +1091,25 @@ export interface ApplyWordPressPatchesStep {
 	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
@@ -1103,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;
 }
 /**
@@ -1127,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;
 }
 /**
@@ -1270,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;
@@ -1331,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;
 }
 /**
@@ -1380,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;
 }
 /**
@@ -1401,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;
 }
 /**
@@ -1430,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;
 }
 /**
@@ -1452,7 +1501,9 @@ export declare const request: StepHandler<RequestStep>;
  */
 export interface CpStep {
 	step: "cp";
+	/** Source path */
 	fromPath: string;
+	/** Target path */
 	toPath: string;
 }
 /**
@@ -1475,7 +1526,9 @@ export declare const cp: StepHandler<CpStep>;
  */
 export interface MvStep {
 	step: "mv";
+	/** Source path */
 	fromPath: string;
+	/** Target path */
 	toPath: string;
 }
 /**
@@ -1496,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;
 }
 /**
@@ -1517,6 +1571,7 @@ export declare const mkdir: StepHandler<MkdirStep>;
  */
 export interface RmStep {
 	step: "rm";
+	/** The path to remove */
 	path: string;
 }
 /**
@@ -1538,6 +1593,7 @@ export declare const rm: StepHandler<RmStep>;
  */
 export interface RmdirStep {
 	step: "rmdir";
+	/** The path to remove */
 	path: string;
 }
 /**
@@ -1560,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;
 }
 /**
@@ -1568,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";
@@ -1583,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.
@@ -1655,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 {
@@ -1781,6 +1857,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 +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;
 	}>;
-	resetOpfs(): Promise<void>;
+	resetVirtualOpfs(): Promise<void>;
+	reloadFilesFromOpfs(): Promise<void>;
+	bindOpfs(opfs: FileSystemDirectoryHandle, onProgress?: SyncProgressCallback): Promise<void>;
 }
 export interface ProgressBarOptions {
 	caption?: string;
@@ -1845,6 +1931,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.