@php-wasm/universal 0.9.19 → 0.9.20

package/lib/php.d.ts

@@ -0,0 +1,314 @@
+import { PHPResponse } from './php-response';
+import type { PHPRuntimeId } from './load-php-runtime';
+import { MessageListener, PHPRequest, PHPRequestHeaders, PHPRunOptions, SpawnHandler, PHPEventListener, PHPEvent } from './universal-php';
+import { RmDirOptions, ListFilesOptions } from './fs-helpers';
+import { Semaphore } from '../../../util/src/index.ts';
+import { PHPRequestHandler } from './php-request-handler';
+import { Emscripten } from './emscripten-types';
+export declare const __private__dont__use: unique symbol;
+export declare class PHPExecutionFailureError extends Error {
+    response: PHPResponse;
+    source: 'request' | 'php-wasm';
+    constructor(message: string, response: PHPResponse, source: 'request' | 'php-wasm');
+}
+export type UnmountFunction = (() => Promise<any>) | (() => any);
+export type MountHandler = (php: PHP, FS: Emscripten.RootFS, vfsMountPoint: string) => UnmountFunction | Promise<UnmountFunction>;
+export declare const PHP_INI_PATH = "/internal/shared/php.ini";
+/**
+ * An environment-agnostic wrapper around the Emscripten PHP runtime
+ * that universals the super low-level API and provides a more convenient
+ * higher-level API.
+ *
+ * It exposes a minimal set of methods to run PHP scripts and to
+ * interact with the PHP filesystem.
+ */
+export declare class PHP implements Disposable {
+    #private;
+    protected [__private__dont__use]: any;
+    requestHandler?: PHPRequestHandler;
+    /**
+     * An exclusive lock that prevent multiple requests from running at
+     * the same time.
+     */
+    semaphore: Semaphore;
+    /**
+     * Initializes a PHP runtime.
+     *
+     * @internal
+     * @param  PHPRuntime - Optional. PHP Runtime ID as initialized by loadPHPRuntime.
+     * @param  requestHandlerOptions - Optional. Options for the PHPRequestHandler. If undefined, no request handler will be initialized.
+     */
+    constructor(PHPRuntimeId?: PHPRuntimeId);
+    /**
+     * Adds an event listener for a PHP event.
+     * @param eventType - The type of event to listen for.
+     * @param listener - The listener function to be called when the event is triggered.
+     */
+    addEventListener(eventType: PHPEvent['type'], listener: PHPEventListener): void;
+    /**
+     * Removes an event listener for a PHP event.
+     * @param eventType - The type of event to remove the listener from.
+     * @param listener - The listener function to be removed.
+     */
+    removeEventListener(eventType: PHPEvent['type'], listener: PHPEventListener): void;
+    dispatchEvent<Event extends PHPEvent>(event: Event): void;
+    /**
+     * Listens to message sent by the PHP code.
+     *
+     * To dispatch messages, call:
+     *
+     *     post_message_to_js(string $data)
+     *
+     *     Arguments:
+     *         $data (string) – Data to pass to JavaScript.
+     *
+     * @example
+     *
+     * ```ts
+     * const php = await PHP.load('8.0');
+     *
+     * php.onMessage(
+     *     // The data is always passed as a string
+     *     function (data: string) {
+     *         // Let's decode and log the data:
+     *         console.log(JSON.parse(data));
+     *     }
+     * );
+     *
+     * // Now that we have a listener in place, let's
+     * // dispatch a message:
+     * await php.run({
+     *     code: `<?php
+     *         post_message_to_js(
+     *             json_encode([
+     *                 'post_id' => '15',
+     *                 'post_title' => 'This is a blog post!'
+     *             ])
+     *         ));
+     *     `,
+     * });
+     * ```
+     *
+     * @param listener Callback function to handle the message.
+     */
+    onMessage(listener: MessageListener): void;
+    setSpawnHandler(handler: SpawnHandler | string): Promise<void>;
+    /** @deprecated Use PHPRequestHandler instead. */
+    get absoluteUrl(): string;
+    /** @deprecated Use PHPRequestHandler instead. */
+    get documentRoot(): string;
+    /** @deprecated Use PHPRequestHandler instead. */
+    pathToInternalUrl(path: string): string;
+    /** @deprecated Use PHPRequestHandler instead. */
+    internalUrlToPath(internalUrl: string): string;
+    initializeRuntime(runtimeId: PHPRuntimeId): void;
+    /** @inheritDoc */
+    setSapiName(newName: string): Promise<void>;
+    /**
+     * Changes the current working directory in the PHP filesystem.
+     * This is the directory that will be used as the base for relative paths.
+     * For example, if the current working directory is `/root/php`, and the
+     * path is `data`, the absolute path will be `/root/php/data`.
+     *
+     * @param  path - The new working directory.
+     */
+    chdir(path: string): void;
+    /**
+     * Do not use. Use new PHPRequestHandler() instead.
+     * @deprecated
+     */
+    request(request: PHPRequest): Promise<PHPResponse>;
+    /**
+     * Runs PHP code.
+     *
+     * This low-level method directly interacts with the WebAssembly
+     * PHP interpreter.
+     *
+     * Every time you call run(), it prepares the PHP
+     * environment and:
+     *
+     * * Resets the internal PHP state
+     * * Populates superglobals ($_SERVER, $_GET, etc.)
+     * * Handles file uploads
+     * * Populates input streams (stdin, argv, etc.)
+     * * Sets the current working directory
+     *
+     * You can use run() in two primary modes:
+     *
+     * ### Code snippet mode
+     *
+     * In this mode, you pass a string containing PHP code to run.
+     *
+     * ```ts
+     * const result = await php.run({
+     * 	code: `<?php echo "Hello world!";`
+     * });
+     * // result.text === "Hello world!"
+     * ```
+     *
+     * In this mode, information like __DIR__ or __FILE__ isn't very
+     * useful because the code is not associated with any file.
+     *
+     * Under the hood, the PHP snippet is passed to the `zend_eval_string`
+     * C function.
+     *
+     * ### File mode
+     *
+     * In the file mode, you pass a scriptPath and PHP executes a file
+     * found at a that path:
+     *
+     * ```ts
+     * php.writeFile(
+     * 	"/www/index.php",
+     * 	`<?php echo "Hello world!";"`
+     * );
+     * const result = await php.run({
+     * 	scriptPath: "/www/index.php"
+     * });
+     * // result.text === "Hello world!"
+     * ```
+     *
+     * In this mode, you can rely on path-related information like __DIR__
+     * or __FILE__.
+     *
+     * Under the hood, the PHP file is executed with the `php_execute_script`
+     * C function.
+     *
+     * The `run()` method cannot be used in conjunction with `cli()`.
+     *
+     * @example
+     * ```js
+     * const result = await php.run(`<?php
+     *  $fp = fopen('php://stderr', 'w');
+     *  fwrite($fp, "Hello, world!");
+     * `);
+     * // result.errors === "Hello, world!"
+     * ```
+     *
+     * @param  options - PHP runtime options.
+     */
+    run(request: PHPRunOptions): Promise<PHPResponse>;
+    /**
+     * Defines a constant in the PHP runtime.
+     * @param key - The name of the constant.
+     * @param value - The value of the constant.
+     */
+    defineConstant(key: string, value: string | boolean | number | null): void;
+    /**
+     * Recursively creates a directory with the given path in the PHP filesystem.
+     * For example, if the path is `/root/php/data`, and `/root` already exists,
+     * it will create the directories `/root/php` and `/root/php/data`.
+     *
+     * @param  path - The directory path to create.
+     */
+    mkdir(path: string): void;
+    /**
+     * @deprecated Use mkdir instead.
+     */
+    mkdirTree(path: string): void;
+    /**
+     * Reads a file from the PHP filesystem and returns it as a string.
+     *
+     * @throws {@link @php-wasm/universal:ErrnoError} – If the file doesn't exist.
+     * @param  path - The file path to read.
+     * @returns The file contents.
+     */
+    readFileAsText(path: string): string;
+    /**
+     * Reads a file from the PHP filesystem and returns it as an array buffer.
+     *
+     * @throws {@link @php-wasm/universal:ErrnoError} – If the file doesn't exist.
+     * @param  path - The file path to read.
+     * @returns The file contents.
+     */
+    readFileAsBuffer(path: string): Uint8Array;
+    /**
+     * Overwrites data in a file in the PHP filesystem.
+     * Creates a new file if one doesn't exist yet.
+     *
+     * @param  path - The file path to write to.
+     * @param  data - The data to write to the file.
+     */
+    writeFile(path: string, data: string | Uint8Array): void;
+    /**
+     * Removes a file from the PHP filesystem.
+     *
+     * @throws {@link @php-wasm/universal:ErrnoError} – If the file doesn't exist.
+     * @param  path - The file path to remove.
+     */
+    unlink(path: string): void;
+    /**
+     * Moves a file or directory in the PHP filesystem to a
+     * new location.
+     *
+     * @param oldPath The path to rename.
+     * @param newPath The new path.
+     */
+    mv(fromPath: string, toPath: string): void;
+    /**
+     * Removes a directory from the PHP filesystem.
+     *
+     * @param path The directory path to remove.
+     * @param options Options for the removal.
+     */
+    rmdir(path: string, options?: RmDirOptions): void;
+    /**
+     * Lists the files and directories in the given directory.
+     *
+     * @param  path - The directory path to list.
+     * @param  options - Options for the listing.
+     * @returns The list of files and directories in the given directory.
+     */
+    listFiles(path: string, options?: ListFilesOptions): string[];
+    /**
+     * Checks if a directory exists in the PHP filesystem.
+     *
+     * @param  path – The path to check.
+     * @returns True if the path is a directory, false otherwise.
+     */
+    isDir(path: string): boolean;
+    /**
+     * Checks if a file (or a directory) exists in the PHP filesystem.
+     *
+     * @param  path - The file path to check.
+     * @returns True if the file exists, false otherwise.
+     */
+    fileExists(path: string): boolean;
+    /**
+     * Hot-swaps the PHP runtime for a new one without
+     * interrupting the operations of this PHP instance.
+     *
+     * @param runtime
+     * @param cwd. Internal, the VFS path to recreate in the new runtime.
+     *             This arg is temporary and will be removed once BasePHP
+     *             is fully decoupled from the request handler and
+     *             accepts a constructor-level cwd argument.
+     */
+    hotSwapPHPRuntime(runtime: number, cwd?: string): void;
+    /**
+     * Mounts a filesystem to a given path in the PHP filesystem.
+     *
+     * @param  virtualFSPath - Where to mount it in the PHP virtual filesystem.
+     * @param  mountHandler - The mount handler to use.
+     * @return Unmount function to unmount the filesystem.
+     */
+    mount(virtualFSPath: string, mountHandler: MountHandler): Promise<UnmountFunction>;
+    /**
+     * Starts a PHP CLI session with given arguments.
+     *
+     * This method can only be used when PHP was compiled with the CLI SAPI
+     * and it cannot be used in conjunction with `run()`.
+     *
+     * Once this method finishes running, the PHP instance is no
+     * longer usable and should be discarded. This is because PHP
+     * internally cleans up all the resources and calls exit().
+     *
+     * @param  argv - The arguments to pass to the CLI.
+     * @returns The exit code of the CLI session.
+     */
+    cli(argv: string[]): Promise<number>;
+    setSkipShebang(shouldSkip: boolean): void;
+    exit(code?: number): void;
+    [Symbol.dispose](): void;
+}
+export declare function normalizeHeaders(headers: PHPRequestHeaders): PHPRequestHeaders;

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

