Documentation
¶
Overview ¶
Package envfile provides helpers for reading and updating .env files while preserving comments, blank lines, and line order.
Index ¶
- Constants
- func ApplyPhpArrayUpdates(path string, updates map[string]string) error
- func ApplyPhpConstUpdates(path string, updates map[string]string) error
- func ApplyPhpVarsUpdates(path string, updates map[string]string) error
- func ApplyUpdates(path string, updates map[string]string) error
- func ApplyUpdatesIn(path, format string, updates map[string]string) error
- func DuplicateKeys(path string) map[string][]string
- func ExampleValues(exampleContent string) map[string]string
- func KnownFormat(format string) bool
- func ReadKey(path, key string) string
- func ReadKeys(path string) ([]string, error)
- func ReadOverride(dir string) (overrides map[string]string, external map[string]bool)
- func ReadPhpArray(path string) (map[string]string, error)
- func ReadPhpConst(path string) (map[string]string, error)
- func ReadPhpVars(path string) (map[string]string, error)
- func ReadValues(path string) map[string]string
- func Reader(path, format string) func(key string) string
- func ReferencesContainer(content, serviceName string) bool
- func SyncPrimaryDomain(projectPath, envFile, urlKey, domain string, secured bool) error
- func UpdateAppURL(projectPath, envFile, urlKey, scheme, domain string) error
- func Values(path, format string) map[string]string
- type MergeResult
Constants ¶
const ( FormatDotenv = "dotenv" FormatPhpConst = "php-const" FormatPhpArray = "php-array" FormatPhpVars = "php-vars" )
Formats lerd can read and write. A definition naming anything else is from a newer store than this binary understands.
const ExternalServicesKey = "LERD_EXTERNAL_SERVICES"
ExternalServicesKey is the one reserved key inside OverrideFile. Its comma/space separated value lists services lerd should NOT start or provision for this project (you run your own). It is consumed by lerd and never written into the project's env file.
const OverrideFile = ".env.lerd_override"
OverrideFile is the personal, gitignored, per-project override file. It is plain dotenv syntax: any KEY=VALUE is layered on top of what `lerd env` writes, winning over lerd's defaults and computed values.
Variables ¶
This section is empty.
Functions ¶
func ApplyPhpArrayUpdates ¶ added in v1.29.0
ApplyPhpArrayUpdates sets each dotted key to its value, creating intermediate arrays as needed, and rewrites the file. A missing file (and its parent dirs) is created. An existing scalar keeps its type when the new value fits it.
func ApplyPhpConstUpdates ¶ added in v1.0.0
ApplyPhpConstUpdates rewrites define() values in a PHP file for the given keys. Existing define() calls are updated in-place. Keys that don't exist in the file are appended before "/* That's all" comment, or at the end of the file if not found.
func ApplyPhpVarsUpdates ¶ added in v1.33.0
ApplyPhpVarsUpdates sets each dotted key, rewriting the statement that owns it and appending a statement of its own for a key no assignment covers. A missing file (and its parent dirs) is created. An existing scalar keeps its type when the new value fits it.
func ApplyUpdates ¶
ApplyUpdates rewrites the .env at path, replacing values for any key in updates. Keys not already present are appended at the end in stable (sorted) order so idempotent calls produce identical bytes regardless of Go's map-range nondeterminism. Comments and blank lines are preserved. The write is skipped when the resulting contents match the existing file, so dev-side watchers (vite, IDE indexers, opcache) don't see mtime churn on idempotent calls. The file's existing mode is preserved.
Keys must not contain '=' or any newline character; values must not contain newline characters. These checks reject the env_overrides injection vector where a malicious .lerd.yaml value containing "\nADMIN_TOKEN=stolen" would otherwise split a single .env line into two and silently introduce an unrelated key.
func ApplyUpdatesIn ¶ added in v1.33.0
ApplyUpdatesIn writes updates to an env file in the given format, and is the one way anything writes one.
An unknown format is refused rather than written. The store reaches every install within a day, whatever binary it runs, so a definition naming a format added after a given release will land on machines that cannot honour it. The switches this replaces each fell through to the dotenv writer, which appended `key=value` lines into whatever file the definition named: a PHP settings file so treated stops parsing, and the site is down through no fault of its owner. Refusing leaves the project exactly as it was, which is the worst a binary too old for its definition should ever do.
func DuplicateKeys ¶ added in v1.33.0
DuplicateKeys returns the keys a dotenv file sets more than once, each with its values in the order they appear. Commented lines are not settings, so a value left behind under a `#` is not a duplicate of the live one.
A file setting a key twice is read differently by different runtimes, and both are defensible: Symfony's dotenv parses into an array so the last assignment wins, while Laravel loads through phpdotenv's immutable writer, which refuses to overwrite a name already set, so the first wins. lerd reads the first everywhere. Nothing can be right for both, which is why this exists to report the ambiguity rather than to resolve it.
func ExampleValues ¶ added in v1.28.0
ExampleValues maps each key in an .env.example to its raw value, everything after the first "=", copied verbatim so placeholders and quoting survive. The first occurrence of a key wins, matching the first-wins placement MergeMissing uses when inserting a duplicated example key.
func KnownFormat ¶ added in v1.33.0
KnownFormat reports whether this binary can read and write a format. An empty format is dotenv, which is what a definition that names none has always meant.
func ReadKey ¶ added in v0.6.0
ReadKey returns the value of a single key from the .env file at path, or an empty string if the key is absent or the file cannot be read.
func ReadKeys ¶ added in v1.5.0
ReadKeys returns all non-comment key names from the .env file at path, in the order they appear.
func ReadOverride ¶ added in v1.33.0
ReadOverride loads the personal override file from dir. It returns the KEY=VALUE overrides (with the reserved external key stripped out) and the set of externally-managed service names (lowercased). A missing or unreadable file yields two empty, non-nil collections. Values are kept verbatim, including any surrounding quotes, so they round-trip into the env file unchanged — quotes matter for values with spaces or '#'.
func ReadPhpArray ¶ added in v1.29.0
ReadPhpArray parses a PHP file returning a nested array and flattens it to dotted keys. A file with no return statement yields an empty map, not an error.
func ReadPhpConst ¶ added in v1.0.0
ReadPhpConst reads a WordPress-style wp-config.php file and returns a map of the defined PHP constants (define('KEY', 'value') calls). Only string and numeric constants are captured; boolean/null defines are ignored.
func ReadPhpVars ¶ added in v1.33.0
ReadPhpVars parses a PHP file's top-level assignments and flattens them to dotted keys. A file with no assignments yields an empty map, not an error.
func ReadValues ¶ added in v1.26.0
ReadValues reads path once and returns all non-comment key/value pairs, with each value unquoted the same way ReadKey unquotes a single key. On a duplicate key the first occurrence wins, matching ReadKey, which returns its first match. Returns an empty (non-nil) map when the file is missing, so callers can range freely. Prefer this over repeated ReadKey calls when checking several keys from one file: ReadKey re-opens and rescans the whole file on every call.
func Reader ¶ added in v1.29.0
Reader returns a key lookup for an env file in the given format ("dotenv", "php-const", "php-array", "php-vars"). An unreadable file yields a reader that returns empty strings, so callers need no error path for a missing env file.
func ReferencesContainer ¶ added in v1.26.0
ReferencesContainer reports whether content references the lerd container hostname "lerd-<serviceName>" as a whole token, so bare "postgres" is not matched by a "lerd-postgres-18" reference (and vice versa). Commented-out lines are ignored so a disabled "#DB_HOST=lerd-mysql" doesn't keep a removed service's badge alive on the site page.
func SyncPrimaryDomain ¶ added in v1.10.0
SyncPrimaryDomain updates the framework's URL key and VITE_REVERB_HOST/SCHEME/PORT in the project's env file to reflect the current primary domain and TLS state. envFile and urlKey are the framework's, resolved by config.URLTargetFor. Only keys that already exist in the .env are touched. Silently does nothing if no .env exists.
func UpdateAppURL ¶
UpdateAppURL sets the framework's URL key in envFile to scheme://domain. envFile and urlKey come from the framework definition (config.URLTargetFor), so Symfony's DEFAULT_URI in .env.local is written the same way Laravel's APP_URL in .env is. An empty urlKey means the framework holds its base URL somewhere other than the env file. Silently does nothing if the file is absent.
func Values ¶ added in v1.33.0
Values reads every key/value pair from an env file in the given format ("dotenv", "php-const", "php-array", "php-vars"). An unreadable file yields an empty (non-nil) map, so callers need no error path for a project whose env file isn't there yet. Prefer this over Reader when several keys are wanted, or when the absence of a key has to be told apart from an empty value.
Types ¶
type MergeResult ¶ added in v1.28.0
MergeResult is the outcome of merging missing .env.example keys into an existing .env. Merged is the full proposed file content, ready to render in a diff or write to disk; Added lists the keys that were inserted, in the order they appear in .env.example; AddedLines gives the 1-based line numbers in Merged that are newly inserted (key lines and their carried comments), so a viewer can decorate exactly the added lines without re-diffing.
func MergeMissing ¶ added in v1.28.0
func MergeMissing(exampleContent, envContent string, include map[string]bool) MergeResult
MergeMissing computes a proposed .env that adds the keys present in exampleContent but missing from envContent, placing each one next to the neighbours it has in .env.example rather than appending them all at the end.
Placement is anchor-based: walking the example in order, the last example key that also exists in the .env is the current anchor, and a missing key is queued to be inserted right after that anchor's line. This keeps a missing DB_PORT inside the DB_* block instead of orphaning it at the bottom. Keys missing before any shared key land at the top, in example order.
When include is non-nil, only missing keys for which include[key] is true are added; a nil include adds every missing key. Values, quoting, and attached comments are copied verbatim from the example so placeholders survive. Keys in the .env that are absent from the example are never touched.
Source Files