import type { Emscripten } from './emscripten-types';
import type { EmscriptenOptions } from './load-php-runtime';
/**
 * 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";
/**
 * The php.ini directive used to load the extension. Use `extension` for
 * regular PHP extensions and `zend_extension` for Zend extensions like Xdebug.
 */
export type PHPExtensionIniDirective = 'extension' | 'zend_extension';
export type PHPExtensionLoadDirective = PHPExtensionIniDirective | false;
/**
 * Extension artifact manifest. Lets callers publish a matrix of `.so` files
 * and lets `resolvePHPExtension()` select the artifact matching the current
 * PHP version. External extension artifacts are JSPI-only.
 */
export interface PHPExtensionManifest {
    name: string;
    version?: string;
    mode?: 'php-extension';
    /**
     * The first directive of the generated startup `.ini` file. Defaults to
     * `extension`; use `zend_extension` for Zend extensions like Xdebug.
     * Use `false` to stage the `.so` without registering it in php.ini.
     */
    loadWithIniDirective?: PHPExtensionLoadDirective;
    /** Additional `key=value` lines for the generated startup `.ini` file. */
    iniEntries?: Record<string, string>;
    /** Environment variables added 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;
    artifacts: Array<{
        /** PHP major/minor version, e.g. `8.4`. */
        phpVersion: string;
        /** Relative to the manifest URL/base URL, or an absolute URL. */
        sourcePath: string;
        /** URL-backed files needed only by this artifact. */
        extraFiles?: PHPExtensionManifestExtraFiles;
    }>;
    /** URL-backed files shared by every artifact in this manifest. */
    extraFiles?: PHPExtensionManifestExtraFiles;
}
export interface PHPExtensionManifestExtraFiles {
    /**
     * Absolute VFS path where files and directories are written. When a
     * manifest declares both top-level and per-artifact `extraFiles`, the
     * first declared `targetPath` wins. Defaults to
     * `<extensionDir>/<name>-assets`.
     */
    vfsRoot?: string;
    nodes?: Array<{
        /** Joined with the group's `vfsRoot` to form the final VFS path. */
        vfsPath: string;
        /** Defaults to "file". Only file nodes need a `sourcePath`. */
        type?: 'file' | 'directory';
        /** Relative to the manifest URL/base URL, or an absolute URL. */
        sourcePath?: string;
    }>;
}
/**
 * Source for a PHP extension `.so`. Use `format: 'so'` when the caller 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';
    name?: string;
    bytes: Uint8Array | ArrayBuffer;
} | {
    format: 'url';
    name?: string;
    url: string | URL;
} | {
    format: 'manifest';
    /**
     * In `@php-wasm/universal`, must be an absolute URL. `@php-wasm/node`
     * also accepts filesystem paths and `file:` URLs.
     */
    manifestUrl: string | URL;
} | {
    format: 'manifest';
    manifest: PHPExtensionManifest;
    /** Base URL for resolving relative artifact paths. */
    baseUrl?: string | URL;
};
export type DataToResolvePhpExtension = ResolvedInstallOptions;
export interface ResolvedInstallOptions {
    /** PHP major/minor version the active runtime is initializing for. */
    phpVersion: string;
    source: PHPExtensionSource;
    /** Overrides the name inferred from `source`. */
    name?: string;
    /**
     * The first directive of the generated startup `.ini` file. Regular
     * extensions need `extension=...`; Zend extensions like Xdebug need
     * `zend_extension=...`.
     */
    loadWithIniDirective?: PHPExtensionLoadDirective;
    /** Additional `key=value` lines for the generated startup `.ini` file. */
    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?: ResolvedExtraFiles;
    /** Environment variables added 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 URL and manifest sources. Runtimes may
     * provide environment-specific defaults; for example, `@php-wasm/node`
     * adds local file support.
     */
    fetch?: typeof fetch;
}
/**
 * Fully resolved files and settings needed to install one extension. Produced
 * by `resolvePHPExtension`; consumed by `withResolvedPHPExtensions` and
 * `installPHPExtensionFilesSync`.
 */
export interface ResolvedPHPExtension {
    /** Absolute VFS path the `.so` file is staged at. */
    soPath: string;
    /** Compiled extension bytes to write at `soPath`. */
    soBytes: Uint8Array;
    /** Absolute VFS path the generated per-extension ini file is staged at. */
    iniPath?: string;
    /**
     * Contents of the generated per-extension ini file. The first line is the
     * `extension=` or `zend_extension=` directive; remaining lines are the
     * caller-supplied `iniEntries`.
     */
    iniContent?: string;
    /** Sidecar files staged alongside the extension. Optional. */
    extraFiles?: ResolvedExtraFiles;
    /** Environment variables added before PHP startup. */
    env?: Record<string, string>;
    /** VFS directory the `.so` and ini file live in. */
    extensionDir: string;
}
/**
 * Sidecar files to stage next to an extension. Use this for data files or
 * native-library assets the extension expects at runtime. All paths are
 * absolute VFS paths.
 */
export interface ResolvedExtraFiles {
    /** Absolute VFS paths to create as empty directories. */
    directories?: string[];
    /** Map of absolute VFS paths to file contents. */
    files: Record<string, Uint8Array | string>;
}
/**
 * Inputs used to build the staged `.so` path and per-extension ini file when
 * `installPHPExtensionFilesSync` is called with raw install options instead of
 * a `ResolvedPHPExtension`.
 */
export interface InstallPHPExtensionFilesOptions {
    /** Extension name used for staged file names and the ini directive. */
    name: string;
    /** Compiled extension bytes. */
    soBytes: Uint8Array | ArrayBuffer;
    /**
     * The first directive of the generated startup `.ini` file. Regular
     * extensions need `extension=...`; Zend extensions like Xdebug need
     * `zend_extension=...`.
     */
    loadWithIniDirective?: PHPExtensionLoadDirective;
    /** Additional `key=value` lines for the generated startup `.ini` file. */
    iniEntries?: Record<string, string>;
    /** Sidecar files to write into the PHP VFS before the extension is loaded. */
    extraFiles?: ResolvedExtraFiles;
    /** Environment variables added 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;
}
/**
 * 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.
 *
 * Manifest-declared extra files are joined with their group's `vfsRoot` so the
 * returned `extraFiles` always uses absolute VFS paths.
 *
 * TODO: Remove the remote manifest.json resolution and move it to Blueprints
 *       where the paths can be validated and downloads scheduled using the
 *       same code paths as we do for all other paths and URLs.
 */
export declare function resolvePHPExtension(options: DataToResolvePhpExtension): Promise<ResolvedPHPExtension>;
/**
 * Adds resolved extensions to Emscripten options. The returned options install
 * extension files during `preRun` 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.
 */
export declare function installPHPExtensionFilesSync(fs: Emscripten.RootFS, options: InstallPHPExtensionFilesOptions | ResolvedPHPExtension): ResolvedPHPExtension;