@@ -0,0 +1,7 @@
+import { PHP } from './php';
+/**
+ * Proxy specific paths to the parent's MEMFS instance.
+ * This is useful for sharing the WordPress installation
+ * between the parent and child processes.
+ */
+export declare function proxyFileSystem(sourceOfTruth: PHP, replica: PHP, paths: string[]): void;

package/lib/rethrow-file-system-error.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Emscripten's filesystem-related Exception.
+ *
+ * @see https://emscripten.org/docs/api_reference/Filesystem-API.html
+ * @see https://github.com/emscripten-core/emscripten/blob/main/system/lib/libc/musl/arch/emscripten/bits/errno.h
+ * @see https://github.com/emscripten-core/emscripten/blob/38eedc630f17094b3202fd48ac0c2c585dbea31e/system/include/wasi/api.h#L336
+ */
+export interface ErrnoError extends Error {
+    node?: any;
+    errno: number;
+    message: string;
+}
+/**
+ * @see https://github.com/emscripten-core/emscripten/blob/38eedc630f17094b3202fd48ac0c2c585dbea31e/system/include/wasi/api.h#L336
+ */
+export declare const FileErrorCodes: any;
+export declare function getEmscriptenFsError(e: any): any;
+export declare function rethrowFileSystemError(messagePrefix?: string): (target: any, methodName: string, descriptor: PropertyDescriptor) => void;

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

