Path or paths to .env files to load. Defaults to no file loading. When supplied, the runtime must provide fs (absent on edge platforms).

Ignored when ConfigPluginOptions.instance is set.

When true, a path in ConfigPluginOptions.envFilePath that does not exist is skipped instead of throwing. Defaults to false, which is the behaviour released in 0.1.0.

This exists for the layered-dotenv arrangement a scaffolded project uses: a gitignored .env beside a tracked .env.example. The file is present on the machine that generated it and absent on every fresh clone, in CI, and in a container built from the repository — so requiring it would make the project fail to start everywhere except its author's machine. A file that EXISTS but cannot be read still throws; only absence is tolerated.

Ignored when ConfigPluginOptions.instance is set.

A structural schema (e.g., a Zod schema) for validating configuration at startup. When provided, the schema's parse() is called once after merging and expansion, and the parsed output is stored as the configuration snapshot. This preserves Zod coercions and defaults.

Ignored when ConfigPluginOptions.instance is set — the supplied snapshot has already been through whatever validation produced it.

When true (default), expand ${NAME} references in values. Set to false to disable variable expansion.

Ignored when ConfigPluginOptions.instance is set.

An already-loaded configuration snapshot to use verbatim.

Present → nothing is read from the environment or from disk, the three options above are ignored, and this exact object becomes the application's CAPABILITIES.CONFIG service. Absent → configuration is loaded normally.

This exists so configuration can be resolved BEFORE plugins are constructed — deciding which plugins to register from a value in the environment — without the application then loading a second snapshot. Two snapshots read at different moments can disagree, and the one the composer branched on would not be the one handlers read.