@wp-playground/client 0.1.45 → 0.1.49

package/index.d.ts

@@ -259,7 +259,33 @@ export interface RequestHandler {
 	/**
 	 * Serves the request – either by serving a static file, or by
 	 * dispatching it to the PHP runtime.
-	 * Cannot be used in conjunction with `cli()`.
+	 *
+	 * The request() method mode behaves like a web server and only works if
+	 * the PHP was initialized with a `requestHandler` option (which the online version
+	 * of WordPress Playground does by default).
+	 *
+	 * In the request mode, you pass an object containing the request information
+	 * (method, headers, body, etc.) and the path to the PHP file to run:
+	 *
+	 * ```ts
+	 * const php = PHP.load('7.4', {
+	 * 	requestHandler: {
+	 * 		documentRoot: "/www"
+	 * 	}
+	 * })
+	 * php.writeFile("/www/index.php", `<?php echo file_get_contents("php://input");`);
+	 * const result = await php.run({
+	 * 	method: "GET",
+	 * 	headers: {
+	 * 		"Content-Type": "text/plain"
+	 * 	},
+	 * 	body: "Hello world!",
+	 * 	path: "/www/index.php"
+	 * });
+	 * // result.text === "Hello world!"
+	 * ```
+	 *
+	 * The `request()` method cannot be used in conjunction with `cli()`.
 	 *
 	 * @example
 	 * ```js
@@ -306,7 +332,18 @@ export interface RequestHandler {
 	documentRoot: string;
 }
 export interface IsomorphicLocalPHP extends RequestHandler {
+	/**
+	 * Sets the path to the php.ini file to use for the PHP instance.
+	 *
+	 * @param path - The path to the php.ini file.
+	 */
 	setPhpIniPath(path: string): void;
+	/**
+	 * Sets a value for a specific key in the php.ini file for the PHP instance.
+	 *
+	 * @param key - The key to set the value for.
+	 * @param value - The value to set for the key.
+	 */
 	setPhpIniEntry(key: string, value: string): void;
 	/**
 	 * Recursively creates a directory with the given path in the PHP filesystem.
@@ -398,24 +435,72 @@ export interface IsomorphicLocalPHP extends RequestHandler {
 	chdir(path: string): void;
 	/**
 	 * Runs PHP code.
-	 * Cannot be used in conjunction with `cli()`.
 	 *
-	 * @example
-	 * ```js
-	 * const output = await php.run('<?php echo "Hello world!";');
-	 * console.log(output.stdout); // "Hello world!"
+	 * This low-level method directly interacts with the WebAssembly
+	 * PHP interpreter.
+	 *
+	 * Every time you call run(), it prepares the PHP
+	 * environment and:
+	 *
+	 * * Resets the internal PHP state
+	 * * Populates superglobals ($_SERVER, $_GET, etc.)
+	 * * Handles file uploads
+	 * * Populates input streams (stdin, argv, etc.)
+	 * * Sets the current working directory
+	 *
+	 * You can use run() in two primary modes:
+	 *
+	 * ### Code snippet mode
+	 *
+	 * In this mode, you pass a string containing PHP code to run.
+	 *
+	 * ```ts
+	 * const result = await php.run({
+	 * 	code: `<?php echo "Hello world!";`
+	 * });
+	 * // result.text === "Hello world!"
 	 * ```
 	 *
+	 * In this mode, information like __DIR__ or __FILE__ isn't very
+	 * useful because the code is not associated with any file.
+	 *
+	 * Under the hood, the PHP snippet is passed to the `zend_eval_string`
+	 * C function.
+	 *
+	 * ### File mode
+	 *
+	 * In the file mode, you pass a scriptPath and PHP executes a file
+	 * found at a that path:
+	 *
+	 * ```ts
+	 * php.writeFile(
+	 * 	"/www/index.php",
+	 * 	`<?php echo "Hello world!";"`
+	 * );
+	 * const result = await php.run({
+	 * 	scriptPath: "/www/index.php"
+	 * });
+	 * // result.text === "Hello world!"
+	 * ```
+	 *
+	 * In this mode, you can rely on path-related information like __DIR__
+	 * or __FILE__.
+	 *
+	 * Under the hood, the PHP file is executed with the `php_execute_script`
+	 * C function.
+	 *
+	 * The `run()` method cannot be used in conjunction with `cli()`.
+	 *
 	 * @example
 	 * ```js
-	 * console.log(await php.run(`<?php
+	 * const result = await php.run(`<?php
 	 *  $fp = fopen('php://stderr', 'w');
 	 *  fwrite($fp, "Hello, world!");
-	 * `));
-	 * // {"exitCode":0,"stdout":"","stderr":["Hello, world!"]}
+	 * `);
+	 * // result.errors === "Hello, world!"
 	 * ```
 	 *
-	 * @param  options - PHP run options.
+	 * @param  options - PHP runtime options.
 	 */
 	run(options: PHPRunOptions): Promise<PHPResponse>;
 }
