@php-wasm/universal 0.9.15 → 0.9.16

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

@@ -1,150 +0,0 @@
-/**
- * Loads the PHP runtime with the given arguments and data dependencies.
- *
- * This function handles the entire PHP initialization pipeline. In particular, it:
- *
- * * Instantiates the Emscripten PHP module
- * * Wires it together with the data dependencies and loads them
- * * Ensures is all happens in a correct order
- * * Waits until the entire loading sequence is finished
- *
- * Basic usage:
- *
- * ```js
- *  const phpLoaderModule = await getPHPLoaderModule("7.4");
- *  const php = await loadPHPRuntime( phpLoaderModule );
- *  console.log(php.run(`<?php echo "Hello, world!"; `));
- *  // { stdout: ArrayBuffer containing the string "Hello, world!", stderr: [''], exitCode: 0 }
- * ```
- *
- * **The PHP loader module:**
- *
- * In the basic usage example, `phpLoaderModule` is **not** a vanilla Emscripten module. Instead,
- * it's an ESM module that wraps the regular Emscripten output and adds some
- * extra functionality. It's generated by the Dockerfile shipped with this repo.
- * Here's the API it provides:
- *
- * ```js
- * // php.wasm size in bytes:
- * export const dependenciesTotalSize = 5644199;
- *
- * // php.wasm filename:
- * export const dependencyFilename = 'php.wasm';
- *
- * // Run Emscripten's generated module:
- * export default function(jsEnv, emscriptenModuleArgs) {}
- * ```
- *
- * **PHP Filesystem:**
- *
- * Once initialized, the PHP has its own filesystem separate from the project
- * files. It's provided by [Emscripten and uses its FS library](https://emscripten.org/docs/api_reference/Filesystem-API.html).
- *
- * The API exposed to you via the PHP class is succinct and abstracts
- * certain unintuitive parts of low-level filesystem interactions.
- *
- * Here's how to use it:
- *
- * ```js
- * // Recursively create a /var/www directory
- * php.mkdirTree('/var/www');
- *
- * console.log(php.fileExists('/var/www/file.txt'));
- * // false
- *
- * php.writeFile('/var/www/file.txt', 'Hello from the filesystem!');
- *
- * console.log(php.fileExists('/var/www/file.txt'));
- * // true
- *
- * console.log(php.readFile('/var/www/file.txt'));
- * // "Hello from the filesystem!
- *
- * // Delete the file:
- * php.unlink('/var/www/file.txt');
- * ```
- *
- * For more details consult the PHP class directly.
- *
- * **Data dependencies:**
- *
- * Using existing PHP packages by manually recreating them file-by-file would
- * be quite inconvenient. Fortunately, Emscripten provides a "data dependencies"
- * feature.
- *
- * Data dependencies consist of a `dependency.data` file and a `dependency.js` loader and
- * can be packaged with the [file_packager.py tool]( https://emscripten.org/docs/porting/files/packaging_files.html#packaging-using-the-file-packager-tool).
- * This project requires wrapping the Emscripten-generated `dependency.js` file in an ES
- * module as follows:
- *
- * 1. Prepend `export default function(emscriptenPHPModule) {'; `
- * 2. Prepend `export const dependencyFilename = '<DATA FILE NAME>'; `
- * 3. Prepend `export const dependenciesTotalSize = <DATA FILE SIZE>;`
- * 4. Append `}`
- *
- * Be sure to use the `--export-name="emscriptenPHPModule"` file_packager.py option.
- *
- * You want the final output to look as follows:
- *
- * ```js
- * export const dependenciesTotalSize = 5644199;
- * export const dependencyFilename = 'dependency.data';
- * export default function(emscriptenPHPModule) {
- *    // Emscripten-generated code:
- *    var Module = typeof emscriptenPHPModule !== 'undefined' ? emscriptenPHPModule : {};
- *    // ... the rest of it ...
- * }
- * ```
- *
- * Such a constructions enables loading the `dependency.js` as an ES Module using
- * `import("/dependency.js")`.
- *
- * Once it's ready, you can load PHP and your data dependencies as follows:
- *
- * ```js
- *  const [phpLoaderModule, wordPressLoaderModule] = await Promise.all([
- *    getPHPLoaderModule("7.4"),
- *    import("/wp.js")
- *  ]);
- *  const php = await loadPHPRuntime(phpLoaderModule, {}, [wordPressLoaderModule]);
- * ```
- *
- * @public
- * @param  phpLoaderModule         - The ESM-wrapped Emscripten module. Consult the Dockerfile for the build process.
- * @param  phpModuleArgs           - The Emscripten module arguments, see https://emscripten.org/docs/api_reference/module.html#affecting-execution.
- * @returns Loaded runtime id.
- */
-export declare function loadPHPRuntime(phpLoaderModule: PHPLoaderModule, phpModuleArgs?: EmscriptenOptions): Promise<number>;
-export type RuntimeType = 'NODE' | 'WEB' | 'WORKER';
-export type PHPRuntimeId = number;
-export declare function getLoadedRuntime(id: PHPRuntimeId): PHPRuntime;
-export declare const currentJsRuntime: string;
-export type PHPRuntime = any;
-export type PHPLoaderModule = {
-    dependencyFilename: string;
-    dependenciesTotalSize: number;
-    init: (jsRuntime: string, options: EmscriptenOptions) => PHPRuntime;
-};
-export type DataModule = {
-    dependencyFilename: string;
-    dependenciesTotalSize: number;
-    default: (phpRuntime: PHPRuntime) => void;
-};
-export type EmscriptenOptions = {
-    onAbort?: (message: string) => void;
-    /**
-     * Set to true for debugging tricky WebAssembly errors.
-     */
-    debug?: boolean;
-    ENV?: Record<string, string>;
-    locateFile?: (path: string) => string;
-    noInitialRun?: boolean;
-    print?: (message: string) => void;
-    printErr?: (message: string) => void;
-    quit?: (status: number, toThrow: any) => void;
-    onRuntimeInitialized?: () => void;
-    monitorRunDependencies?: (left: number) => void;
-    onMessage?: (listener: EmscriptenMessageListener) => void;
-    instantiateWasm?: (info: WebAssembly.Imports, receiveInstance: (instance: WebAssembly.Instance, module: WebAssembly.Module) => void) => void;
-} & Record<string, any>;
-export type EmscriptenMessageListener = (type: string, data: string) => void;

