@php-wasm/node 0.1.46 → 0.1.49

package/index.cjs

@@ -68273,8 +68273,12 @@ var _NodePHP = class extends BasePHP2 {
   /**
    * Starts a PHP CLI session with given arguments.
    *
-   * Can only be used when PHP was compiled with the CLI SAPI.
-   * Cannot be used in conjunction with `run()`.
+   * This method can only be used when PHP was compiled with the CLI SAPI
+   * and it cannot be used in conjunction with `run()`.
+   *
+   * Once this method finishes running, the PHP instance is no
+   * longer usable and should be discarded. This is because PHP
+   * internally cleans up all the resources and calls exit().
    *
    * @param  argv - The arguments to pass to the CLI.
    * @returns The exit code of the CLI session.

package/index.d.ts

@@ -105,7 +105,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
@@ -152,7 +178,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.
@@ -244,24 +281,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>;
 }
@@ -567,8 +652,12 @@ export declare class NodePHP extends BasePHP {
 	/**
 	 * Starts a PHP CLI session with given arguments.
 	 *
-	 * Can only be used when PHP was compiled with the CLI SAPI.
-	 * Cannot be used in conjunction with `run()`.
+	 * This method can only be used when PHP was compiled with the CLI SAPI
+	 * and it cannot be used in conjunction with `run()`.
+	 *
+	 * Once this method finishes running, the PHP instance is no
+	 * longer usable and should be discarded. This is because PHP
+	 * internally cleans up all the resources and calls exit().
 	 *
 	 * @param  argv - The arguments to pass to the CLI.
 	 * @returns The exit code of the CLI session.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@php-wasm/node",
-  "version": "0.1.46",
+  "version": "0.1.49",
   "description": "PHP.wasm for Node.js",
   "repository": {
     "type": "git",
@@ -28,13 +28,13 @@
   "license": "GPL-2.0-or-later",
   "main": "index.cjs",
   "types": "index.d.ts",
-  "gitHead": "b1e1b4b57b00fb52429f0490af4ccb943f496f74",
+  "gitHead": "93834fa77a89c21be2ade4c1d67430981ed92c83",
   "dependencies": {
     "comlink": "^4.4.1",
     "express": "4.18.2",
     "ws": "8.13.0",
     "yargs": "17.7.2",
-    "@php-wasm/universal": "0.1.46",
-    "@php-wasm/util": "0.1.46"
+    "@php-wasm/universal": "0.1.49",
+    "@php-wasm/util": "0.1.49"
   }
 }