@@ -926,7 +1011,7 @@ export declare class SemaphoreResource<T extends Resource> extends DecoratedReso
 }
 export interface ActivatePluginStep {
 	step: "activatePlugin";
-	plugin: string;
+	pluginPath: string;
 }
 /**
  * Activates a WordPress plugin in the Playground.
@@ -1004,14 +1089,19 @@ export interface ImportFileStep<ResourceType> {
  */
 export declare const importFile: StepHandler<ImportFileStep<File>>;
 /**
- * The step to install a WordPress plugin in the Playground.
- *
+ * @inheritDoc installPlugin
+ * @hasRunnableExample
+ * @needsLogin
+ * @landingPage /wp-admin/plugins.php
  * @example
  *
  * <code>
  * {
  * 	    "step": "installPlugin",
- * 		"pluginZipFile": "http://example.com/plugin.zip",
+ * 		"pluginZipFile": {
+ * 			"resource": "wordpress.org/plugins",
+ * 			"slug": "gutenberg"
+ * 		},
  * 		"options": {
  * 			"activate": true
  * 		}
@@ -1048,10 +1138,43 @@ export interface InstallPluginOptions {
  * @param options Optional. Set `activate` to false if you don't want to activate the plugin.
  */
 export declare const installPlugin: StepHandler<InstallPluginStep<File>>;