package/lib/php-process-manager.d.ts

@@ -1,104 +0,0 @@
-import { PHP } from './php';
-export type PHPFactoryOptions = {
-    isPrimary: boolean;
-};
-export type PHPFactory = (options: PHPFactoryOptions) => Promise<PHP>;
-export interface ProcessManagerOptions {
-    /**
-     * The maximum number of PHP instances that can exist at
-     * the same time.
-     */
-    maxPhpInstances?: number;
-    /**
-     * The number of milliseconds to wait for a PHP instance when
-     * we have reached the maximum number of PHP instances and
-     * cannot spawn a new one. If the timeout is reached, we assume
-     * all the PHP instances are deadlocked and a throw MaxPhpInstancesError.
-     *
-     * Default: 5000
-     */
-    timeout?: number;
-    /**
-     * The primary PHP instance that's never killed. This instance
-     * contains the reference filesystem used by all other PHP instances.
-     */
-    primaryPhp?: PHP;
-    /**
-     * A factory function used for spawning new PHP instances.
-     */
-    phpFactory?: PHPFactory;
-}
-export interface SpawnedPHP {
-    php: PHP;
-    reap: () => void;
-}
-export declare class MaxPhpInstancesError extends Error {
-    constructor(limit: number);
-}
-/**
- * A PHP Process manager.
- *
- * Maintains:
- * * A single "primary" PHP instance that's never killed – it contains the
- *   reference filesystem used by all other PHP instances.
- * * A pool of disposable PHP instances that are spawned to handle a single
- *   request and reaped immediately after.
- *
- * When a new request comes in, PHPProcessManager yields the idle instance to handle it,
- * and immediately starts initializing a new idle instance. In other words, for n concurrent
- * requests, there are at most n+1 PHP instances running at the same time.
- *
- * A slight nuance is that the first idle instance is not initialized until the first
- * concurrent request comes in. This is because many use-cases won't involve parallel
- * requests and, for those, we can avoid eagerly spinning up a second PHP instance.
- *
- * This strategy is inspired by Cowboy, an Erlang HTTP server. Handling a single extra
- * request can happen immediately, while handling multiple extra requests requires
- * extra time to spin up a few PHP instances. This is a more resource-friendly tradeoff
- * than keeping 5 idle instances at all times.
- */
-export declare class PHPProcessManager implements AsyncDisposable {
-    private primaryPhp?;
-    private primaryIdle;
-    private nextInstance;
-    /**
-     * All spawned PHP instances, including the primary PHP instance.
-     * Used for bookkeeping and reaping all instances on dispose.
-     */
-    private allInstances;
-    private phpFactory?;
-    private maxPhpInstances;
-    private semaphore;
-    constructor(options?: ProcessManagerOptions);
-    /**
-     * Get the primary PHP instance.
-     *
-     * If the primary PHP instance is not set, it will be spawned
-     * using the provided phpFactory.
-     *
-     * @throws {Error} when called twice before the first call is resolved.
-     */
-    getPrimaryPhp(): Promise<PHP>;
-    /**
-     * Get a PHP instance.
-     *
-     * It could be either the primary PHP instance, an idle disposable PHP instance,
-     * or a newly spawned PHP instance – depending on the resource availability.
-     *
-     * @throws {MaxPhpInstancesError} when the maximum number of PHP instances is reached
-     *                                and the waiting timeout is exceeded.
-     */
-    acquirePHPInstance(): Promise<SpawnedPHP>;
-    /**
-     * Initiated spawning of a new PHP instance.
-     * This function is synchronous on purpose – it needs to synchronously
-     * add the spawn promise to the allInstances array without waiting
-     * for PHP to spawn.
-     */
-    private spawn;
-    /**
-     * Actually acquires the lock and spawns a new PHP instance.
-     */
-    private doSpawn;
-    [Symbol.asyncDispose](): Promise<void>;
-}

