@php-wasm/universal 1.1.2 → 1.1.4

package/lib/api.d.ts

@@ -0,0 +1,18 @@
+import * as Comlink from 'comlink';
+import type { NodeEndpoint } from 'comlink/dist/esm/node-adapter';
+export type WithAPIState = {
+    /**
+     * Resolves to true when the remote API is ready for
+     * Comlink communication, but not necessarily fully initialized yet.
+     */
+    isConnected: () => Promise<void>;
+    /**
+     * Resolves to true when the remote API is declares it's
+     * fully loaded and ready to be used.
+     */
+    isReady: () => Promise<void>;
+};
+export type RemoteAPI<T> = Comlink.Remote<T> & WithAPIState;
+export declare function consumeAPI<APIType>(remote: Worker | Window | NodeEndpoint, context?: undefined | EventTarget): RemoteAPI<APIType>;
+export type PublicAPI<Methods, PipedAPI = unknown> = RemoteAPI<Methods & PipedAPI>;
+export declare function exposeAPI<Methods, PipedAPI>(apiMethods?: Methods, pipedApi?: PipedAPI, targetWorker?: NodeEndpoint): [() => void, (e: Error) => void, PublicAPI<Methods, PipedAPI>];

package/lib/index.d.ts

@@ -10,12 +10,12 @@ export { iteratePhpFiles as iterateFiles } from './iterate-files';
 export { writeFilesStreamToPhp } from './write-files-stream-to-php';
 export { PHPProcessManager } from './php-process-manager';
 export type { MaxPhpInstancesError, PHPFactory, PHPFactoryOptions, ProcessManagerOptions, SpawnedPHP, } from './php-process-manager';
-export { PHPResponse } from './php-response';
+export { PHPResponse, StreamedPHPResponse } from './php-response';
 export type { PHPResponseData } from './php-response';
 export type { ErrnoError } from './rethrow-file-system-error';
 export { LatestSupportedPHPVersion, SupportedPHPVersions, SupportedPHPVersionsList, } from './supported-php-versions';
 export type { SupportedPHPVersion } from './supported-php-versions';
-export { PHP, __private__dont__use } from './php';
+export { PHP, __private__dont__use, PHPExecutionFailureError } from './php';
 export type { MountHandler, UnmountFunction } from './php';
 export { loadPHPRuntime, getLoadedRuntime } from './load-php-runtime';
 export type { Emscripten } from './emscripten-types';
@@ -27,5 +27,7 @@ export { rotatePHPRuntime } from './rotate-php-runtime';
 export { writeFiles } from './write-files';
 export type { FileTree } from './write-files';
 export { DEFAULT_BASE_URL, ensurePathPrefix, removePathPrefix, toRelativeUrl, } from './urls';
-export { isExitCodeZero } from './is-exit-code-zero';
+export { isExitCode } from './is-exit-code';
 export { proxyFileSystem } from './proxy-file-system';
+export * from './api';
+export type { WithAPIState as WithIsReady } from './api';

package/lib/is-exit-code.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Check if the Emscripten-thrown error is an exit code 0 error.
+ *
+ * @param e The error to check
+ * @returns True if the error appears to represent an exit code or status
+ */
+export declare function isExitCode(e: any): e is {
+    exitCode: number;
+};

package/lib/php-process-manager.d.ts

