@php-wasm/universal 3.1.21 → 3.1.22

package/lib/index.d.ts

@@ -35,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@php-wasm/universal",
-  "version": "3.1.21",
+  "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": "5864051cbf4c2a55656112d99a3f1b076bcd67cd",
+  "gitHead": "04c986b63dd56fe74e4ed0cf04d00cae7ac050bf",
   "engines": {
     "node": ">=20.10.0",
     "npm": ">=10.2.3"
   },
   "dependencies": {
     "ini": "4.1.2",
-    "@php-wasm/logger": "3.1.21",
-    "@php-wasm/util": "3.1.21",
-    "@php-wasm/stream-compression": "3.1.21",
-    "@php-wasm/progress": "3.1.21"
+    "@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": {