package/lib/php-request-handler.d.ts

@@ -1,219 +0,0 @@
-import { PHP } from './php';
-import { PHPResponse } from './php-response';
-import { PHPRequest } from './universal-php';
-import { PHPFactoryOptions, PHPProcessManager } from './php-process-manager';
-export type RewriteRule = {
-    match: RegExp;
-    replacement: string;
-};
-interface BaseConfiguration {
-    /**
-     * The directory in the PHP filesystem where the server will look
-     * for the files to serve. Default: `/var/www`.
-     */
-    documentRoot?: string;
-    /**
-     * Request Handler URL. Used to populate $_SERVER details like HTTP_HOST.
-     */
-    absoluteUrl?: string;
-    /**
-     * Rewrite rules
-     */
-    rewriteRules?: RewriteRule[];
-}
-export type PHPRequestHandlerFactoryArgs = PHPFactoryOptions & {
-    requestHandler: PHPRequestHandler;
-};
-export type PHPRequestHandlerConfiguration = BaseConfiguration & ({
-    /**
-     * PHPProcessManager is required because the request handler needs
-     * to make a decision for each request.
-     *
-     * Static assets are served using the primary PHP's filesystem, even
-     * when serving 100 static files concurrently. No new PHP interpreter
-     * is ever created as there's no need for it.
-     *
-     * Dynamic PHP requests, however, require grabbing an available PHP
-     * interpreter, and that's where the PHPProcessManager comes in.
-     */
-    processManager: PHPProcessManager;
-} | {
-    phpFactory: (requestHandler: PHPRequestHandlerFactoryArgs) => Promise<PHP>;
-    /**
-     * The maximum number of PHP instances that can exist at
-     * the same time.
-     */
-    maxPhpInstances?: number;
-});
-/**
- * Handles HTTP requests using PHP runtime as a backend.
- *
- * @public
- * @example Use PHPRequestHandler implicitly with a new PHP instance:
- * ```js
- * import { PHP } from '../../../web/src/index.ts';
- *
- * const php = await PHP.load( '7.4', {
- *     requestHandler: {
- *         // PHP FS path to serve the files from:
- *         documentRoot: '/www',
- *
- *         // Used to populate $_SERVER['SERVER_NAME'] etc.:
- *         absoluteUrl: 'http://127.0.0.1'
- *     }
- * } );
- *
- * php.mkdirTree('/www');
- * php.writeFile('/www/index.php', '<?php echo "Hi from PHP!"; ');
- *
- * const response = await php.request({ path: '/index.php' });
- * console.log(response.text);
- * // "Hi from PHP!"
- * ```
- *
- * @example Explicitly create a PHPRequestHandler instance and run a PHP script:
- * ```js
- * import {
- *   loadPHPRuntime,
- *   PHP,
- *   PHPRequestHandler,
- *   getPHPLoaderModule,
- * } from '@php-wasm/web';
- *
- * const runtime = await loadPHPRuntime( await getPHPLoaderModule('7.4') );
- * const php = new PHP( runtime );
- *
- * php.mkdirTree('/www');
- * php.writeFile('/www/index.php', '<?php echo "Hi from PHP!"; ');
- *
- * const server = new PHPRequestHandler(php, {
- *     // PHP FS path to serve the files from:
- *     documentRoot: '/www',
- *
- *     // Used to populate $_SERVER['SERVER_NAME'] etc.:
- *     absoluteUrl: 'http://127.0.0.1'
- * });
- *
- * const response = server.request({ path: '/index.php' });
- * console.log(response.text);
- * // "Hi from PHP!"
- * ```
- */
-export declare class PHPRequestHandler {
-    #private;
-    rewriteRules: RewriteRule[];
-    processManager: PHPProcessManager;
-    /**
-     * The request handler needs to decide whether to serve a static asset or
-     * run the PHP interpreter. For static assets it should just reuse the primary
-     * PHP even if there's 50 concurrent requests to serve. However, for
-     * dynamic PHP requests, it needs to grab an available interpreter.
-     * Therefore, it cannot just accept PHP as an argument as serving requests
-     * requires access to ProcessManager.
-     *
-     * @param  php    - The PHP instance.
-     * @param  config - Request Handler configuration.
-     */
-    constructor(config: PHPRequestHandlerConfiguration);
-    getPrimaryPhp(): Promise<PHP>;
-    /**
-     * Converts a path to an absolute URL based at the PHPRequestHandler
-     * root.
-     *
-     * @param  path The server path to convert to an absolute URL.
-     * @returns The absolute URL.
-     */
-    pathToInternalUrl(path: string): string;
-    /**
-     * Converts an absolute URL based at the PHPRequestHandler to a relative path
-     * without the server pathname and scope.
-     *
-     * @param  internalUrl An absolute URL based at the PHPRequestHandler root.
-     * @returns The relative path.
-     */
-    internalUrlToPath(internalUrl: string): string;
-    /**
-     * The absolute URL of this PHPRequestHandler instance.
-     */
-    get absoluteUrl(): string;
-    /**
-     * The directory in the PHP filesystem where the server will look
-     * for the files to serve. Default: `/var/www`.
-     */
-    get documentRoot(): string;
-    /**
-     * Serves the request – either by serving a static file, or by
-     * dispatching it to the PHP runtime.
-     *
-     * The request() method mode behaves like a web server and only works if
-     * the PHP was initialized with a `requestHandler` option (which the online version
-     * of WordPress Playground does by default).
-     *
-     * In the request mode, you pass an object containing the request information
-     * (method, headers, body, etc.) and the path to the PHP file to run:
-     *
-     * ```ts
-     * const php = PHP.load('7.4', {
-     * 	requestHandler: {
-     * 		documentRoot: "/www"
-     * 	}
-     * })
-     * php.writeFile("/www/index.php", `<?php echo file_get_contents("php://input");`);
-     * const result = await php.request({
-     * 	method: "GET",
-     * 	headers: {
-     * 		"Content-Type": "text/plain"
-     * 	},
-     * 	body: "Hello world!",
-     * 	path: "/www/index.php"
-     * });
-     * // result.text === "Hello world!"
-     * ```
-     *
-     * The `request()` method cannot be used in conjunction with `cli()`.
-     *
-     * @example
-     * ```js
-     * const output = await php.request({
-     * 	method: 'GET',
-     * 	url: '/index.php',
-     * 	headers: {
-     * 		'X-foo': 'bar',
-     * 	},
-     * 	body: {
-     * 		foo: 'bar',
-     * 	},
-     * });
-     * console.log(output.stdout); // "Hello world!"
-     * ```
-     *
-     * @param  request - PHP Request data.
-     */
-    request(request: PHPRequest): Promise<PHPResponse>;
-}
-/**
- * Guesses whether the given path looks like a PHP file.
- *
- * @example
- * ```js
- * seemsLikeAPHPRequestHandlerPath('/index.php') // true
- * seemsLikeAPHPRequestHandlerPath('/index.php') // true
- * seemsLikeAPHPRequestHandlerPath('/index.php/foo/bar') // true
- * seemsLikeAPHPRequestHandlerPath('/index.html') // false
- * seemsLikeAPHPRequestHandlerPath('/index.html/foo/bar') // false
- * seemsLikeAPHPRequestHandlerPath('/') // true
- * ```
- *
- * @param  path The path to check.
- * @returns Whether the path seems like a PHP server path.
- */
-export declare function seemsLikeAPHPRequestHandlerPath(path: string): boolean;
-/**
- * Applies the given rewrite rules to the given path.
- *
- * @param  path  The path to apply the rules to.
- * @param  rules The rules to apply.
- * @returns The path with the rules applied.
- */
-export declare function applyRewriteRules(path: string, rules: RewriteRule[]): string;
-export {};

