@php-wasm/web 0.1.46 → 0.1.49

package/{index-61d766d5.js → index-40326b86.js}

@@ -1448,22 +1448,25 @@ class Ge {
       monitor: r
     }), this.absoluteUrl = e.absoluteUrl, this.documentRoot = e.documentRoot;
   }
-  /** @inheritDoc */
+  /** @inheritDoc @php-wasm/universal!RequestHandler.pathToInternalUrl  */
   pathToInternalUrl(e) {
     return d.get(this).php.pathToInternalUrl(e);
   }
-  /** @inheritDoc */
+  /** @inheritDoc @php-wasm/universal!RequestHandler.internalUrlToPath  */
   internalUrlToPath(e) {
     return d.get(this).php.internalUrlToPath(e);
   }
+  /**
+   * The onDownloadProgress event listener.
+   */
   async onDownloadProgress(e) {
     return d.get(this).monitor?.addEventListener("progress", e);
   }
-  /** @inheritDoc */
+  /** @inheritDoc @php-wasm/universal!IsomorphicLocalPHP.mv  */
   mv(e, r) {
     return d.get(this).php.mv(e, r);
   }
-  /** @inheritDoc */
+  /** @inheritDoc @php-wasm/universal!IsomorphicLocalPHP.rmdir  */
   rmdir(e, r) {
     return d.get(this).php.rmdir(e, r);
   }

package/index.d.ts

@@ -15,7 +15,7 @@ export type WithAPIState = {
 	 */
 	isReady: () => Promise<void>;
 };
-export type RemoteAPI<T> = Comlink.Remote<T & WithAPIState>;
+export type RemoteAPI<T> = Comlink.Remote<T> & WithAPIState;
 export declare function consumeAPI<APIType>(remote: Worker | Window): RemoteAPI<APIType>;
 export type PublicAPI<Methods, PipedAPI = unknown> = RemoteAPI<Methods & PipedAPI>;
 export declare function exposeAPI<Methods, PipedAPI>(apiMethods?: Methods, pipedApi?: PipedAPI): [
@@ -127,7 +127,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
@@ -174,7 +200,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.
@@ -266,24 +303,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>;
 }
@@ -590,20 +675,23 @@ export declare class WebPHP extends BasePHP {
  * A PHP client that can be used to run PHP code in the browser.
  */
 export 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>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@php-wasm/web",
-	"version": "0.1.46",
+	"version": "0.1.49",
 	"description": "PHP.wasm for the web",
 	"repository": {
 		"type": "git",
@@ -29,5 +29,5 @@
 	"type": "module",
 	"main": "index.js",
 	"types": "index.d.ts",
-	"gitHead": "b1e1b4b57b00fb52429f0490af4ccb943f496f74"
+	"gitHead": "93834fa77a89c21be2ade4c1d67430981ed92c83"
 }