@php-wasm/universal 3.0.22 → 3.0.29

package/lib/fs-helpers.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="node" />
 import type { Emscripten } from './emscripten-types';
 export interface RmDirOptions {
     /**
@@ -40,7 +41,7 @@ export declare class FSHelpers {
      * @param  path - The file path to write to.
      * @param  data - The data to write to the file.
      */
-    static writeFile(FS: Emscripten.RootFS, path: string, data: string | Uint8Array): void;
+    static writeFile(FS: Emscripten.RootFS, path: string, data: string | Uint8Array | Buffer): void;
     /**
      * Removes a file from the PHP filesystem.
      *

package/lib/index.d.ts

@@ -9,8 +9,15 @@ export { HttpCookieStore } from './http-cookie-store';
 export type { IteratePhpFilesOptions as IterateFilesOptions } from './iterate-files';
 export { iteratePhpFiles as iterateFiles } from './iterate-files';
 export { writeFilesStreamToPhp } from './write-files-stream-to-php';
+export type { PHPInstanceManager, AcquiredPHP, 
+/**
+ * Backwards compatibility alias.
+ */
+AcquiredPHP as SpawnedPHP, } from './php-instance-manager';
+export { SinglePHPInstanceManager } from './single-php-instance-manager';
+export type { SinglePHPInstanceManagerOptions } from './single-php-instance-manager';
 export { PHPProcessManager } from './php-process-manager';
-export type { MaxPhpInstancesError, PHPFactory, PHPFactoryOptions, ProcessManagerOptions, SpawnedPHP, } from './php-process-manager';
+export type { MaxPhpInstancesError, PHPFactory, PHPFactoryOptions, ProcessManagerOptions, } from './php-process-manager';
 export { PHPResponse, StreamedPHPResponse } from './php-response';
 export type { PHPResponseData } from './php-response';
 export type { ErrnoError } from './rethrow-file-system-error';
