@wp-playground/client 3.1.25 → 3.1.27

package/index.d.ts

@@ -1852,139 +1852,94 @@ export type AllPHPVersion = SupportedPHPVersion | LegacyPHPVersion;
 export interface FileTree extends Record<string, Uint8Array | string | FileTree> {
 }
 /**
- * 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 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
@@ -1992,15 +1947,23 @@ 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;
 }
+/**
+ * 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>;
+}
 export type WithAPIState = {
 	/**
 	 * Resolves to true when the remote API is ready for
@@ -5266,7 +5229,7 @@ export type BuiltInPHPWebExtensionName = "intl";
  * External sources are supported in JSPI runtimes only. Asyncify support is
  * limited to bundled extensions shipped with this package.
  */
-export type RuntimePHPWebExtensionSource = PHPExtensionInstallOptions;
+export type RuntimePHPWebExtensionSource = Omit<ResolvedInstallOptions, "phpVersion">;
 /**
  * PHP extension request accepted by `loadWebRuntime()`.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-playground/client",
-  "version": "3.1.25",
+  "version": "3.1.27",
   "description": "WordPress Playground client",
   "repository": {
     "type": "git",
@@ -38,7 +38,7 @@
   "main": "./index.cjs",
   "module": "./index.js",
   "types": "index.d.ts",
-  "gitHead": "e662afdd9a3b6dad3e194ad34d80421c539b7386",
+  "gitHead": "fd598fe315657fd276d7e14d5251c1127d495766",
   "engines": {
     "node": ">=20.10.0",
     "npm": ">=10.2.3"