@php-wasm/universal 3.1.20 → 3.1.22

package/lib/index.d.ts

@@ -21,8 +21,9 @@ export type { MaxPhpInstancesError, PHPFactory, PHPFactoryOptions, ProcessManage
 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 { AllPHPVersions, isLegacyPHPVersion, LatestSupportedPHPVersion, LegacyPHPVersions, SupportedPHPVersions, SupportedPHPVersionsList, } from './supported-php-versions';
+export type { AllPHPVersion, LegacyPHPVersion, SupportedPHPVersion, } from './supported-php-versions';
+export { createLegacyPhpIniPreRunStep, LEGACY_PHP_INI_CONTENT, LEGACY_PHP_INI_PATH, } from './legacy-php-ini';
 export { PHP, __private__dont__use, PHPExecutionFailureError } from './php';
 export type { MountHandler, UnmountFunction } from './php';
 export { loadPHPRuntime, popLoadedRuntime } from './load-php-runtime';
@@ -34,6 +35,8 @@ export type { FileNotFoundGetActionCallback, FileNotFoundToInternalRedirect, Fil
 export { rotatePHPRuntime } from './rotate-php-runtime';
 export { writeFiles } from './write-files';
 export type { FileTree } from './write-files';
+export { withResolvedPHPExtensions, installPHPExtensionFilesSync, PHP_EXTENSIONS_DIR, resolvePHPExtension, } from './load-extension';
+export type { InstallPHPExtensionFilesOptions, PHPExtensionExtraFiles, PHPExtensionIniDirective, PHPExtensionInstallOptions, ResolvedPHPExtension, PHPExtensionManifest, PHPExtensionManifestArtifact, PHPExtensionSource, PHPWasmAsyncMode, ResolvePHPExtensionOptions, } from './load-extension';
 export { DEFAULT_BASE_URL, ensurePathPrefix, removePathPrefix, toRelativeUrl, } from './urls';
 export { isExitCode } from './is-exit-code';
 export { proxyFileSystem, isPathToSharedFS } from './proxy-file-system';

package/lib/legacy-php-ini.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Pre-boot php.ini content for legacy PHP builds (currently 5.2).
+ *
+ * Why pre-create a php.ini before the SAPI starts:
+ *
+ * - ini_get_all() crashes on legacy PHP WASM (null function pointer in
+ *   the Asyncify instrumentation) so we disable it via
+ *   `disable_functions`, which PHP only reads during module startup.
+ * - OPcache's shared-memory allocator fails in our WASM environment,
+ *   so opcache must be disabled before php_module_startup runs.
+ *
+ * Both settings are processed by php_module_startup before PHP reads
+ * any user code, so setting them at runtime via `ini_set()` is too
+ * late. The Emscripten preRun hook below writes the ini file before
+ * PHP.initializeRuntime invokes __wasm_call_ctors, which in turn
+ * invokes wasm_sapi_module_startup → php_module_startup.
+ *
+ * PHP.initializeRuntime will skip writing its own default php.ini
+ * when the file already exists.
+ */
+export declare const LEGACY_PHP_INI_PATH = "/internal/shared/php.ini";
+export declare const LEGACY_PHP_INI_CONTENT: string;
+/**
+ * Returns an Emscripten preRun callback that writes
+ * {@link LEGACY_PHP_INI_CONTENT} to {@link LEGACY_PHP_INI_PATH}.
+ */
+export declare function createLegacyPhpIniPreRunStep(): (module: {
+    FS: {
+        mkdirTree: (path: string) => void;
+        writeFile: (path: string, content: string) => void;
+    };
+}) => void;

package/lib/load-extension.d.ts

@@ -0,0 +1,227 @@
+import type { Emscripten } from './emscripten-types';
+import type { EmscriptenOptions } from './load-php-runtime';
+import type { FileTree } from './write-files';
+/**
+ * Default VFS directory where PHP.wasm stages extension `.so` files and
+ * writes their per-extension ini files.
+ */
+export declare const PHP_EXTENSIONS_DIR = "/internal/shared/extensions";
+/**
+ * Async mode used by the PHP.wasm build that will load the extension.
+ *
+ * Extension side modules must be compiled for the same mode as the main PHP
+ * module.
+ */
+export type PHPWasmAsyncMode = 'jspi' | 'asyncify';
+/**
+ * The php.ini directive used to load the extension.
+ *
+ * Use `extension` for regular PHP extensions and `zend_extension` for Zend
+ * extensions such as Xdebug.
+ */
+export type PHPExtensionIniDirective = 'extension' | 'zend_extension';
+/**
+ * One compiled extension artifact in a manifest.
+ */
+export interface PHPExtensionManifestArtifact {
+    /**
+     * PHP major/minor version the artifact was compiled against, e.g. `8.4`.
+     */
+    phpVersion: string;
+    /**
+     * PHP.wasm async mode the artifact was compiled against.
+     */
+    asyncMode: PHPWasmAsyncMode;
+    /**
+     * Relative to the manifest URL/base URL, or an absolute URL.
+     */
+    file: string;
+    /**
+     * Optional SHA-256 checksum for the fetched `.so` artifact.
+     */
+    sha256?: string;
+}
+/**
+ * Extension artifact manifest.
+ *
+ * A manifest lets callers publish a matrix of `.so` files and lets
+ * `resolvePHPExtension()` select the artifact that matches the current PHP
+ * version and async mode.
+ */
+export interface PHPExtensionManifest {
+    name: string;
+    version?: string;
+    mode?: 'php-extension';
+    artifacts: PHPExtensionManifestArtifact[];
+}
+/**
+ * Source for a PHP extension `.so`.
+ *
+ * Use `format: 'so'` when the caller already has bytes, `format: 'url'` for a
+ * direct artifact URL, and `format: 'manifest'` when PHP.wasm should select
+ * the right artifact from a manifest.
+ */
+export type PHPExtensionSource = {
+    format: 'so';
+    /**
+     * Required when `PHPExtensionInstallOptions.name` is not set.
+     */
+    name?: string;
+    bytes: Uint8Array | ArrayBuffer;
+    sha256?: string;
+} | {
+    format: 'url';
+    /**
+     * Optional extension name. If omitted, PHP.wasm infers the name
+     * from a `.so` filename in the URL.
+     */
+    name?: string;
+    url: string | URL;
+    sha256?: string;
+} | {
+    format: 'manifest';
+    /**
+     * URL of the extension manifest.
+     *
+     * In `@php-wasm/universal`, string values must be absolute URLs.
+     * In `@php-wasm/node`, this may also be a filesystem path or a
+     * `file:` URL; `@php-wasm/node` resolves local paths before fetching.
+     */
+    manifestUrl: string | URL;
+} | {
+    format: 'manifest';
+    manifest: PHPExtensionManifest;
+    /**
+     * Base URL used to resolve relative artifact paths in an inline
+     * manifest.
+     */
+    baseUrl?: string | URL;
+};
+/**
+ * Extra files to stage next to an extension.
+ *
+ * Use this for sidecar data files such as ICU data or native-library assets
+ * that the extension expects to find at runtime.
+ */
+export interface PHPExtensionExtraFiles {
+    /**
+     * Files are written here. Defaults to
+     * `/internal/shared/extensions/<name>-assets`.
+     */
+    targetPath?: string;
+    files: FileTree;
+}
+/**
+ * Options for staging a PHP extension before startup.
+ */
+export interface PHPExtensionInstallOptions {
+    /**
+     * The extension artifact bytes, URL, or manifest.
+     */
+    source: PHPExtensionSource;
+    /**
+     * Extension name used for staged file names and the first ini directive.
+     *
+     * This overrides a name inferred from `source`.
+     */
+    name?: string;
+    /**
+     * The directive PHP.wasm writes as the first line of the generated
+     * startup `.ini` file for this extension.
+     *
+     * Regular PHP extensions need `extension=/path/to/name.so`. Zend
+     * extensions, such as Xdebug, need `zend_extension=/path/to/name.so`.
+     * This does not edit the main `php.ini`; it controls the generated
+     * per-extension `.ini` file PHP reads while starting.
+     */
+    loadWithIniDirective?: PHPExtensionIniDirective;
+    /**
+     * Additional `key=value` lines written to the generated startup `.ini`
+     * file after the `extension=` or `zend_extension=` directive.
+     */
+    iniEntries?: Record<string, string>;
+    /**
+     * Sidecar files to write into the PHP VFS before the extension is loaded.
+     *
+     * Use this for data files or dependency assets the extension expects at
+     * runtime.
+     */
+    extraFiles?: PHPExtensionExtraFiles;
+    /**
+     * Environment variables to add to the PHP runtime before the extension is
+     * loaded.
+     */
+    env?: Record<string, string>;
+    /**
+     * VFS directory where PHP.wasm writes the extension `.so` file and its
+     * per-extension ini file. Defaults to `PHP_EXTENSIONS_DIR`.
+     */
+    extensionDir?: string;
+    /**
+     * Fetch implementation used for `format: 'url'`, `manifestUrl`, and
+     * manifest artifacts.
+     *
+     * Runtimes may provide environment-specific defaults. For example,
+     * `@php-wasm/node` provides local file support for extension manifests and
+     * artifacts.
+     */
+    fetch?: typeof fetch;
+}
+/**
+ * Options for resolving an extension before a PHP instance exists.
+ */
+export type ResolvePHPExtensionOptions = PHPExtensionInstallOptions & {
+    phpVersion: string;
+    asyncMode: PHPWasmAsyncMode;
+};
+/**
+ * Inputs used to build the staged `.so` path and per-extension ini file.
+ */
+export interface InstallPHPExtensionFilesOptions {
+    name: string;
+    soBytes: Uint8Array | ArrayBuffer;
+    loadWithIniDirective?: PHPExtensionIniDirective;
+    iniEntries?: Record<string, string>;
+    extraFiles?: PHPExtensionExtraFiles;
+    env?: Record<string, string>;
+    extensionDir?: string;
+}
+/**
+ * Fully resolved files and settings needed to install one extension.
+ *
+ * `iniPath` and `iniContent` describe the per-extension ini file PHP.wasm
+ * writes into the PHP VFS.
+ */
+export interface ResolvedPHPExtension {
+    soPath: string;
+    soBytes: Uint8Array;
+    iniPath: string;
+    iniContent: string;
+    extraFiles?: PHPExtensionExtraFiles & {
+        targetPath: string;
+    };
+    env?: Record<string, string>;
+    extensionDir: string;
+}
+/**
+ * Resolves an extension source without mutating a PHP instance.
+ *
+ * Use this from runtimes that need to fetch extension bytes and compute
+ * `iniPath`/`iniContent` before Emscripten initializes PHP.
+ */
+export declare function resolvePHPExtension(options: ResolvePHPExtensionOptions): Promise<ResolvedPHPExtension>;
+/**
+ * Adds resolved extensions to Emscripten options.
+ *
+ * The returned options install extension files during `onRuntimeInitialized`
+ * and update `PHP_INI_SCAN_DIR` before PHP startup.
+ */
+export declare function withResolvedPHPExtensions(options: EmscriptenOptions, extensions: ResolvedPHPExtension[]): EmscriptenOptions;
+/**
+ * Installs extension files through Emscripten's synchronous filesystem API.
+ *
+ * Use this while the PHP runtime is initializing and only the raw Emscripten
+ * `FS` object is available. This writes the `.so` file and generated `.ini`
+ * file to their resolved VFS paths.
+ */
+export declare function installPHPExtensionFilesSync(fs: Emscripten.RootFS, options: InstallPHPExtensionFilesOptions | ResolvedPHPExtension): ResolvedPHPExtension;

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

@@ -161,6 +161,7 @@ export type PHPRuntime = any;
 export type PHPLoaderModule = {
     dependencyFilename: string;
     dependenciesTotalSize: number;
+    phpWasmAsyncMode?: 'jspi' | 'asyncify';
     init: (jsRuntime: string, options: EmscriptenOptions) => PHPRuntime;
 };
 export type DataModule = {

package/lib/object-pool-proxy.d.ts

@@ -25,6 +25,11 @@ export type Pooled<T extends object> = Omit<Promisified<T>, typeof Symbol.dispos
  *
  * The returned proxy provides a promisified version of the original
  * interface: method calls and property accesses all return promises.
+ *
+ * Methods may return streamed response objects whose work continues
+ * after the method promise resolves. When a returned value exposes a
+ * `finished` promise, the pool keeps the instance checked out until
+ * that promise settles.
  */
 export declare function createObjectPoolProxy<T extends object>(instances: T[]): Pooled<T>;
 export {};

package/lib/php-worker.d.ts

@@ -43,7 +43,7 @@ export declare class PHPWorker implements LimitedPHPApi, AsyncDisposable {
      * the web API. It will change or even be removed without
      * a warning.
      */
-    protected __internal_getRequestHandler(): PHPRequestHandler | undefined;
+    protected __internal_getRequestHandler(): PHPRequestHandler;
     setPrimaryPHP(php: PHP): Promise<void>;
     /** @inheritDoc @php-wasm/universal!PHPRequestHandler.pathToInternalUrl  */
     pathToInternalUrl(path: string): string;
@@ -121,4 +121,6 @@ export declare class PHPWorker implements LimitedPHPApi, AsyncDisposable {
     protected dispatchEvent<Event extends PHPWorkerEvent>(event: Event): void;
     protected registerWorkerListeners(php: PHP): void;
     [Symbol.asyncDispose](): Promise<void>;
+    protected getRequestHandler(required?: true): PHPRequestHandler;
+    protected getRequestHandler(required: false): PHPRequestHandler | undefined;
 }

package/lib/proxy-file-system.d.ts

@@ -6,8 +6,20 @@ import type { PHP } from './php';
  * For example, mounting /wordpress from the parent instance into a child worker allows
  * both to access the same WordPress installation without copying the entire directory.
  *
- * The function automatically patches PROXYFS with mmap support before mounting, ensuring
- * libraries like ICU can memory-map data files through the proxied filesystem.
+ * The function automatically patches PROXYFS with mmap support before mounting on
+ * PHP 7+, so libraries like ICU can memory-map data files through the proxied
+ * filesystem.
+ *
+ * Legacy PHP (< 7) skips the mmap patch. PHP 5.x's zend_compile_file
+ * calls mmap() via zend_stream_fixup and trusts fstat() for the buffer
+ * size. When a file is pre-populated in MEMFS before PROXYFS is mounted
+ * over that path (e.g. php.ini written by preRun), fstat() can return
+ * the stale MEMFS size instead of the PROXYFS size, causing the parser
+ * to read past the real EOF and report spurious syntax errors. Without
+ * the mmap patch, Emscripten returns ENOSYS from mmap() and PHP falls
+ * back to a read-based path that handles size mismatches gracefully.
+ * PHP 7+ removed the mmap path from zend_stream_fixup entirely, so the
+ * patch is both safe and needed there (for ICU/intl).
  *
  * Mounts are registered via php.mount() so they survive runtime rotation.
  * When the replica's WASM module is hot-swapped, hotSwapPHPRuntime()

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

@@ -2,3 +2,13 @@ export declare const SupportedPHPVersions: readonly ["8.5", "8.4", "8.3", "8.2",
 export declare const LatestSupportedPHPVersion: "8.5";
 export declare const SupportedPHPVersionsList: string[];
 export type SupportedPHPVersion = (typeof SupportedPHPVersions)[number];
+export declare const LegacyPHPVersions: readonly ["5.2"];
+export type LegacyPHPVersion = (typeof LegacyPHPVersions)[number];
+/**
+ * Type guard for legacy PHP versions. Lets callers narrow a string
+ * to `LegacyPHPVersion` without the `as readonly string[]` cast that
+ * would otherwise be required to satisfy `Array.prototype.includes`.
+ */
+export declare function isLegacyPHPVersion(version: string | undefined): version is LegacyPHPVersion;
+export declare const AllPHPVersions: readonly ["8.5", "8.4", "8.3", "8.2", "8.1", "8.0", "7.4", "5.2"];
+export type AllPHPVersion = SupportedPHPVersion | LegacyPHPVersion;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@php-wasm/universal",
-  "version": "3.1.20",
+  "version": "3.1.22",
   "description": "PHP.wasm – emscripten bindings for PHP",
   "repository": {
     "type": "git",
@@ -37,17 +37,17 @@
   "module": "./index.js",
   "types": "index.d.ts",
   "license": "GPL-2.0-or-later",
-  "gitHead": "98cfca0a050ef1dacce25710d6ebdf816e80b764",
+  "gitHead": "04c986b63dd56fe74e4ed0cf04d00cae7ac050bf",
   "engines": {
     "node": ">=20.10.0",
     "npm": ">=10.2.3"
   },
   "dependencies": {
     "ini": "4.1.2",
-    "@php-wasm/logger": "3.1.20",
-    "@php-wasm/util": "3.1.20",
-    "@php-wasm/stream-compression": "3.1.20",
-    "@php-wasm/progress": "3.1.20"
+    "@php-wasm/logger": "3.1.22",
+    "@php-wasm/util": "3.1.22",
+    "@php-wasm/stream-compression": "3.1.22",
+    "@php-wasm/progress": "3.1.22"
   },
   "packageManager": "npm@10.9.2",
   "overrides": {