@php-wasm/node 0.1.45 → 0.1.49

package/index.cjs

@@ -67117,6 +67117,16 @@ var PHPRequestHandler = class {
       } else {
         body = request.body;
       }
+      let scriptPath;
+      try {
+        scriptPath = this.#resolvePHPFilePath(requestedUrl.pathname);
+      } catch (error) {
+        return new PHPResponse(
+          404,
+          {},
+          new TextEncoder().encode("404 File not found")
+        );
+      }
       return await this.php.run({
         relativeUri: ensurePathPrefix(
           toRelativeUrl(requestedUrl),
@@ -67126,7 +67136,7 @@ var PHPRequestHandler = class {
         method: request.method || preferredMethod,
         body,
         fileInfos,
-        scriptPath: this.#resolvePHPFilePath(requestedUrl.pathname),
+        scriptPath,
         headers
       });
     } finally {
@@ -67139,6 +67149,7 @@ var PHPRequestHandler = class {
    * Fall back to index.php as if there was a url rewriting rule in place.
    *
    * @param  requestedPath - The requested pathname.
+   * @throws {Error} If the requested path doesn't exist.
    * @returns The resolved filesystem path.
    */
   #resolvePHPFilePath(requestedPath) {
@@ -67157,6 +67168,9 @@ var PHPRequestHandler = class {
     if (this.php.fileExists(resolvedFsPath)) {
       return resolvedFsPath;
     }
+    if (!this.php.fileExists(`${this.#DOCROOT}/index.php`)) {
+      throw new Error(`File not found: ${resolvedFsPath}`);
+    }
     return `${this.#DOCROOT}/index.php`;
   }
 };
@@ -67691,7 +67705,7 @@ var BasePHP2 = class {
     let exitCode;
     let errorListener;
     try {
-      exitCode = await new Promise(async (resolve, reject) => {
+      exitCode = await new Promise((resolve, reject) => {
         errorListener = (e) => {
           const rethrown = new Error("Rethrown");
           rethrown.cause = e.error;
@@ -67702,24 +67716,16 @@ var BasePHP2 = class {
           "error",
           errorListener
         );
-        try {
-          resolve(
-            /**
-             * This is awkward, but Asyncify makes wasm_sapi_handle_request return
-             * Promise<Promise<number>>.
-             *
-             * @TODO: Determine whether this is a bug in emscripten or in our code.
-             */
-            await await this[__private__dont__use].ccall(
-              "wasm_sapi_handle_request",
-              NUMBER,
-              [],
-              []
-            )
-          );
-        } catch (e) {
-          reject(e);
+        const response = this[__private__dont__use].ccall(
+          "wasm_sapi_handle_request",
+          NUMBER,
+          [],
+          []
+        );
+        if (response instanceof Promise) {
+          return response.then(resolve, reject);
         }
+        return resolve(response);
       });
     } catch (e) {
       for (const name in this) {
@@ -68267,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.45",
+  "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": "ca75514c17b912dc8b5dc529f6d123295671320a",
+  "gitHead": "93834fa77a89c21be2ade4c1d67430981ed92c83",
   "dependencies": {
-    "comlink": "4.4.1",
+    "comlink": "^4.4.1",
     "express": "4.18.2",
     "ws": "8.13.0",
     "yargs": "17.7.2",
-    "@php-wasm/universal": "0.1.45",
-    "@php-wasm/util": "0.1.45"
+    "@php-wasm/universal": "0.1.49",
+    "@php-wasm/util": "0.1.49"
   }
 }