@@ -61,6 +61,7 @@ export declare class MaxPhpInstancesError extends Error {
  */
 export declare class PHPProcessManager implements AsyncDisposable {
     private primaryPhp?;
+    private primaryPhpPromise?;
     private primaryIdle;
     private nextInstance;
     /**
@@ -88,10 +89,23 @@ export declare class PHPProcessManager implements AsyncDisposable {
      * instance, or a newly spawned PHP instance – depending on the resource
      * availability.
      *
+     * @param considerPrimary - Whether to consider the primary PHP instance.
+     *                          It matters because PHP.cli() sets the SAPI to CLI and
+     *                          kills the entire process after it finishes running,
+     *                          making the primary PHP instance non-reusable for
+     *                          subsequent .run() calls. This is fine for one-off
+     *                          child PHP instances, but not for the primary PHP
+     *                          that's meant to continue working for the entire duration
+     *                          of the ProcessManager lifetime. Therefore, we don't
+     *                          consider the primary PHP instance by default unless
+     *                          the caller explicitly requests it.
+     *
      * @throws {MaxPhpInstancesError} when the maximum number of PHP instances is reached
      *                                and the waiting timeout is exceeded.
      */
-    acquirePHPInstance(): Promise<SpawnedPHP>;
+    acquirePHPInstance({ considerPrimary, }?: {
+        considerPrimary?: boolean;
+    }): Promise<SpawnedPHP>;
     /**
      * Initiated spawning of a new PHP instance.
      * This function is synchronous on purpose – it needs to synchronously

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

@@ -136,7 +136,7 @@ export type PHPRequestHandlerConfiguration = BaseConfiguration & ({
  * // "Hi from PHP!"
  * ```
  */
-export declare class PHPRequestHandler {
+export declare class PHPRequestHandler implements AsyncDisposable {
     #private;
     rewriteRules: RewriteRule[];
     processManager: PHPProcessManager;
@@ -228,6 +228,7 @@ export declare class PHPRequestHandler {
      * @param  request - PHP Request data.
      */
     request(request: PHPRequest): Promise<PHPResponse>;
+    [Symbol.asyncDispose](): Promise<void>;
 }
 /**
  * Applies the given rewrite rules to the given path.

package/lib/php-response.d.ts

@@ -7,7 +7,7 @@ export interface PHPResponseData {
      * Response body. Contains the output from `echo`,
      * `print`, inline HTML etc.
      */
-    readonly bytes: ArrayBuffer;
+    readonly bytes: Uint8Array;
     /**
      * Stderr contents, if any.
      */
@@ -22,6 +22,56 @@ export interface PHPResponseData {
      */
     readonly httpStatusCode: number;
 }
+export declare class StreamedPHPResponse {
+    /**
+     * Response headers.
+     */
+    private readonly headersStream;
+    /**
+     * Response body. Contains the output from `echo`,
+     * `print`, inline HTML etc.
+     */
+    readonly stdout: ReadableStream<Uint8Array>;
+    /**
+     * Stderr contents, if any.
+     */
+    readonly stderr: ReadableStream<Uint8Array>;
+    /**
+     * The exit code of the script. `0` is a success, anything
+     * else is an error.
+     */
+    readonly exitCode: Promise<number>;
+    private parsedHeaders;
+    private cachedStdoutText;
+    private cachedStderrText;
+    constructor(headers: ReadableStream<Uint8Array>, stdout: ReadableStream<Uint8Array>, stderr: ReadableStream<Uint8Array>, exitCode: Promise<number>);
+    /**
+     * True if the response is successful (HTTP status code 200-399),
+     * false otherwise.
+     */
+    ok(): Promise<boolean>;
+    /**
+     * Resolves when the response has finished processing – either successfully or not.
+     */
+    get finished(): Promise<void>;
+    /**
+     * Resolves once HTTP headers are available.
+     */
+    get headers(): Promise<Record<string, string[]>>;
+    /**
+     * Resolves once HTTP status code is available.
+     */
+    get httpStatusCode(): Promise<number>;
+    /**
+     * Exposes the stdout bytes as they're produced by the PHP instance
+     */
+    get stdoutText(): Promise<string>;
+    /**
+     * Exposes the stderr bytes as they're produced by the PHP instance
+     */
+    get stderrText(): Promise<string>;
+    private getParsedHeaders;
+}
 /**
  * PHP response. Body is an `ArrayBuffer` because it can
  * contain binary data.
@@ -33,16 +83,17 @@ export declare class PHPResponse implements PHPResponseData {
     /** @inheritDoc */
     readonly headers: Record<string, string[]>;
     /** @inheritDoc */
-    readonly bytes: ArrayBuffer;
+    readonly bytes: Uint8Array;
     /** @inheritDoc */
     readonly errors: string;
     /** @inheritDoc */
     readonly exitCode: number;
     /** @inheritDoc */
     readonly httpStatusCode: number;
-    constructor(httpStatusCode: number, headers: Record<string, string[]>, body: ArrayBuffer, errors?: string, exitCode?: number);
+    constructor(httpStatusCode: number, headers: Record<string, string[]>, body: Uint8Array, errors?: string, exitCode?: number);
     static forHttpCode(httpStatusCode: number, text?: string): PHPResponse;
     static fromRawData(data: PHPResponseData): PHPResponse;
+    static fromStreamedResponse(streamedResponse: StreamedPHPResponse): Promise<PHPResponse>;
     toRawData(): PHPResponseData;
     /**
      * Response body as JSON.

package/lib/php-worker.d.ts

@@ -11,7 +11,7 @@ export type LimitedPHPApi = Pick<PHP, 'request' | 'defineConstant' | 'addEventLi
 /**
  * A PHP client that can be used to run PHP code in the browser.
  */
-export declare class PHPWorker implements LimitedPHPApi {
+export declare class PHPWorker implements LimitedPHPApi, AsyncDisposable {
     /** @inheritDoc @php-wasm/universal!RequestHandler.absoluteUrl  */
     absoluteUrl: string;
     /** @inheritDoc @php-wasm/universal!RequestHandler.documentRoot  */
@@ -76,4 +76,5 @@ export declare class PHPWorker implements LimitedPHPApi {
     addEventListener(eventType: PHPEvent['type'], listener: PHPEventListener): void;
     /** @inheritDoc @php-wasm/universal!/PHP.removeEventListener */
     removeEventListener(eventType: PHPEvent['type'], listener: PHPEventListener): void;
+    [Symbol.asyncDispose](): Promise<void>;
 }

package/lib/php.d.ts

@@ -1,4 +1,4 @@
-import { PHPResponse } from './php-response';
+import { PHPResponse, StreamedPHPResponse } from './php-response';
 import type { PHPRuntimeId } from './load-php-runtime';
 import type { MessageListener, PHPRequest, PHPRequestHeaders, PHPRunOptions, SpawnHandler, PHPEventListener, PHPEvent } from './universal-php';
 import type { RmDirOptions, ListFilesOptions } from './fs-helpers';
@@ -179,16 +179,111 @@ export declare class PHP implements Disposable {
      *
      * @example
      * ```js
-     * const result = await php.run(`<?php
-     *  $fp = fopen('php://stderr', 'w');
-     *  fwrite($fp, "Hello, world!");
-     * `);
+     * const result = await php.run({
+     * 	code: `<?php
+     * 		$fp = fopen('php://stderr', 'w');
+     * 		fwrite($fp, "Hello, world!");
+     * 	`
+     * });
      * // result.errors === "Hello, world!"
      * ```
      *
-     * @param  options - PHP runtime options.
+     * @deprecated Use stream() instead.
+     * @param  request - PHP runtime options.
      */
     run(request: PHPRunOptions): Promise<PHPResponse>;
+    /**
+     * Runs PHP code and returns a StreamedPHPResponse object that can be used to
+     * process the output incrementally.
+     *
+     * This low-level method directly interacts with the WebAssembly
+     * PHP interpreter and provides streaming capabilities for processing
+     * PHP output as it becomes available.
+     *
+     * Every time you call stream(), 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 stream() in two primary modes:
+     *
+     * ### Code snippet mode
+     *
+     * In this mode, you pass a string containing PHP code to run.
+     *
+     * ```ts
+     * const streamedResponse = await php.stream({
+     * 	code: `<?php echo "Hello world!";`
+     * });
+     * // Process output incrementally
+     * for await (const chunk of streamedResponse.text) {
+     * 	console.log(chunk);
+     * }
+     * ```
+     *
+     * 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 that path:
+     *
+     * ```ts
+     * php.writeFile(
+     * 	"/www/index.php",
+     * 	`<?php echo "Hello world!";"`
+     * );
+     * const streamedResponse = await php.stream({
+     * 	scriptPath: "/www/index.php"
+     * });
+     * // Process output incrementally
+     * for await (const chunk of streamedResponse.text) {
+     * 	console.log(chunk);
+     * }
+     * ```
+     *
+     * 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 `stream()` method cannot be used in conjunction with `cli()`.
+     *
+     * @example
+     * ```js
+     * const streamedResponse = await php.stream({
+     * 	code: `<?php
+     * 		for ($i = 0; $i < 5; $i++) {
+     * 			echo "Line $i\n";
+     * 			flush();
+     * 		}
+     * 	`
+     * });
+     *
+     * // Process output as it becomes available
+     * for await (const chunk of streamedResponse.text) {
+     * 	console.log('Received:', chunk);
+     * }
+     *
+     * // Get the final exit code
+     * const exitCode = await streamedResponse.exitCode;
+     * console.log('Exit code:', exitCode);
+     * ```
+     *
+     * @see run() – a synchronous version of this method.
+     * @param request - PHP runtime options.
+     * @returns A StreamedPHPResponse object.
+     */
+    runStream(request: PHPRunOptions): Promise<StreamedPHPResponse>;
     /**
      * Defines a constant in the PHP runtime.
      * @param key - The name of the constant.
@@ -340,7 +435,9 @@ export declare class PHP implements Disposable {
      * @param  argv - The arguments to pass to the CLI.
      * @returns The exit code of the CLI session.
      */
-    cli(argv: string[]): Promise<number>;
+    cli(argv: string[], options?: {
+        env?: Record<string, string>;
+    }): Promise<StreamedPHPResponse>;
     setSkipShebang(shouldSkip: boolean): void;
     exit(code?: number): void;
     [Symbol.dispose](): void;

package/lib/wasm-error-reporting.d.ts

@@ -4,8 +4,8 @@ type Runtime = {
 };
 export declare class UnhandledRejectionsTarget extends EventTarget {
     listenersCount: number;
-    addEventListener(type: unknown, callback: unknown): void;
-    removeEventListener(type: unknown, callback: unknown): void;
+    addEventListener(type: unknown, callback: unknown, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener(type: unknown, callback: unknown, options?: boolean | EventListenerOptions): void;
     hasListeners(): boolean;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@php-wasm/universal",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "PHP.wasm – emscripten bindings for PHP",
   "repository": {
     "type": "git",
@@ -37,19 +37,19 @@
   "module": "./index.js",
   "types": "index.d.ts",
   "license": "GPL-2.0-or-later",
-  "gitHead": "59c2db1ec41efa10ffa01e6e1ea7ac6e78bc693e",
+  "gitHead": "ed646326d99ba84bad911d65b6634265f508f073",
   "engines": {
     "node": ">=20.18.3",
     "npm": ">=10.1.0"
   },
   "dependencies": {
-    "comlink": "^4.4.1",
+    "comlink": "^4.4.2",
     "ini": "4.1.2",
-    "@php-wasm/node-polyfills": "1.1.2",
-    "@php-wasm/logger": "1.1.2",
-    "@php-wasm/util": "1.1.2",
-    "@php-wasm/stream-compression": "1.1.2",
-    "@php-wasm/progress": "1.1.2"
+    "@php-wasm/node-polyfills": "1.1.4",
+    "@php-wasm/logger": "1.1.4",
+    "@php-wasm/util": "1.1.4",
+    "@php-wasm/stream-compression": "1.1.4",
+    "@php-wasm/progress": "1.1.4"
   },
   "overrides": {
     "rollup": "^4.34.6",

package/lib/is-exit-code-zero.d.ts

@@ -1,7 +0,0 @@
-/**
- * Check if the Emscripten-thrown error is an exit code 0 error.
- *
- * @param e The error to check
- * @returns True if the error is an exit code 0 error
- */
-export declare function isExitCodeZero(e: any): boolean;