package/lib/php-response.d.ts

@@ -1,55 +0,0 @@
-export interface PHPResponseData {
-    /**
-     * Response headers.
-     */
-    readonly headers: Record<string, string[]>;
-    /**
-     * Response body. Contains the output from `echo`,
-     * `print`, inline HTML etc.
-     */
-    readonly bytes: ArrayBuffer;
-    /**
-     * Stderr contents, if any.
-     */
-    readonly errors: string;
-    /**
-     * The exit code of the script. `0` is a success, while
-     * `1` and `2` indicate an error.
-     */
-    readonly exitCode: number;
-    /**
-     * Response HTTP status code, e.g. 200.
-     */
-    readonly httpStatusCode: number;
-}
-/**
- * PHP response. Body is an `ArrayBuffer` because it can
- * contain binary data.
- *
- * This type is used in Comlink.transferHandlers.set('PHPResponse', \{ ... \})
- * so be sure to update that if you change this type.
- */
-export declare class PHPResponse implements PHPResponseData {
-    /** @inheritDoc */
-    readonly headers: Record<string, string[]>;
-    /** @inheritDoc */
-    readonly bytes: ArrayBuffer;
-    /** @inheritDoc */
-    readonly errors: string;
-    /** @inheritDoc */
-    readonly exitCode: number;
-    /** @inheritDoc */
-    readonly httpStatusCode: number;
-    constructor(httpStatusCode: number, headers: Record<string, string[]>, body: ArrayBuffer, errors?: string, exitCode?: number);
-    static forHttpCode(httpStatusCode: number, text?: string): PHPResponse;
-    static fromRawData(data: PHPResponseData): PHPResponse;
-    toRawData(): PHPResponseData;
-    /**
-     * Response body as JSON.
-     */
-    get json(): any;
-    /**
-     * Response body as text.
-     */
-    get text(): string;
-}

