@php-wasm/universal 0.1.46 → 0.1.51

package/lib/universal-php.d.ts

@@ -58,7 +58,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
@@ -105,7 +131,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.
@@ -197,24 +234,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>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@php-wasm/universal",
-	"version": "0.1.46",
+	"version": "0.1.51",
 	"description": "PHP.wasm – emscripten bindings for PHP",
 	"repository": {
 		"type": "git",
@@ -36,5 +36,5 @@
 	"main": "./index.cjs",
 	"module": "./index.js",
 	"license": "GPL-2.0-or-later",
-	"gitHead": "b1e1b4b57b00fb52429f0490af4ccb943f496f74"
+	"gitHead": "756f9e316b51bc1496982fa4ed9310a16701afa5"
 }