@@ -0,0 +1,24 @@
+import { PHP } from './php';
+export interface RotateOptions {
+    php: PHP;
+    cwd: string;
+    recreateRuntime: () => Promise<number> | number;
+    maxRequests: number;
+}
+/**
+ * Listens to PHP events and swaps the internal PHP Runtime for a fresh one
+ * after a certain number of run() calls (which are responsible for handling
+ * HTTP requests).
+ *
+ * Why? Because PHP and PHP extension have a memory leak. Each request leaves
+ * the memory a bit more fragmented and with a bit less available space than
+ * before. Eventually, new allocations start failing.
+ *
+ * Rotating the PHP instance may seem like a workaround, but it's actually
+ * what PHP-FPM does natively:
+ *
+ * https://www.php.net/manual/en/install.fpm.configuration.php#pm.max-tasks
+ *
+ * @return cleanup function to restore
+ */
+export declare function rotatePHPRuntime({ php, cwd, recreateRuntime, maxRequests, }: RotateOptions): () => void;

package/lib/stream-read-file-from-php.d.ts

@@ -0,0 +1,5 @@
+import { UniversalPHP } from './universal-php';
+/**
+ * Reads a file from PHP filesystem using a stream.
+ */
+export declare function streamReadFileFromPHP(php: UniversalPHP, path: string): ReadableStream<any>;

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

