@php-wasm/universal 0.6.16 → 0.7.1

package/lib/base-php.d.ts

@@ -1,5 +1,4 @@
-import { PHPBrowser } from './php-browser';
-import { PHPRequestHandlerConfiguration } from './php-request-handler';
+import { PHPRequestHandler, PHPRequestHandlerConfiguration } from './php-request-handler';
 import { PHPResponse } from './php-response';
 import type { PHPRuntimeId } from './load-php-runtime';
 import { IsomorphicLocalPHP, MessageListener, PHPRequest, PHPRequestHeaders, PHPRunOptions, RmDirOptions, ListFilesOptions, SpawnHandler, PHPEventListener, PHPEvent } from './universal-php';
@@ -21,7 +20,7 @@ export declare class PHPExecutionFailureError extends Error {
 export declare abstract class BasePHP implements IsomorphicLocalPHP {
     #private;
     protected [__private__dont__use]: any;
-    requestHandler?: PHPBrowser;
+    requestHandler?: PHPRequestHandler;
     /**
      * An exclusive lock that prevent multiple requests from running at
      * the same time.
@@ -60,10 +59,9 @@ export declare abstract class BasePHP implements IsomorphicLocalPHP {
     /** @inheritDoc */
     chdir(path: string): void;
     /** @inheritDoc */
-    request(request: PHPRequest, maxRedirects?: number): Promise<PHPResponse>;
+    request(request: PHPRequest): Promise<PHPResponse>;
     /** @inheritDoc */
     run(request: PHPRunOptions): Promise<PHPResponse>;
-    addServerGlobalEntry(key: string, value: string): void;
     defineConstant(key: string, value: string | boolean | number | null): void;
     /** @inheritDoc */
     mkdir(path: string): void;
@@ -92,8 +90,12 @@ export declare abstract class BasePHP implements IsomorphicLocalPHP {
      * interrupting the operations of this PHP instance.
      *
      * @param runtime
+     * @param cwd. Internal, the VFS path to recreate in the new runtime.
+     *             This arg is temporary and will be removed once BasePHP
+     *             is fully decoupled from the request handler and
+     *             accepts a constructor-level cwd argument.
      */
-    hotSwapPHPRuntime(runtime: number): void;
+    hotSwapPHPRuntime(runtime: number, cwd?: string): void;
     exit(code?: number): void;
 }
 export declare function normalizeHeaders(headers: PHPRequestHeaders): PHPRequestHeaders;

package/lib/http-cookie-store.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @public
+ */
+export declare class HttpCookieStore {
+    cookies: Record<string, string>;
+    rememberCookiesFromResponseHeaders(headers: Record<string, string[]>): void;
+    getCookieRequestHeader(): string;
+}

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export type { IsomorphicLocalPHP, IsomorphicRemotePHP, MessageListener, PHPOutput, PHPRunOptions, UniversalPHP, ListFilesOptions, RmDirOptions, PHPEvent, PHPEventListener, HTTPMethod, PHPRequest, PHPRequestHeaders, RequestHandler, SpawnHandler, } from './universal-php';
+export type { IsomorphicLocalPHP, IsomorphicRemotePHP, MessageListener, PHPOutput, PHPRunOptions, UniversalPHP, ListFilesOptions, RmDirOptions, PHPEvent, PHPEventListener, HTTPMethod, PHPRequest, PHPRequestHeaders, SpawnHandler, } from './universal-php';
 export { UnhandledRejectionsTarget } from './wasm-error-reporting';
 export type { IteratePhpFilesOptions as IterateFilesOptions } from './iterate-files';
 export { iteratePhpFiles as iterateFiles } from './iterate-files';
@@ -18,8 +18,6 @@ export { isLocalPHP } from './is-local-php';
 export { isRemotePHP } from './is-remote-php';
 export type { PHPRequestHandlerConfiguration, RewriteRule, } from './php-request-handler';
 export { PHPRequestHandler, applyRewriteRules } from './php-request-handler';
-export type { PHPBrowserConfiguration } from './php-browser';
-export { PHPBrowser } from './php-browser';
 export { rotatePHPRuntime } from './rotate-php-runtime';
 export { writeFiles } from './write-files';
 export { DEFAULT_BASE_URL, ensurePathPrefix, removePathPrefix, toRelativeUrl, } from './urls';

package/lib/load-php-runtime.d.ts

@@ -145,5 +145,6 @@ export type EmscriptenOptions = {
     onRuntimeInitialized?: () => void;
     monitorRunDependencies?: (left: number) => void;
     onMessage?: (listener: EmscriptenMessageListener) => void;
+    instantiateWasm?: (info: WebAssembly.Imports, receiveInstance: (instance: WebAssembly.Instance, module: WebAssembly.Module) => void) => void;
 } & Record<string, any>;
 export type EmscriptenMessageListener = (type: string, data: string) => void;

package/lib/php-request-handler.d.ts

@@ -1,6 +1,6 @@
 import { BasePHP } from './base-php';
 import { PHPResponse } from './php-response';
-import { PHPRequest, RequestHandler } from './universal-php';
+import { PHPRequest } from './universal-php';
 export type RewriteRule = {
     match: RegExp;
     replacement: string;
@@ -20,8 +20,61 @@ export interface PHPRequestHandlerConfiguration {
      */
     rewriteRules?: RewriteRule[];
 }
-/** @inheritDoc */
-export declare class PHPRequestHandler implements RequestHandler {
+/**
+ * Handles HTTP requests using PHP runtime as a backend.
+ *
+ * @public
+ * @example Use PHPRequestHandler implicitly with a new PHP instance:
+ * ```js
+ * import { PHP } from '../../../web/src/index.ts';
+ *
+ * const php = await PHP.load( '7.4', {
+ *     requestHandler: {
+ *         // PHP FS path to serve the files from:
+ *         documentRoot: '/www',
+ *
+ *         // Used to populate $_SERVER['SERVER_NAME'] etc.:
+ *         absoluteUrl: 'http://127.0.0.1'
+ *     }
+ * } );
+ *
+ * php.mkdirTree('/www');
+ * php.writeFile('/www/index.php', '<?php echo "Hi from PHP!"; ');
+ *
+ * const response = await php.request({ path: '/index.php' });
+ * console.log(response.text);
+ * // "Hi from PHP!"
+ * ```
+ *
+ * @example Explicitly create a PHPRequestHandler instance and run a PHP script:
+ * ```js
+ * import {
+ *   loadPHPRuntime,
+ *   PHP,
+ *   PHPRequestHandler,
+ *   getPHPLoaderModule,
+ * } from '@php-wasm/web';
+ *
+ * const runtime = await loadPHPRuntime( await getPHPLoaderModule('7.4') );
+ * const php = new PHP( runtime );
+ *
+ * php.mkdirTree('/www');
+ * php.writeFile('/www/index.php', '<?php echo "Hi from PHP!"; ');
+ *
+ * const server = new PHPRequestHandler(php, {
+ *     // PHP FS path to serve the files from:
+ *     documentRoot: '/www',
+ *
+ *     // Used to populate $_SERVER['SERVER_NAME'] etc.:
+ *     absoluteUrl: 'http://127.0.0.1'
+ * });
+ *
+ * const response = server.request({ path: '/index.php' });
+ * console.log(response.text);
+ * // "Hi from PHP!"
+ * ```
+ */
+export declare class PHPRequestHandler {
     #private;
     rewriteRules: RewriteRule[];
     /**
@@ -33,16 +86,80 @@ export declare class PHPRequestHandler implements RequestHandler {
      * @param  config - Request Handler configuration.
      */
     constructor(php: BasePHP, config?: PHPRequestHandlerConfiguration);
-    /** @inheritDoc */
+    /**
+     * Converts a path to an absolute URL based at the PHPRequestHandler
+     * root.
+     *
+     * @param  path The server path to convert to an absolute URL.
+     * @returns The absolute URL.
+     */
     pathToInternalUrl(path: string): string;
-    /** @inheritDoc */
+    /**
+     * Converts an absolute URL based at the PHPRequestHandler to a relative path
+     * without the server pathname and scope.
+     *
+     * @param  internalUrl An absolute URL based at the PHPRequestHandler root.
+     * @returns The relative path.
+     */
     internalUrlToPath(internalUrl: string): string;
     get isRequestRunning(): boolean;
-    /** @inheritDoc */
+    /**
+     * The absolute URL of this PHPRequestHandler instance.
+     */
     get absoluteUrl(): string;
-    /** @inheritDoc */
+    /**
+     * The directory in the PHP filesystem where the server will look
+     * for the files to serve. Default: `/var/www`.
+     */
     get documentRoot(): string;
-    /** @inheritDoc */
+    /**
+     * Serves the request – either by serving a static file, or by
+     * dispatching it to the PHP runtime.
+     *
+     * 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.request({
+     * 	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
+     * const output = await php.request({
+     * 	method: 'GET',
+     * 	url: '/index.php',
+     * 	headers: {
+     * 		'X-foo': 'bar',
+     * 	},
+     * 	body: {
+     * 		foo: 'bar',
+     * 	},
+     * });
+     * console.log(output.stdout); // "Hello world!"
+     * ```
+     *
+     * @param  request - PHP Request data.
+     */
     request(request: PHPRequest): Promise<PHPResponse>;
 }
 /**

package/lib/rotate-php-runtime.d.ts

@@ -1,6 +1,7 @@
 import { BasePHP } from './base-php';
 export interface RotateOptions<T extends BasePHP> {
     php: T;
+    cwd: string;
     recreateRuntime: () => Promise<number> | number;
     maxRequests: number;
 }
@@ -20,4 +21,4 @@ export interface RotateOptions<T extends BasePHP> {
  *
  * @return cleanup function to restore
  */
-export declare function rotatePHPRuntime<T extends BasePHP>({ php, recreateRuntime, maxRequests, }: RotateOptions<T>): () => void;
+export declare function rotatePHPRuntime<T extends BasePHP>({ php, cwd, recreateRuntime, maxRequests, }: RotateOptions<T>): () => void;

package/lib/universal-php.d.ts

@@ -36,137 +36,17 @@ export type PHPEvent = PHPRequestEndEvent | PHPRequestErrorEvent | PHPRuntimeIni
  * A callback function that handles PHP events.
  */
 export type PHPEventListener = (event: PHPEvent) => void;
-/**
- * Handles HTTP requests using PHP runtime as a backend.
- *
- * @public
- * @example Use PHPRequestHandler implicitly with a new PHP instance:
- * ```js
- * import { PHP } from '../../../web/src/index.ts';
- *
- * const php = await PHP.load( '7.4', {
- *     requestHandler: {
- *         // PHP FS path to serve the files from:
- *         documentRoot: '/www',
- *
- *         // Used to populate $_SERVER['SERVER_NAME'] etc.:
- *         absoluteUrl: 'http://127.0.0.1'
- *     }
- * } );
- *
- * php.mkdirTree('/www');
- * php.writeFile('/www/index.php', '<?php echo "Hi from PHP!"; ');
- *
- * const response = await php.request({ path: '/index.php' });
- * console.log(response.text);
- * // "Hi from PHP!"
- * ```
- *
- * @example Explicitly create a PHPRequestHandler instance and run a PHP script:
- * ```js
- * import {
- *   loadPHPRuntime,
- *   PHP,
- *   PHPRequestHandler,
- *   getPHPLoaderModule,
- * } from '@php-wasm/web';
- *
- * const runtime = await loadPHPRuntime( await getPHPLoaderModule('7.4') );
- * const php = new PHP( runtime );
- *
- * php.mkdirTree('/www');
- * php.writeFile('/www/index.php', '<?php echo "Hi from PHP!"; ');
- *
- * const server = new PHPRequestHandler(php, {
- *     // PHP FS path to serve the files from:
- *     documentRoot: '/www',
- *
- *     // Used to populate $_SERVER['SERVER_NAME'] etc.:
- *     absoluteUrl: 'http://127.0.0.1'
- * });
- *
- * const response = server.request({ path: '/index.php' });
- * console.log(response.text);
- * // "Hi from PHP!"
- * ```
- */
-export interface RequestHandler {
-    /**
-     * Serves the request – either by serving a static file, or by
-     * dispatching it to the PHP runtime.
-     *
-     * 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.request({
-     * 	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
-     * const output = await php.request({
-     * 	method: 'GET',
-     * 	url: '/index.php',
-     * 	headers: {
-     * 		'X-foo': 'bar',
-     * 	},
-     * 	body: {
-     * 		foo: 'bar',
-     * 	},
-     * });
-     * console.log(output.stdout); // "Hello world!"
-     * ```
-     *
-     * @param  request - PHP Request data.
-     */
-    request(request: PHPRequest, maxRedirects?: number): Promise<PHPResponse>;
-    /**
-     * Converts a path to an absolute URL based at the PHPRequestHandler
-     * root.
-     *
-     * @param  path The server path to convert to an absolute URL.
-     * @returns The absolute URL.
-     */
+export interface IsomorphicLocalPHP {
+    /** @deprecated Use PHPRequestHandler instead. */
+    request(request: PHPRequest): Promise<PHPResponse>;
+    /** @deprecated Use PHPRequestHandler instead. */
     pathToInternalUrl(path: string): string;
-    /**
-     * Converts an absolute URL based at the PHPRequestHandler to a relative path
-     * without the server pathname and scope.
-     *
-     * @param  internalUrl An absolute URL based at the PHPRequestHandler root.
-     * @returns The relative path.
-     */
+    /** @deprecated Use PHPRequestHandler instead. */
     internalUrlToPath(internalUrl: string): string;
-    /**
-     * The absolute URL of this PHPRequestHandler instance.
-     */
+    /** @deprecated Use PHPRequestHandler instead. */
     absoluteUrl: string;
-    /**
-     * The directory in the PHP filesystem where the server will look
-     * for the files to serve. Default: `/var/www`.
-     */
+    /** @deprecated Use PHPRequestHandler instead. */
     documentRoot: string;
-}
-export interface IsomorphicLocalPHP extends RequestHandler {
     /**
      * Sets the SAPI name exposed by the PHP module.
      * @param newName - The new SAPI name.
@@ -402,14 +282,6 @@ export interface IsomorphicLocalPHP extends RequestHandler {
      * @param listener Callback function to handle the message.
      */
     onMessage(listener: MessageListener): void;
-    /**
-     * Registers a handler to spawns a child process when
-     * `proc_open()`, `popen()`, `exec()`, `system()`, or `passthru()`
-     * is called.
-     *
-     * @param handler Callback function to spawn a process.
-     */
-    setSpawnHandler(handler: SpawnHandler | string): void;
 }
 export type MessageListener = (data: string) => Promise<string | Uint8Array | void> | string | void;
 interface EventEmitter {
@@ -474,6 +346,10 @@ export interface PHPRunOptions {
      * Environment variables to set for this run.
      */
     env?: Record<string, string>;
+    /**
+     * $_SERVER entries to set for this run.
+     */
+    $_SERVER?: Record<string, string>;
     /**
      * The code snippet to eval instead of a php file.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@php-wasm/universal",
-	"version": "0.6.16",
+	"version": "0.7.1",
 	"description": "PHP.wasm – emscripten bindings for PHP",
 	"repository": {
 		"type": "git",
@@ -36,7 +36,7 @@
 	"main": "./index.cjs",
 	"module": "./index.js",
 	"license": "GPL-2.0-or-later",
-	"gitHead": "1981567e7eacecbc4a18c870267c20bf489afd8f",
+	"gitHead": "ed0ec39040ab4cd69dc48a8eac157436b30f9d55",
 	"engines": {
 		"node": ">=18.18.0",
 		"npm": ">=8.11.0"

package/lib/php-browser.d.ts

@@ -1,54 +0,0 @@
-import type { PHPRequestHandler } from './php-request-handler';
-import type { PHPResponse } from './php-response';
-import { PHPRequest, RequestHandler } from './universal-php';
-export interface PHPBrowserConfiguration {
-    /**
-     * Should handle redirects internally?
-     */
-    handleRedirects?: boolean;
-    /**
-     * The maximum number of redirects to follow internally. Once
-     * exceeded, request() will return the redirecting response.
-     */
-    maxRedirects?: number;
-}
-/**
- * A fake web browser that handles PHPRequestHandler's cookies and redirects
- * internally without exposing them to the consumer.
- *
- * @public
- */
-export declare class PHPBrowser implements RequestHandler {
-    #private;
-    requestHandler: PHPRequestHandler;
-    /**
-     * @param  server - The PHP server to browse.
-     * @param  config - The browser configuration.
-     */
-    constructor(requestHandler: PHPRequestHandler, config?: PHPBrowserConfiguration);
-    /**
-     * Sends the request to the server.
-     *
-     * When cookies are present in the response, this method stores
-     * them and sends them with any subsequent requests.
-     *
-     * When a redirection is present in the response, this method
-     * follows it by discarding a response and sending a subsequent
-     * request.
-     *
-     * @param  request   - The request.
-     * @param  redirects - Internal. The number of redirects handled so far.
-     * @returns PHPRequestHandler response.
-     */
-    request(request: PHPRequest, redirects?: number): Promise<PHPResponse>;
-    /** @inheritDoc */
-    pathToInternalUrl(path: string): string;
-    /** @inheritDoc */
-    internalUrlToPath(internalUrl: string): string;
-    /** @inheritDoc */
-    get absoluteUrl(): string;
-    /** @inheritDoc */
-    get documentRoot(): string;
-    setCookies(cookies: string[]): void;
-    serializeCookies(): string;
-}