+/**
+ * @inheritDoc installTheme
+ * @hasRunnableExample
+ * @needsLogin
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "installTheme",
+ * 		"themeZipFile": {
+ * 			"resource": "wordpress.org/themes",
+ * 			"slug": "pendant"
+ * 		},
+ * 		"options": {
+ * 			"activate": true
+ * 		}
+ * }
+ * </code>
+ */
 export interface InstallThemeStep<ResourceType> {
+	/**
+	 * The step identifier.
+	 */
 	step: "installTheme";
+	/**
+	 * The theme zip file to install.
+	 */
 	themeZipFile: ResourceType;
-	options?: InstallThemeOptions;
+	/**
+	 * Optional installation options.
+	 */
+	options?: {
+		/**
+		 * Whether to activate the theme after installing it.
+		 */
+		activate?: boolean;
+	};
 }
 export interface InstallThemeOptions {
 	/**
@@ -1069,19 +1192,34 @@ export interface InstallThemeOptions {
  * @param options Optional. Set `activate` to false if you don't want to activate the theme.
  */
 export declare const installTheme: StepHandler<InstallThemeStep<File>>;
+/**
+ * @inheritDoc login
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 	    "step": "login",
+ * 		"username": "admin",
+ * 		"password": "password"
+ * }
+ * </code>
+ */
 export type LoginStep = {
 	step: "login";
+	/**
+	 * The user to log in as. Defaults to 'admin'.
+	 */
 	username?: string;
+	/**
+	 * The password to log in with. Defaults to 'password'.
+	 */
 	password?: string;
 };
 /**
  * Logs in to the Playground.
  * Under the hood, this function submits the wp-login.php form
  * just like a user would.
- *
- * @param playground The playground client.
- * @param user The user to log in as. Defaults to 'admin'.
- * @param password The password to log in with. Defaults to 'password'.
  */
 export declare const login: StepHandler<LoginStep>;
 export interface RunWpInstallationWizardStep {
@@ -1099,70 +1237,287 @@ export interface WordPressInstallationOptions {
  * @param options Installation options.
  */
 export declare const runWpInstallationWizard: StepHandler<RunWpInstallationWizardStep>;
+/**
+ * @inheritDoc setSiteOptions
+ * @hasRunnableExample
+ *
+ * @example
+ *
+ * <code>
+ * {
+ *     "step": "setSiteOptions",
+ *     "options": {
+ *         "blogname": "My Blog",
+ *         "blogdescription": "A great blog"
+ *     }
+ * }
+ * </code>
+ */
 export type SetSiteOptionsStep = {
+	/** The name of the step. Must be "setSiteOptions". */
 	step: "setSiteOptions";
+	/** The options to set on the site. */
 	options: Record<string, unknown>;
 };
+/**
+ * Sets site options. This is equivalent to calling `update_option` for each
+ * option in the `options` object.
+ */
 export declare const setSiteOptions: StepHandler<SetSiteOptionsStep>;
+/**
+ * @inheritDoc updateUserMeta
+ * @hasRunnableExample
+ *
+ * @example
+ *
+ * <code>
+ * {
+ *     "step": "updateUserMeta",
+ *     "meta": {
+ * 	       "first_name": "John",
+ * 	       "last_name": "Doe"
+ *     },
+ *     "userId": 1
+ * }
+ * </code>
+ */
 export interface UpdateUserMetaStep {
 	step: "updateUserMeta";
 	meta: Record<string, unknown>;
 	userId: number;
 }
+/**
+ * Updates user meta. This is equivalent to calling `update_user_meta` for each
+ * meta value in the `meta` object.
+ */
 export declare const updateUserMeta: StepHandler<UpdateUserMetaStep>;
+/**
+ * @inheritDoc runPHP
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "runPHP",
+ * 		"code": "<?php echo 'Hello World'; ?>"
+ * }
+ * </code>
+ */
 export interface RunPHPStep {
+	/** The step identifier. */
 	step: "runPHP";
+	/** The PHP code to run. */
 	code: string;
 }
+/**
+ * Runs PHP code.
+ */
 export declare const runPHP: StepHandler<RunPHPStep>;
+/**
+ * @inheritDoc runPHP
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "runPHP",
+ * 		"options": {
+ * 			"code": "<?php echo $_SERVER['HTTP_CONTENT_TYPE']; ?>",
+ * 			"headers": {
+ * 				"Content-type": "text/plain"
+ * 			}
+ * 		}
+ * }
+ * </code>
+ */
 export interface RunPHPWithOptionsStep {
 	step: "runPHPWithOptions";
 	options: PHPRunOptions;
 }
+/**
+ * Runs PHP code with the given options.
+ */
 export declare const runPHPWithOptions: StepHandler<RunPHPWithOptionsStep>;
+/**
+ * @inheritDoc setPhpIniEntry
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "setPhpIniEntry",
+ * 		"key": "display_errors",
+ * 		"value": "1"
+ * }
+ * </code>
+ */
 export interface SetPhpIniEntryStep {
 	step: "setPhpIniEntry";
 	key: string;
 	value: string;
 }
+/**
+ * Sets a PHP ini entry.
+ */
 export declare const setPhpIniEntry: StepHandler<SetPhpIniEntryStep>;
+/**
+ * @inheritDoc request
+ * @needsLogin
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "request",
+ * 		"request": {
+ * 			"method": "POST",
+ * 			"url": "/wp-admin/admin-ajax.php",
+ * 			"formData": {
+ * 				"action": "my_action",
+ * 				"foo": "bar"
+ * 			}
+ * 		}
+ * }
+ * </code>
+ */
 export interface RequestStep {
 	step: "request";
 	request: PHPRequest;
 }
+/**
+ * Sends a HTTP request to the Playground.
+ */
 export declare const request: StepHandler<RequestStep>;
+/**
+ * @inheritDoc cp
+ * @hasRunnableExample
+ * @landingPage /index2.php
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "cp",
+ * 		"fromPath": "/wordpress/index.php",
+ * 		"toPath": "/wordpress/index2.php"
+ * }
+ * </code>
+ */
 export interface CpStep {
 	step: "cp";
 	fromPath: string;
 	toPath: string;
 }
+/**
+ * Copies a file from one path to another.
+ */
 export declare const cp: StepHandler<CpStep>;
+/**
+ * @inheritDoc mv
+ * @hasRunnableExample
+ * @landingPage /index2.php
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "mv",
+ * 		"fromPath": "/wordpress/index.php",
+ * 		"toPath": "/wordpress/index2.php"
+ * }
+ * </code>
+ */
 export interface MvStep {
 	step: "mv";
 	fromPath: string;
 	toPath: string;
 }
+/**
+ * Moves a file or directory from one path to another.
+ */
 export declare const mv: StepHandler<MvStep>;
+/**
+ * @inheritDoc mkdir
+ * @hasRunnableExample
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "mkdir",
+ * 		"path": "/wordpress/my-new-folder"
+ * }
+ * </code>
+ */
 export interface MkdirStep {
 	step: "mkdir";
 	path: string;
 }
+/**
+ * Creates a directory at the specified path.
+ */
 export declare const mkdir: StepHandler<MkdirStep>;
+/**
+ * @inheritDoc rm
+ * @hasRunnableExample
+ * @landingPage /index.php
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "rm",
+ * 		"path": "/wordpress/index.php"
+ * }
+ * </code>
+ */
 export interface RmStep {
 	step: "rm";
 	path: string;
 }
+/**
+ * Removes a file at the specified path.
+ */
 export declare const rm: StepHandler<RmStep>;
+/**
+ * @inheritDoc rmdir
+ * @hasRunnableExample
+ * @landingPage /wp-admin/
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "rm",
+ * 		"path": "/wordpress/wp-admin"
+ * }
+ * </code>
+ */
 export interface RmdirStep {
 	step: "rmdir";
 	path: string;
 }
+/**
+ * Removes a directory at the specified path.
+ */
 export declare const rmdir: StepHandler<RmdirStep>;
+/**
+ * @inheritDoc writeFile
+ * @hasRunnableExample
+ * @landingPage /test.php
+ * @example
+ *
+ * <code>
+ * {
+ * 		"step": "writeFile",
+ * 		"path": "/wordpress/test.php",
+ * 		"data": "<?php echo 'Hello World!'; ?>"
+ * }
+ * </code>
+ */
 export interface WriteFileStep<ResourceType> {
 	step: "writeFile";
 	path: string;
 	data: ResourceType | string | Uint8Array;
 }
+/**
+ * Writes data to a file at the specified path.
+ */
 export declare const writeFile: StepHandler<WriteFileStep<File>>;
 /**
  * The step object for defining constants in the wp-config.php file of a WordPress installation.
@@ -1179,6 +1534,17 @@ export interface DefineWpConfigConstsStep {
  * @param wpConfigConst
  */
 export declare const defineWpConfigConsts: StepHandler<DefineWpConfigConstsStep>;
+export interface ActivateThemeStep {
+	step: "activateTheme";
+	themeFolderName: string;
+}
+/**
+ * Activates a WordPress theme in the Playground.
+ *
+ * @param playground The playground client.
+ * @param themeFolderName The theme folder name.
+ */
+export declare const activateTheme: StepHandler<ActivateThemeStep>;
 /**
  * The step object for defining constants in the VFS_CONFIG_FILE_PATH php file and loaded using the auto_prepend_file php.ini directive.
  */
@@ -1204,8 +1570,20 @@ export type StepDefinition = Step & {
 		caption?: string;
 	};
 };
-export type GenericStep<Resource> = ActivatePluginStep | ApplyWordPressPatchesStep | CpStep | DefineWpConfigConstsStep | DefineVirtualWpConfigConstsStep | 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 StepHandler<S extends GenericStep<File>> = (php: UniversalPHP, args: Omit<S, "step">, progressArgs?: {
+/**
+ * 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 | DefineVirtualWpConfigConstsStep | 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 StepHandler<S extends GenericStep<File>> = (
+/**
+ * A PHP instance or Playground client.
+ */
+php: UniversalPHP, args: Omit<S, "step">, 
+/**
+ * Progress reporting details.
+ */
+progressArgs?: {
 	tracker: ProgressTracker;
 	initialCaption?: string;
 }) => any;
@@ -1282,7 +1660,7 @@ export type WithAPIState = {
 	 */
 	isReady: () => Promise<void>;
 };
-export type RemoteAPI<T> = Comlink.Remote<T & WithAPIState>;
+export type RemoteAPI<T> = Comlink.Remote<T> & WithAPIState;
 export interface PHPWebLoaderOptions {
 	emscriptenOptions?: EmscriptenOptions;
 	downloadMonitor?: EmscriptenDownloadMonitor;
@@ -1317,20 +1695,23 @@ declare class WebPHP extends BasePHP {
 	};
 }
 declare class WebPHPEndpoint implements IsomorphicLocalPHP {
-	/** @inheritDoc */
+	/** @inheritDoc @php-wasm/universal!RequestHandler.absoluteUrl  */
 	absoluteUrl: string;
-	/** @inheritDoc */
+	/** @inheritDoc @php-wasm/universal!RequestHandler.documentRoot  */
 	documentRoot: string;
 	/** @inheritDoc */
 	constructor(php: BasePHP, monitor?: EmscriptenDownloadMonitor);
-	/** @inheritDoc */
+	/** @inheritDoc @php-wasm/universal!RequestHandler.pathToInternalUrl  */
 	pathToInternalUrl(path: string): string;
-	/** @inheritDoc */
+	/** @inheritDoc @php-wasm/universal!RequestHandler.internalUrlToPath  */
 	internalUrlToPath(internalUrl: string): string;
+	/**
+	 * The onDownloadProgress event listener.
+	 */
 	onDownloadProgress(callback: (progress: CustomEvent<ProgressEvent>) => void): Promise<void>;
-	/** @inheritDoc */
+	/** @inheritDoc @php-wasm/universal!IsomorphicLocalPHP.mv  */
 	mv(fromPath: string, toPath: string): void;
-	/** @inheritDoc */
+	/** @inheritDoc @php-wasm/universal!IsomorphicLocalPHP.rmdir  */
 	rmdir(path: string, options?: RmDirOptions): void;
 	/** @inheritDoc @php-wasm/universal!RequestHandler.request */
 	request(request: PHPRequest, redirects?: number): Promise<PHPResponse>;
@@ -1362,10 +1743,22 @@ declare class WebPHPEndpoint implements IsomorphicLocalPHP {
 	fileExists(path: string): boolean;
 }
 declare class PlaygroundWorkerEndpoint extends WebPHPEndpoint {
+	/**
+	 * A string representing the scope of the Playground instance.
+	 */
 	scope: string;
+	/**
+	 * A string representing the version of WordPress being used.
+	 */
 	wordPressVersion: string;
+	/**
+	 * A string representing the version of PHP being used.
+	 */
 	phpVersion: string;
 	constructor(php: WebPHP, monitor: EmscriptenDownloadMonitor, scope: string, wordPressVersion: string, phpVersion: string);
+	/**
+	 * @returns WordPress module details, including the static assets directory and default theme.
+	 */
 	getWordPressModuleDetails(): Promise<{
 		staticAssetsDirectory: string;
 		defaultTheme: any;
@@ -1378,18 +1771,44 @@ export interface ProgressBarOptions {
 	visible?: boolean;
 }
 export interface WebClientMixin extends ProgressReceiver {
+	/**
+	 * Sets the progress bar options.
+	 * @param options The progress bar options.
+	 */
 	setProgress(options: ProgressBarOptions): Promise<void>;
+	/**
+	 * Sets the loaded state.
+	 */
 	setLoaded(): Promise<void>;
+	/**
+	 * Sets the navigation event listener.
+	 * @param fn The function to be called when a navigation event occurs.
+	 */
 	onNavigation(fn: (url: string) => void): Promise<void>;
+	/**
+	 * Navigates to the requested path.
+	 * @param requestedPath The requested path.
+	 */
 	goTo(requestedPath: string): Promise<void>;
+	/**
+	 * Gets the current URL.
+	 */
 	getCurrentURL(): Promise<string>;
+	/**
+	 * Sets the iframe sandbox flags.
+	 * @param flags The iframe sandbox flags.
+	 */
 	setIframeSandboxFlags(flags: string[]): Promise<void>;
+	/**
+	 * The onDownloadProgress event listener.
+	 */
 	onDownloadProgress: PlaygroundWorkerEndpoint["onDownloadProgress"];
 }
 /**
- * @inheritDoc
+ * The Playground Client interface.
  */
-export type PlaygroundClient = RemoteAPI<PlaygroundWorkerEndpoint & WebClientMixin>;
+export interface PlaygroundClient extends RemoteAPI<PlaygroundWorkerEndpoint & WebClientMixin> {
+}
 export interface StartPlaygroundOptions {
 	iframe: HTMLIFrameElement;
 	remoteUrl: string;