@@ -0,0 +1,7 @@
+export type SupportedPHPExtension = 'iconv' | 'mbstring' | 'xml-bundle' | 'gd';
+export declare const SupportedPHPExtensionsList: string[];
+export declare const SupportedPHPExtensionBundles: {
+    'kitchen-sink': string[];
+    light: never[];
+};
+export type SupportedPHPExtensionBundle = 'kitchen-sink' | 'light';

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

@@ -0,0 +1,4 @@
+export declare const SupportedPHPVersions: readonly ["8.3", "8.2", "8.1", "8.0", "7.4", "7.3", "7.2", "7.1", "7.0"];
+export declare const LatestSupportedPHPVersion: "8.3";
+export declare const SupportedPHPVersionsList: string[];
+export type SupportedPHPVersion = (typeof SupportedPHPVersions)[number];

package/lib/universal-php.d.ts

@@ -0,0 +1,121 @@
+import { Remote } from 'comlink';
+import { LimitedPHPApi } from './php-worker';
+/**
+ * Represents an event related to the PHP request.
+ */
+export interface PHPRequestEndEvent {
+    type: 'request.end';
+}
+/**
+ * Represents an error event related to the PHP request.
+ */
+export interface PHPRequestErrorEvent {
+    type: 'request.error';
+    error: Error;
+    source?: 'request' | 'php-wasm';
+}
+/**
+ * Represents a PHP runtime initialization event.
+ */
+export interface PHPRuntimeInitializedEvent {
+    type: 'runtime.initialized';
+}
+/**
+ * Represents a PHP runtime destruction event.
+ */
+export interface PHPRuntimeBeforeDestroyEvent {
+    type: 'runtime.beforedestroy';
+}
+/**
+ * Represents an event related to the PHP instance.
+ * This is intentionally not an extension of CustomEvent
+ * to make it isomorphic between different JavaScript runtimes.
+ */
+export type PHPEvent = PHPRequestEndEvent | PHPRequestErrorEvent | PHPRuntimeInitializedEvent | PHPRuntimeBeforeDestroyEvent;
+/**
+ * A callback function that handles PHP events.
+ */
+export type PHPEventListener = (event: PHPEvent) => void;
+export type UniversalPHP = LimitedPHPApi | Remote<LimitedPHPApi>;
+export type MessageListener = (data: string) => Promise<string | Uint8Array | void> | string | void;
+interface EventEmitter {
+    on(event: string, listener: (...args: any[]) => void): this;
+    emit(event: string, ...args: any[]): boolean;
+}
+type ChildProcess = EventEmitter & {
+    stdout: EventEmitter;
+    stderr: EventEmitter;
+};
+export type SpawnHandler = (command: string, args: string[]) => ChildProcess;
+export type HTTPMethod = 'GET' | 'POST' | 'HEAD' | 'OPTIONS' | 'PATCH' | 'PUT' | 'DELETE';
+export type PHPRequestHeaders = Record<string, string>;
+export interface PHPRequest {
+    /**
+     * Request method. Default: `GET`.
+     */
+    method?: HTTPMethod;
+    /**
+     * Request path or absolute URL.
+     */
+    url: string;
+    /**
+     * Request headers.
+     */
+    headers?: PHPRequestHeaders;
+    /**
+     * Request body.
+     * If an object is given, the request will be encoded as multipart
+     * and sent with a `multipart/form-data` header.
+     */
+    body?: string | Uint8Array | Record<string, string | Uint8Array | File>;
+}
+export interface PHPRunOptions {
+    /**
+     * Request path following the domain:port part.
+     */
+    relativeUri?: string;
+    /**
+     * Path of the .php file to execute.
+     */
+    scriptPath?: string;
+    /**
+     * Request protocol.
+     */
+    protocol?: string;
+    /**
+     * Request method. Default: `GET`.
+     */
+    method?: HTTPMethod;
+    /**
+     * Request headers.
+     */
+    headers?: PHPRequestHeaders;
+    /**
+     * Request body.
+     */
+    body?: string | Uint8Array;
+    /**
+     * Environment variables to set for this run.
+     */
+    env?: Record<string, string>;
+    /**
+     * $_SERVER entries to set for this run.
+     */
+    $_SERVER?: Record<string, string>;
+    /**
+     * The code snippet to eval instead of a php file.
+     */
+    code?: string;
+}
+/**
+ * Output of the PHP.wasm runtime.
+ */
+export interface PHPOutput {
+    /** Exit code of the PHP process. 0 means success, 1 and 2 mean error. */
+    exitCode: number;
+    /** Stdout data */
+    stdout: ArrayBuffer;
+    /** Stderr lines */
+    stderr: string[];
+}
+export {};

