@wp-playground/client 0.1.46 → 0.1.49

package/blueprint-schema.json

@@ -646,10 +646,12 @@
             },
             "step": {
               "type": "string",
-              "const": "runPHP"
+              "const": "runPHP",
+              "description": "The step identifier."
             },
             "code": {
-              "type": "string"
+              "type": "string",
+              "description": "The PHP code to run."
             }
           },
           "required": [
@@ -766,11 +768,13 @@
             },
             "step": {
               "type": "string",
-              "const": "setSiteOptions"
+              "const": "setSiteOptions",
+              "description": "The name of the step. Must be \"setSiteOptions\"."
             },
             "options": {
               "type": "object",
-              "additionalProperties": {}
+              "additionalProperties": {},
+              "description": "The options to set on the site."
             }
           },
           "required": [

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>;
 }
@@ -1152,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.
@@ -1268,6 +1570,10 @@ export type StepDefinition = Step & {
 		caption?: string;
 	};
 };
+/**
+ * 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>> = (
 /**
@@ -1354,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;
@@ -1389,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>;
@@ -1434,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;
@@ -1450,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;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wp-playground/client",
-	"version": "0.1.46",
+	"version": "0.1.49",
 	"description": "WordPress Playground client",
 	"repository": {
 		"type": "git",
@@ -37,5 +37,5 @@
 	"main": "./index.cjs",
 	"module": "./index.js",
 	"types": "index.d.ts",
-	"gitHead": "b1e1b4b57b00fb52429f0490af4ccb943f496f74"
+	"gitHead": "93834fa77a89c21be2ade4c1d67430981ed92c83"
 }