@php-wasm/universal - npm Package Compare versions

Comparing version 3.1.21 to 3.1.22

lib/load-extension.d.ts

+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;

lib/index.d.ts

@@ -38,2 +38,4 @@ export type { MessageListener, PHPOutput, PHPRunOptions, UniversalPHP, PHPEvent, PHPEventListener, HTTPMethod, PHPRequest, PHPRequestHeaders, SpawnHandler, } from './universal-php';
 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';
@@ -40,0 +42,0 @@ export { isExitCode } from './is-exit-code';

lib/load-php-runtime.d.ts

@@ -164,2 +164,3 @@ /// <reference types="node" />
     dependenciesTotalSize: number;
+    phpWasmAsyncMode?: 'jspi' | 'asyncify';
     init: (jsRuntime: string, options: EmscriptenOptions) => PHPRuntime;
@@ -166,0 +167,0 @@ };

lib/object-pool-proxy.d.ts

@@ -28,4 +28,9 @@ /**
  * 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 {};

lib/php-worker.d.ts

@@ -46,3 +46,3 @@ import type { EmscriptenDownloadMonitor } from '@php-wasm/progress';
      */
-    protected __internal_getRequestHandler(): PHPRequestHandler | undefined;
+    protected __internal_getRequestHandler(): PHPRequestHandler;
     setPrimaryPHP(php: PHP): Promise<void>;
@@ -125,2 +125,4 @@ /** @inheritDoc @php-wasm/universal!PHPRequestHandler.pathToInternalUrl  */
     [Symbol.asyncDispose](): Promise<void>;
+    protected getRequestHandler(required?: true): PHPRequestHandler;
+    protected getRequestHandler(required: false): PHPRequestHandler | undefined;
 }

package.json

 {
   "name": "@php-wasm/universal",
-  "version": "3.1.21",
+  "version": "3.1.22",
   "description": "PHP.wasm – emscripten bindings for PHP",
@@ -40,3 +40,3 @@ "repository": {
   "license": "GPL-2.0-or-later",
-  "gitHead": "5864051cbf4c2a55656112d99a3f1b076bcd67cd",
+  "gitHead": "04c986b63dd56fe74e4ed0cf04d00cae7ac050bf",
   "engines": {
@@ -48,6 +48,6 @@ "node": ">=20.10.0",
     "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"
   },
@@ -54,0 +54,0 @@ "packageManager": "npm@10.9.2",

New alerts

Network access

Supply chain risk

This module accesses the network.

Found 1 instance in 1 package

Uses eval

Supply chain risk

Package uses dynamic code execution (e.g., eval()), which is a dangerous practice. This can prevent the code from running in certain environments and increases the risk that the code may contain exploits or malicious behavior.

Found 1 instance in 1 package

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 2 instances in 1 package

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Found 1 instance in 1 package

Fixed alerts

Uses eval

Supply chain risk

Package uses dynamic code execution (e.g., eval()), which is a dangerous practice. This can prevent the code from running in certain environments and increases the risk that the code may contain exploits or malicious behavior.

Found 1 instance in 1 package

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 2 instances in 1 package

AI-detected potential code anomaly

Supply chain risk

AI has identified unusual behaviors that may pose a security risk.

Found 1 instance in 1 package

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

1232462

6.78%

Number of package files

49

2.08%

Lines of code

8942

5.65%

Number of lines in readme file

67

6600%

Number of low supply chain risk alerts

21

-4.55%

Worsened metrics

Number of medium supply chain risk alerts

21

950%

Dependency changes

• + Added

  @php-wasm/logger@3.1.22
  (transitive)

• + Added

  @php-wasm/progress@3.1.22
  (transitive)

• + Added

  @php-wasm/stream-compression@3.1.22
  (transitive)

• + Added

  @php-wasm/util@3.1.22
  (transitive)

• - Removed

  @php-wasm/logger@3.1.21
  (transitive)

• - Removed

  @php-wasm/progress@3.1.21
  (transitive)

• - Removed

  @php-wasm/stream-compression@3.1.21
  (transitive)

• - Removed

  @php-wasm/util@3.1.21
  (transitive)

• Updated

  @php-wasm/logger@3.1.22

• Updated

  @php-wasm/progress@3.1.22

• Updated

  @php-wasm/stream-compression@3.1.22

• Updated

  @php-wasm/util@3.1.22