package/lib/urls.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The default base used to convert a path into the URL object.
+ */
+export declare const DEFAULT_BASE_URL = "http://example.com";
+/**
+ * Returns a string representing the path, query, and
+ * fragment of the given URL.
+ *
+ * @example
+ * ```js
+ * const url = new URL('http://example.com/foo/bar?baz=qux#quux');
+ * toRelativeUrl(url); // '/foo/bar?baz=qux#quux'
+ * ```
+ *
+ * @param  url The URL.
+ * @returns The path, query, and fragment.
+ */
+export declare function toRelativeUrl(url: URL): string;
+/**
+ * Removes the given prefix from the given path.
+ *
+ * @example
+ * ```js
+ * removePathPrefix('/foo/bar', '/foo'); // '/bar'
+ * removePathPrefix('/bar', '/foo'); // '/bar'
+ * ```
+ *
+ * @param  path   The path to remove the prefix from.
+ * @param  prefix The prefix to remove.
+ * @returns Path with the prefix removed.
+ */
+export declare function removePathPrefix(path: string, prefix: string): string;
+/**
+ * Ensures the given path has the given prefix.
+ *
+ * @example
+ * ```js
+ * ensurePathPrefix('/bar', '/foo'); // '/foo/bar'
+ * ensurePathPrefix('/foo/bar', '/foo'); // '/foo/bar'
+ * ```
+ *
+ * @param  path
+ * @param  prefix
+ * @returns Path with the prefix added.
+ */
+export declare function ensurePathPrefix(path: string, prefix: string): string;