@@ -18,7 +25,7 @@ export { LatestSupportedPHPVersion, SupportedPHPVersions, SupportedPHPVersionsLi
 export type { SupportedPHPVersion } from './supported-php-versions';
 export { PHP, __private__dont__use, PHPExecutionFailureError } from './php';
 export type { MountHandler, UnmountFunction } from './php';
-export { loadPHPRuntime, getLoadedRuntime } from './load-php-runtime';
+export { loadPHPRuntime, popLoadedRuntime } from './load-php-runtime';
 export type { Emscripten } from './emscripten-types';
 export type { DataModule, EmscriptenOptions, PHPLoaderModule, PHPRuntime, PHPRuntimeId, RuntimeType, } from './load-php-runtime';
 export type { PHPRequestHandlerConfiguration, RewriteRule, } from './php-request-handler';
@@ -33,3 +40,4 @@ export { proxyFileSystem, isPathToSharedFS } from './proxy-file-system';
 export { sandboxedSpawnHandlerFactory } from './sandboxed-spawn-handler-factory';
 export * from './api';
 export type { WithAPIState as WithIsReady } from './api';
+export type { Remote } from './comlink-sync';

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

@@ -122,7 +122,40 @@ import type { IncomingMessage, Server, ServerResponse } from 'http';
 export declare function loadPHPRuntime(phpLoaderModule: PHPLoaderModule, ...options: EmscriptenOptions[]): Promise<number>;
 export type RuntimeType = 'NODE' | 'WEB' | 'WORKER';
 export type PHPRuntimeId = number;
-export declare function getLoadedRuntime(id: PHPRuntimeId): PHPRuntime;
+/**
+ * Retrieves a PHP runtime by its ID and removes it from the internal registry.
+ *
+ * When you call `loadPHPRuntime()`, it creates an Emscripten-based PHP instance and
+ * stores it in a module-level Map keyed by a numeric ID. This function is the only
+ * way to retrieve that runtime object so you can actually use it.
+ *
+ * The "pop" semantic is intentional: retrieving a runtime also removes it from the
+ * registry. This prevents memory leaks since the registry would otherwise hold
+ * references to every runtime ever created. Once you pop a runtime, you own it and
+ * are responsible for its lifecycle.
+ *
+ * Typical usage flow:
+ * ```ts
+ * // 1. Load a PHP runtime (returns just the ID)
+ * const runtimeId = await loadPHPRuntime(phpLoaderModule);
+ *
+ * // 2. Pop the runtime to get the actual Emscripten module
+ * const phpRuntime = popLoadedRuntime(runtimeId);
+ *
+ * // 3. Now you can use phpRuntime to run PHP code, access the filesystem, etc.
+ * ```
+ *
+ * @param id - The numeric ID returned by `loadPHPRuntime()`.
+ * @param options.dangerouslyKeepTheRuntimeInTheMap - Test-only escape hatch. When true,
+ *        retrieves the runtime without removing it from the registry. This violates
+ *        the function's contract and only works when `process.env.TEST` is set.
+ *        Never use this in production code.
+ * @returns The PHP runtime object (an Emscripten module instance).
+ * @throws If no runtime exists with the given ID.
+ */
+export declare function popLoadedRuntime(id: PHPRuntimeId, { dangerouslyKeepTheRuntimeInTheMap, }?: {
+    dangerouslyKeepTheRuntimeInTheMap?: boolean;
+}): PHPRuntime;
 export declare const currentJsRuntime: string;
 export type PHPRuntime = any;
 export type PHPLoaderModule = {

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

@@ -0,0 +1,38 @@
+import type { PHP } from './php';
+/**
+ * Result of acquiring a PHP instance.
+ * The `reap` function should be called when done with the instance.
+ */
+export interface AcquiredPHP {
+    php: PHP;
+    /**
+     * Release the PHP instance back to the pool (for multi-instance managers)
+     * or mark it as idle (for single-instance managers).
+     */
+    reap: () => void;
+}
+/**
+ * Minimal interface for managing PHP instances.
+ *
+ * This interface allows PHPRequestHandler to work with different
+ * instance management strategies:
+ * - PHPProcessManager: Multiple PHP instances with concurrency control
+ * - SinglePHPInstanceManager: Single PHP instance for CLI contexts
+ */
+export interface PHPInstanceManager extends AsyncDisposable {
+    /**
+     * Get the primary PHP instance.
+     * This instance is persistent and never killed.
+     */
+    getPrimaryPhp(): Promise<PHP>;
+    /**
+     * Acquire a PHP instance for processing a request.
+     *
+     * @param options.considerPrimary - Whether the primary instance can be used.
+     *        Set to false for operations that would corrupt the primary (e.g., CLI commands).
+     * @returns An acquired PHP instance with a reap function.
+     */
+    acquirePHPInstance(options?: {
+        considerPrimary?: boolean;
+    }): Promise<AcquiredPHP>;
+}

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

@@ -1,4 +1,5 @@
 import type { PHP } from './php';
+import type { PHPInstanceManager, AcquiredPHP } from './php-instance-manager';
 export type PHPFactoryOptions = {
     isPrimary: boolean;
 };
@@ -28,10 +29,6 @@ export interface ProcessManagerOptions {
      */
     phpFactory?: PHPFactory;
 }
-export interface SpawnedPHP {
-    php: PHP;
-    reap: () => void;
-}
 export declare class MaxPhpInstancesError extends Error {
     constructor(limit: number);
 }
@@ -59,7 +56,7 @@ export declare class MaxPhpInstancesError extends Error {
  * requests requires extra time to spin up a few PHP instances. This is a more
  * resource-friendly tradeoff than keeping 5 idle instances at all times.
  */
-export declare class PHPProcessManager implements AsyncDisposable {
+export declare class PHPProcessManager implements PHPInstanceManager {
     private primaryPhp?;
     private primaryPhpPromise?;
     private primaryIdle;
@@ -105,7 +102,7 @@ export declare class PHPProcessManager implements AsyncDisposable {
      */
     acquirePHPInstance({ considerPrimary, }?: {
         considerPrimary?: boolean;
-    }): Promise<SpawnedPHP>;
+    }): Promise<AcquiredPHP>;
     /**
      * Initiated spawning of a new PHP instance.
      * This function is synchronous on purpose – it needs to synchronously

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

@@ -2,7 +2,7 @@ import type { PHP } from './php';
 import { PHPResponse } from './php-response';
 import type { PHPRequest } from './universal-php';
 import type { PHPFactoryOptions } from './php-process-manager';
-import { PHPProcessManager } from './php-process-manager';
+import type { PHPInstanceManager } from './php-instance-manager';
 export type RewriteRule = {
     match: RegExp;
     replacement: string;
@@ -59,28 +59,24 @@ interface BaseConfiguration {
 export type PHPRequestHandlerFactoryArgs = PHPFactoryOptions & {
     requestHandler: PHPRequestHandler;
 };
-export type PHPRequestHandlerConfiguration = BaseConfiguration & ({
+export type PHPRequestHandlerConfiguration = BaseConfiguration & {
+    cookieStore?: CookieStore | false;
     /**
-     * PHPProcessManager is required because the request handler needs
-     * to make a decision for each request.
-     *
-     * Static assets are served using the primary PHP's filesystem, even
-     * when serving 100 static files concurrently. No new PHP interpreter
-     * is ever created as there's no need for it.
-     *
-     * Dynamic PHP requests, however, require grabbing an available PHP
-     * interpreter, and that's where the PHPProcessManager comes in.
+     * Provide a single PHP instance directly.
+     * PHPRequestHandler will create a SinglePHPInstanceManager internally.
+     * This is the simplest option for CLI contexts with a single PHP instance.
+     */
+    php?: PHP;
+    /**
+     * Provide a factory function to create PHP instances.
+     * PHPRequestHandler will create a PHPProcessManager internally.
      */
-    processManager: PHPProcessManager;
-} | {
-    phpFactory: (requestHandler: PHPRequestHandlerFactoryArgs) => Promise<PHP>;
+    phpFactory?: (requestHandler: PHPRequestHandlerFactoryArgs) => Promise<PHP>;
     /**
      * The maximum number of PHP instances that can exist at
-     * the same time.
+     * the same time. Only used when phpFactory is provided.
      */
     maxPhpInstances?: number;
-}) & {
-    cookieStore?: CookieStore | false;
 };
 /**
  * Handles HTTP requests using PHP runtime as a backend.
@@ -139,7 +135,12 @@ export type PHPRequestHandlerConfiguration = BaseConfiguration & ({
 export declare class PHPRequestHandler implements AsyncDisposable {
     #private;
     rewriteRules: RewriteRule[];
-    processManager: PHPProcessManager;
+    /**
+     * The instance manager used for PHP instance lifecycle.
+     * This is either a provided instanceManager or a PHPProcessManager
+     * created from the phpFactory.
+     */
+    instanceManager: PHPInstanceManager;
     getFileNotFoundAction: FileNotFoundGetActionCallback;
     /**
      * The request handler needs to decide whether to serve a static asset or

package/lib/php.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="node" />
 import { Semaphore } from '@php-wasm/util';
 import type { Emscripten } from './emscripten-types';
 import type { ListFilesOptions, RmDirOptions } from './fs-helpers';
@@ -338,7 +339,7 @@ export declare class PHP implements Disposable {
      * @param  path - The file path to write to.
      * @param  data - The data to write to the file.
      */
-    writeFile(path: string, data: string | Uint8Array): void;
+    writeFile(path: string, data: string | Uint8Array | Buffer): void;
     /**
      * Removes a file from the PHP filesystem.
      *

package/lib/sandboxed-spawn-handler-factory.d.ts

@@ -1,4 +1,6 @@
-import type { PHPProcessManager } from './php-process-manager';
+import type { PHP } from './php';
+import type { PHPWorker } from './php-worker';
+import type { Remote } from './comlink-sync';
 /**
  * An isomorphic proc_open() handler that implements typical shell in TypeScript
  * without relying on a server runtime. It can be used in the browser and Node.js
@@ -9,4 +11,7 @@ import type { PHPProcessManager } from './php-process-manager';
  * explore bringing in an actual shell implementation or at least a proper command
  * parser.
  */
-export declare function sandboxedSpawnHandlerFactory(processManager: PHPProcessManager): any;
+export declare function sandboxedSpawnHandlerFactory(getPHPInstance?: () => Promise<{
+    php: PHP | Remote<PHPWorker>;
+    reap: () => void;
+}>): any;

package/lib/single-php-instance-manager.d.ts

@@ -0,0 +1,34 @@
+import type { PHP } from './php';
+import type { PHPInstanceManager, AcquiredPHP } from './php-instance-manager';
+export interface SinglePHPInstanceManagerOptions {
+    /**
+     * Either provide an existing PHP instance...
+     */
+    php?: PHP;
+    /**
+     * ...or a factory to create one on demand.
+     */
+    phpFactory?: () => Promise<PHP>;
+}
+/**
+ * A minimal PHP instance manager that manages a single PHP instance.
+ *
+ * Unlike PHPProcessManager, this does not maintain a pool of instances
+ * or implement concurrency control. It simply returns the same PHP
+ * instance for every request.
+ *
+ * This is suitable for CLI contexts where:
+ * - Only one PHP instance is needed
+ * - Runtime rotation is handled separately via php.enableRuntimeRotation()
+ * - Concurrency is not a concern (each worker has its own instance)
+ */
+export declare class SinglePHPInstanceManager implements PHPInstanceManager {
+    private php;
+    private phpPromise;
+    private phpFactory?;
+    private isAcquired;
+    constructor(options: SinglePHPInstanceManagerOptions);
+    getPrimaryPhp(): Promise<PHP>;
+    acquirePHPInstance(): Promise<AcquiredPHP>;
+    [Symbol.asyncDispose](): Promise<void>;
+}

package/lib/supported-php-versions.d.ts

@@ -1,4 +1,4 @@
-export declare const SupportedPHPVersions: readonly ["8.4", "8.3", "8.2", "8.1", "8.0", "7.4", "7.3", "7.2"];
-export declare const LatestSupportedPHPVersion: "8.4";
+export declare const SupportedPHPVersions: readonly ["8.5", "8.4", "8.3", "8.2", "8.1", "8.0", "7.4", "7.3", "7.2"];
+export declare const LatestSupportedPHPVersion: "8.5";
 export declare const SupportedPHPVersionsList: string[];
 export type SupportedPHPVersion = (typeof SupportedPHPVersions)[number];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@php-wasm/universal",
-  "version": "3.0.22",
+  "version": "3.0.29",
   "description": "PHP.wasm – emscripten bindings for PHP",
   "repository": {
     "type": "git",
@@ -37,18 +37,18 @@
   "module": "./index.js",
   "types": "index.d.ts",
   "license": "GPL-2.0-or-later",
-  "gitHead": "a624d1a97dc639e152d335e6a801b2fad7f6b594",
+  "gitHead": "ce450285157be874d4a164b30c0a828946c2d3ad",
   "engines": {
     "node": ">=20.18.3",
     "npm": ">=10.1.0"
   },
   "dependencies": {
     "ini": "4.1.2",
-    "@php-wasm/node-polyfills": "3.0.22",
-    "@php-wasm/logger": "3.0.22",
-    "@php-wasm/util": "3.0.22",
-    "@php-wasm/stream-compression": "3.0.22",
-    "@php-wasm/progress": "3.0.22"
+    "@php-wasm/node-polyfills": "3.0.29",
+    "@php-wasm/logger": "3.0.29",
+    "@php-wasm/util": "3.0.29",
+    "@php-wasm/stream-compression": "3.0.29",
+    "@php-wasm/progress": "3.0.29"
   },
   "packageManager": "npm@10.9.2",
   "overrides": {
@@ -56,8 +56,8 @@
     "react": "18.3.1",
     "react-dom": "18.3.1",
     "typescript": "5.4.5",
-    "@playwright/test": "1.47.1",
-    "ws": "^8.18.0",
+    "@playwright/test": "1.55.1",
+    "ws": "8.18.3",
     "tmp": "0.2.5",
     "form-data": "^4.0.4"
   },