@php-wasm/universal 0.9.18 → 0.9.20

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

@@ -0,0 +1,104 @@
+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

@@ -0,0 +1,219 @@
+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

@@ -0,0 +1,55 @@
+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

@@ -0,0 +1,77 @@
+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;
+}