/// <reference types="node" />
import type { IncomingMessage, Server, ServerResponse } from 'http';
/**
 * 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  options                 - 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, ...options: EmscriptenOptions[]): Promise<number>;
export type RuntimeType = 'NODE' | 'WEB' | 'WORKER';
export type PHPRuntimeId = number;
/**
 * Retrieves a PHP runtime by its ID and removes it from the internal registry.
 *
 * When you call `loadPHPRuntime()`, it creates an Emscripten-based PHP instance and
 * stores it in a module-level Map keyed by a numeric ID. This function is the only
 * way to retrieve that runtime object so you can actually use it.
 *
 * The "pop" semantic is intentional: retrieving a runtime also removes it from the
 * registry. This prevents memory leaks since the registry would otherwise hold
 * references to every runtime ever created. Once you pop a runtime, you own it and
 * are responsible for its lifecycle.
 *
 * Typical usage flow:
 * ```ts
 * // 1. Load a PHP runtime (returns just the ID)
 * const runtimeId = await loadPHPRuntime(phpLoaderModule);
 *
 * // 2. Pop the runtime to get the actual Emscripten module
 * const phpRuntime = popLoadedRuntime(runtimeId);
 *
 * // 3. Now you can use phpRuntime to run PHP code, access the filesystem, etc.
 * ```
 *
 * @param id - The numeric ID returned by `loadPHPRuntime()`.
 * @param options.dangerouslyKeepTheRuntimeInTheMap - Test-only escape hatch. When true,
 *        retrieves the runtime without removing it from the registry. This violates
 *        the function's contract and only works when `process.env.TEST` is set.
 *        Never use this in production code.
 * @returns The PHP runtime object (an Emscripten module instance).
 * @throws If no runtime exists with the given ID.
 */
export declare function popLoadedRuntime(id: PHPRuntimeId, { dangerouslyKeepTheRuntimeInTheMap, }?: {
    dangerouslyKeepTheRuntimeInTheMap?: boolean;
}): 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?: (phpRuntime: PHPRuntime) => void;
    monitorRunDependencies?: (left: number) => void;
    onMessage?: (listener: EmscriptenMessageListener) => void;
    outboundNetworkProxyServer?: Server<typeof IncomingMessage, typeof ServerResponse>;
    instantiateWasm?: (info: WebAssembly.Imports, receiveInstance: (instance: WebAssembly.Instance, module: WebAssembly.Module) => void) => void;
} & Record<string, any>;
export type EmscriptenMessageListener = (type: string, data: string) => void;