package/lib/wasm-error-reporting.d.ts

@@ -0,0 +1,26 @@
+type Runtime = {
+    wasmExports: Record<string, unknown>;
+    lastAsyncifyStackSource?: Error;
+};
+export declare class UnhandledRejectionsTarget extends EventTarget {
+    listenersCount: number;
+    addEventListener(type: unknown, callback: unknown): void;
+    removeEventListener(type: unknown, callback: unknown): void;
+    hasListeners(): boolean;
+}
+/**
+ * Creates Asyncify errors listener.
+ *
+ * Emscripten turns Asyncify errors into unhandled rejections by
+ * throwing them outside of the context of the original function call.
+ *
+ * With this listener, we can catch and rethrow them in a proper context,
+ * or at least log them in a more readable way.
+ *
+ * @param runtime
+ */
+export declare function improveWASMErrorReporting(runtime: Runtime): UnhandledRejectionsTarget;
+export declare function getFunctionsMaybeMissingFromAsyncify(): string[];
+export declare function clarifyErrorMessage(crypticError: Error, asyncifyStack?: string): string;
+export declare function showCriticalErrorBox(message: string): void;
+export {};

package/lib/write-files-stream-to-php.d.ts

@@ -0,0 +1,5 @@
+import { UniversalPHP } from './universal-php';
+/**
+ * Writes streamed files to PHP filesystem.
+ */
+export declare function writeFilesStreamToPhp(php: UniversalPHP, root: string): WritableStream<File>;

package/lib/write-files.d.ts

@@ -0,0 +1,28 @@
+import { UniversalPHP } from './universal-php';
+export interface WriteFilesOptions {
+    /**
+     * Whether to wipe out the contents of the
+     * root directory before writing the new files.
+     */
+    rmRoot?: boolean;
+}
+export interface FileTree extends Record<string, Uint8Array | string | FileTree> {
+}
+/**
+ * Writes multiple files to a specified directory in the Playground
+ * filesystem.
+ *
+ * @example ```ts
+ * await writeFiles(php, '/test', {
+ * 	'file.txt': 'file',
+ * 	'sub/file.txt': 'file',
+ * 	'sub1/sub2/file.txt': 'file',
+ * });
+ * ```
+ *
+ * @param php
+ * @param root
+ * @param newFiles
+ * @param options
+ */
+export declare function writeFiles(php: UniversalPHP, root: string, newFiles: FileTree, { rmRoot }?: WriteFilesOptions): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@php-wasm/universal",
-  "version": "0.9.19",
+  "version": "0.9.20",
   "description": "PHP.wasm – emscripten bindings for PHP",
   "repository": {
     "type": "git",
@@ -37,7 +37,7 @@
   "module": "./index.js",
   "types": "index.d.ts",
   "license": "GPL-2.0-or-later",
-  "gitHead": "aafbbcdc4b0644885bd55d0ed67381952f0b16b6",
+  "gitHead": "f619fcb719128d247bec296b9339aff52101e948",
   "engines": {
     "node": ">=18.18.0",
     "npm": ">=8.11.0"
@@ -45,10 +45,10 @@
   "dependencies": {
     "comlink": "^4.4.1",
     "ini": "4.1.2",
-    "@php-wasm/node-polyfills": "0.9.19",
-    "@php-wasm/logger": "0.9.19",
-    "@php-wasm/util": "0.9.19",
-    "@php-wasm/stream-compression": "0.9.19",
-    "@php-wasm/progress": "0.9.19"
+    "@php-wasm/node-polyfills": "0.9.20",
+    "@php-wasm/logger": "0.9.20",
+    "@php-wasm/util": "0.9.20",
+    "@php-wasm/stream-compression": "0.9.20",
+    "@php-wasm/progress": "0.9.20"
   }
 }