Loading Functions

Part of the API Reference. All three share identical parameters and parsing behavior — pick based on how you want a missing file and I/O handled.

`penvload`

Map<String, String> penvload(
  String path, {
  String template = _defaultPlaceholderContent,
  bool createFile = true,
  bool expandVariables = true,
  bool useProcessEnvironment = false,
  bool preferProcessEnvironment = true,
  List<String>? required,
}) {

Loads key-value pairs from a .env-style file at path, synchronously. See Env File Syntax for the full parsing rules.

Parameter	Default	Meaning
`template`	a short placeholder comment	Content written to `path` if it doesn’t exist and `createFile` is `true`.
`createFile`	`true`	Whether to write a placeholder file when `path` doesn’t exist.
`expandVariables`	`true`	Whether `${OTHER_KEY}` references are resolved.
`useProcessEnvironment`	`false`	Whether to overlay `Platform.environment` onto keys already present in the file.
`preferProcessEnvironment`	`true`	When overlaying, whether the process environment wins over the file’s own value.
`required`	`null`	Keys that must be present with a non-empty value, or `MissingRequiredKeysException` is thrown.

If no file exists at path:

createFile: true (the default) — a new file is created at path containing template, and EnvFileNotFoundException is thrown.
createFile: false — no file is written, and EnvFileNotFoundException is thrown immediately.

In both cases the caller is expected to fill in the file and call penvload again.

Throws EnvFileNotFoundException if no file exists at path. Throws MissingRequiredKeysException if required keys are missing.

`penvloadOrNull`

Map<String, String>? penvloadOrNull(
  String path, {
  bool expandVariables = true,
  bool useProcessEnvironment = false,
  bool preferProcessEnvironment = true,
  List<String>? required,
}) {

Like [penvload], but returns null instead of throwing when path doesn’t exist, and never creates a placeholder file. Useful for optional configuration that’s fine to skip entirely:

final env = penvloadOrNull('.env.local') ?? <String, String>{};

If the file does exist but required keys are missing from it, MissingRequiredKeysException is still thrown — a present-but-invalid file is treated as a real configuration error, not an absent one.

`penvloadAsync`

Future<Map<String, String>> penvloadAsync(
  String path, {
  String template = _defaultPlaceholderContent,
  bool createFile = true,
  bool expandVariables = true,
  bool useProcessEnvironment = false,
  bool preferProcessEnvironment = true,
  List<String>? required,
}) async {

The async equivalent of [penvload], for callers that avoid synchronous file I/O (e.g. server frameworks that discourage blocking calls). Behavior, parameters, and thrown exceptions are identical to [penvload]. See Async Loading.