package/lib/php-worker.d.ts

@@ -1,77 +0,0 @@
-import { EmscriptenDownloadMonitor } from '../../../progress/src/index.ts';
-import { PHP } from './php';
-import { PHPRequestHandler } from './php-request-handler';
-import { PHPResponse } from './php-response';
-import { PHPRequest, PHPRunOptions, MessageListener, PHPEvent, PHPEventListener } from './universal-php';
-import { RmDirOptions, ListFilesOptions } from './fs-helpers';
-export type LimitedPHPApi = Pick<PHP, 'request' | 'defineConstant' | 'addEventListener' | 'removeEventListener' | 'mkdir' | 'mkdirTree' | 'readFileAsText' | 'readFileAsBuffer' | 'writeFile' | 'unlink' | 'mv' | 'rmdir' | 'listFiles' | 'isDir' | 'fileExists' | 'chdir' | 'run' | 'onMessage'> & {
-    documentRoot: PHP['documentRoot'];
-    absoluteUrl: PHP['absoluteUrl'];
-};
-/**
- * A PHP client that can be used to run PHP code in the browser.
- */
-export declare class PHPWorker implements LimitedPHPApi {
-    /** @inheritDoc @php-wasm/universal!RequestHandler.absoluteUrl  */
-    absoluteUrl: string;
-    /** @inheritDoc @php-wasm/universal!RequestHandler.documentRoot  */
-    documentRoot: string;
-    /** @inheritDoc */
-    constructor(requestHandler?: PHPRequestHandler, monitor?: EmscriptenDownloadMonitor);
-    __internal_setRequestHandler(requestHandler: PHPRequestHandler): void;
-    /**
-     * @internal
-     * @deprecated
-     * Do not use this method directly in the code consuming
-     * the web API. It will change or even be removed without
-     * a warning.
-     */
-    protected __internal_getPHP(): PHP | undefined;
-    setPrimaryPHP(php: PHP): Promise<void>;
-    /** @inheritDoc @php-wasm/universal!PHPRequestHandler.pathToInternalUrl  */
-    pathToInternalUrl(path: string): string;
-    /** @inheritDoc @php-wasm/universal!PHPRequestHandler.internalUrlToPath  */
-    internalUrlToPath(internalUrl: string): string;
-    /**
-     * The onDownloadProgress event listener.
-     */
-    onDownloadProgress(callback: (progress: CustomEvent<ProgressEvent>) => void): Promise<void>;
-    /** @inheritDoc @php-wasm/universal!PHP.mv  */
-    mv(fromPath: string, toPath: string): Promise<void>;
-    /** @inheritDoc @php-wasm/universal!PHP.rmdir  */
-    rmdir(path: string, options?: RmDirOptions): Promise<void>;
-    /** @inheritDoc @php-wasm/universal!PHPRequestHandler.request */
-    request(request: PHPRequest): Promise<PHPResponse>;
-    /** @inheritDoc @php-wasm/universal!/PHP.run */
-    run(request: PHPRunOptions): Promise<PHPResponse>;
-    /** @inheritDoc @php-wasm/universal!/PHP.chdir */
-    chdir(path: string): void;
-    /** @inheritDoc @php-wasm/universal!/PHP.setSapiName */
-    setSapiName(newName: string): void;
-    /** @inheritDoc @php-wasm/universal!/PHP.mkdir */
-    mkdir(path: string): void;
-    /** @inheritDoc @php-wasm/universal!/PHP.mkdirTree */
-    mkdirTree(path: string): void;
-    /** @inheritDoc @php-wasm/universal!/PHP.readFileAsText */
-    readFileAsText(path: string): string;
-    /** @inheritDoc @php-wasm/universal!/PHP.readFileAsBuffer */
-    readFileAsBuffer(path: string): Uint8Array;
-    /** @inheritDoc @php-wasm/universal!/PHP.writeFile */
-    writeFile(path: string, data: string | Uint8Array): void;
-    /** @inheritDoc @php-wasm/universal!/PHP.unlink */
-    unlink(path: string): void;
-    /** @inheritDoc @php-wasm/universal!/PHP.listFiles */
-    listFiles(path: string, options?: ListFilesOptions): string[];
-    /** @inheritDoc @php-wasm/universal!/PHP.isDir */
-    isDir(path: string): boolean;
-    /** @inheritDoc @php-wasm/universal!/PHP.fileExists */
-    fileExists(path: string): boolean;
-    /** @inheritDoc @php-wasm/universal!/PHP.onMessage */
-    onMessage(listener: MessageListener): void;
-    /** @inheritDoc @php-wasm/universal!/PHP.defineConstant */
-    defineConstant(key: string, value: string | boolean | number | null): void;
-    /** @inheritDoc @php-wasm/universal!/PHP.addEventListener */
-    addEventListener(eventType: PHPEvent['type'], listener: PHPEventListener): void;
-    /** @inheritDoc @php-wasm/universal!/PHP.removeEventListener */
-    removeEventListener(eventType: PHPEvent['type'], listener: PHPEventListener): void;
-}