@php-wasm/universal 3.1.25 → 3.1.26

package/lib/index.d.ts

@@ -36,7 +36,7 @@ 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, ResolvePHPExtensionOptions, } from './load-extension';
+export type { InstallPHPExtensionFilesOptions, PHPExtensionIniDirective, ResolvedInstallOptions, ResolvedPHPExtension, PHPExtensionManifest, PHPExtensionManifestExtraFiles, PHPExtensionSource, } 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

@@ -1,145 +1,100 @@
 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";
 /**
- * The php.ini directive used to load the extension.
- *
- * Use `extension` for regular PHP extensions and `zend_extension` for Zend
- * extensions such as Xdebug.
+ * The php.ini directive used to load the extension. Use `extension` for
+ * regular PHP extensions and `zend_extension` for Zend extensions like 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;
-    /**
-     * 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. External extension artifacts are JSPI-only.
+ * Extension artifact manifest. Lets callers publish a matrix of `.so` files
+ * and lets `resolvePHPExtension()` select the artifact matching the current
+ * PHP version. External extension artifacts are JSPI-only.
  */
 export interface PHPExtensionManifest {
     name: string;
     version?: string;
     mode?: 'php-extension';
-    artifacts: PHPExtensionManifestArtifact[];
+    artifacts: Array<{
+        /** PHP major/minor version, e.g. `8.4`. */
+        phpVersion: string;
+        /** Relative to the manifest URL/base URL, or an absolute URL. */
+        sourcePath: string;
+        /** URL-backed files needed only by this artifact. */
+        extraFiles?: PHPExtensionManifestExtraFiles;
+    }>;
+    /** URL-backed files shared by every artifact in this manifest. */
+    extraFiles?: PHPExtensionManifestExtraFiles;
+}
+export interface PHPExtensionManifestExtraFiles {
+    /**
+     * Absolute VFS path where files and directories are written. When a
+     * manifest declares both top-level and per-artifact `extraFiles`, the
+     * first declared `targetPath` wins. Defaults to
+     * `<extensionDir>/<name>-assets`.
+     */
+    vfsRoot?: string;
+    nodes?: Array<{
+        /** Joined with the group's `vfsRoot` to form the final VFS path. */
+        vfsPath: string;
+        /** Defaults to "file". Only file nodes need a `sourcePath`. */
+        type?: 'file' | 'directory';
+        /** Relative to the manifest URL/base URL, or an absolute URL. */
+        sourcePath?: string;
+    }>;
 }
 /**
- * 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.
+ * Source for a PHP extension `.so`. Use `format: 'so'` when the caller 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.
+     * In `@php-wasm/universal`, must be an absolute URL. `@php-wasm/node`
+     * also accepts filesystem paths and `file:` URLs.
      */
     manifestUrl: string | URL;
 } | {
     format: 'manifest';
     manifest: PHPExtensionManifest;
-    /**
-     * Base URL used to resolve relative artifact paths in an inline
-     * manifest.
-     */
+    /** Base URL for resolving relative artifact paths. */
     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.
-     */
+export type DataToResolvePhpExtension = ResolvedInstallOptions;
+export interface ResolvedInstallOptions {
+    /** PHP major/minor version the active runtime is initializing for. */
+    phpVersion: string;
     source: PHPExtensionSource;
-    /**
-     * Extension name used for staged file names and the first ini directive.
-     *
-     * This overrides a name inferred from `source`.
-     */
+    /** Overrides the 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.
+     * The first directive of the generated startup `.ini` file. Regular
+     * extensions need `extension=...`; Zend extensions like Xdebug need
+     * `zend_extension=...`.
      */
     loadWithIniDirective?: PHPExtensionIniDirective;
-    /**
-     * Additional `key=value` lines written to the generated startup `.ini`
-     * file after the `extension=` or `zend_extension=` directive.
-     */
+    /** Additional `key=value` lines for the generated startup `.ini` file. */
     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.
-     */
+    extraFiles?: ResolvedExtraFiles;
+    /** Environment variables added before the extension is loaded. */
     env?: Record<string, string>;
     /**
      * VFS directory where PHP.wasm writes the extension `.so` file and its
@@ -147,69 +102,98 @@ export interface PHPExtensionInstallOptions {
      */
     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 implementation used for URL and manifest sources. Runtimes may
+     * provide environment-specific defaults; for example, `@php-wasm/node`
+     * adds local file support.
      */
     fetch?: typeof fetch;
 }
 /**
- * Options for resolving an extension before a PHP instance exists.
+ * Fully resolved files and settings needed to install one extension. Produced
+ * by `resolvePHPExtension`; consumed by `withResolvedPHPExtensions` and
+ * `installPHPExtensionFilesSync`.
  */
-export type ResolvePHPExtensionOptions = PHPExtensionInstallOptions & {
-    phpVersion: string;
-};
+export interface ResolvedPHPExtension {
+    /** Absolute VFS path the `.so` file is staged at. */
+    soPath: string;
+    /** Compiled extension bytes to write at `soPath`. */
+    soBytes: Uint8Array;
+    /** Absolute VFS path the generated per-extension ini file is staged at. */
+    iniPath: string;
+    /**
+     * Contents of the generated per-extension ini file. The first line is the
+     * `extension=` or `zend_extension=` directive; remaining lines are the
+     * caller-supplied `iniEntries`.
+     */
+    iniContent: string;
+    /** Sidecar files staged alongside the extension. Optional. */
+    extraFiles?: ResolvedExtraFiles;
+    /** Environment variables added before PHP startup. */
+    env?: Record<string, string>;
+    /** VFS directory the `.so` and ini file live in. */
+    extensionDir: string;
+}
 /**
- * Inputs used to build the staged `.so` path and per-extension ini file.
+ * Sidecar files to stage next to an extension. Use this for data files or
+ * native-library assets the extension expects at runtime. All paths are
+ * absolute VFS paths.
+ */
+export interface ResolvedExtraFiles {
+    /** Absolute VFS paths to create as empty directories. */
+    directories?: string[];
+    /** Map of absolute VFS paths to file contents. */
+    files: Record<string, Uint8Array | string>;
+}
+/**
+ * Inputs used to build the staged `.so` path and per-extension ini file when
+ * `installPHPExtensionFilesSync` is called with raw install options instead of
+ * a `ResolvedPHPExtension`.
  */
 export interface InstallPHPExtensionFilesOptions {
+    /** Extension name used for staged file names and the ini directive. */
     name: string;
+    /** Compiled extension bytes. */
     soBytes: Uint8Array | ArrayBuffer;
+    /**
+     * The first directive of the generated startup `.ini` file. Regular
+     * extensions need `extension=...`; Zend extensions like Xdebug need
+     * `zend_extension=...`.
+     */
     loadWithIniDirective?: PHPExtensionIniDirective;
+    /** Additional `key=value` lines for the generated startup `.ini` file. */
     iniEntries?: Record<string, string>;
-    extraFiles?: PHPExtensionExtraFiles;
+    /** Sidecar files to write into the PHP VFS before the extension is loaded. */
+    extraFiles?: ResolvedExtraFiles;
+    /** Environment variables added 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;
 }
 /**
- * Fully resolved files and settings needed to install one extension.
+ * 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.
  *
- * `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.
+ * Manifest-declared extra files are joined with their group's `vfsRoot` so the
+ * returned `extraFiles` always uses absolute VFS paths.
  *
- * Use this from runtimes that need to fetch extension bytes and compute
- * `iniPath`/`iniContent` before Emscripten initializes PHP.
+ * TODO: Remove the remote manifest.json resolution and move it to Blueprints
+ *       where the paths can be validated and downloads scheduled using the
+ *       same code paths as we do for all other paths and URLs.
  */
-export declare function resolvePHPExtension(options: ResolvePHPExtensionOptions): Promise<ResolvedPHPExtension>;
+export declare function resolvePHPExtension(options: DataToResolvePhpExtension): 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.
+ * 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.
+ * `FS` object is available.
  */
 export declare function installPHPExtensionFilesSync(fs: Emscripten.RootFS, options: InstallPHPExtensionFilesOptions | ResolvedPHPExtension): ResolvedPHPExtension;

package/package.json

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

package/php-extension-manifest-schema-validator.d.ts

@@ -0,0 +1,10 @@
+type ValidationError = {
+	instancePath?: string;
+	message?: string;
+	params?: Record<string, unknown>;
+};
+type ValidateFunction = ((data: unknown) => boolean) & {
+	errors?: ValidationError[] | null;
+};
+declare const validatePHPExtensionManifest: ValidateFunction;
+export default validatePHPExtensionManifest;