Skip to content

fix(env): never write an env format this binary does not understand - #1401

Merged
geodro merged 2 commits into
mainfrom
fix/env-format-forward-compatibility
Aug 8, 2026
Merged

fix(env): never write an env format this binary does not understand#1401
geodro merged 2 commits into
mainfrom
fix/env-format-forward-compatibility

Conversation

@geodro

@geodro geodro commented Aug 8, 2026

Copy link
Copy Markdown
Member

A definition published to the store reaches every install within a day, whatever binary it runs, and there is no engine version gate in the index or the schema. So a definition naming an env format added after a given release lands on machines that cannot honour it, and each of the three write switches fell through to the dotenv writer, which appends key=value lines into whatever file the definition names.

Driven against a binary built from before the php-vars format, with a definition using it:

$settings['config_sync_directory'] = 'sites/default/files/sync';
databases.default.default.autoload=core/modules/mysql/src/Driver/Database/mysql/
databases.default.default.database=proj
databases.default.default.driver=mysql

Parse error: syntax error, unexpected token "default" in settings.php on line 11

A dead site, on a machine whose owner did nothing but leave lerd running.

Writing goes through one function now, and it refuses a format it does not know, says so, and leaves the project exactly as it was. Reading an unknown format returns nothing rather than inventing keys out of whatever the file happens to contain. That is the worst a binary too old for its definition should ever do, and it is what makes any future format safe to publish.

A definition also needs a way to describe a file older binaries cannot handle without breaking them, so env gains app_file and app_format, naming the file the application itself reads. Where they are declared lerd reads and writes that file; the existing file and fallback_file describe what an older binary should do with the same definition. They are a separate pair for exactly that reason: an unknown field is ignored on parse, so one definition carries both answers and every install behaves as well as its version allows.

Verified both ways against the same definition. The old binary appends define() calls that Drupal ignores, which is what it does today, and the file still parses. The current binary writes the $databases array Drupal actually reads.

A definition published to the store reaches every install within a day, whatever binary it runs, and there is no engine version gate in the index or the schema. A definition naming a format added after a given release therefore lands on machines that cannot honour it, and each of the three write switches fell through to the dotenv writer, which appended key=value lines into whatever file the definition named. Driven against a binary from before the php-vars format, that turned a Drupal settings file into one PHP refuses to parse: the site is down, on a machine whose owner did nothing.

Writing goes through one function now, and it refuses a format it does not know, saying so and leaving the project exactly as it was. Reading an unknown format returns nothing rather than inventing keys out of whatever the file happens to contain. That is the worst a binary too old for its definition should ever do.

A definition also needs a way to describe a file older binaries cannot handle without breaking them, so env gains app_file and app_format, naming the file the application itself reads. Where they are declared lerd reads and writes that file, and the existing file and fallback_file describe what an older binary should do with the same definition. They are a separate pair for exactly that reason: an unknown field is ignored on parse, so a definition can carry both answers at once and every install behaves as well as its version allows.
@geodro
geodro requested a review from a team as a code owner August 8, 2026 07:10
@geodro
geodro merged commit 20c29be into main Aug 8, 2026
3 checks passed
@geodro
geodro deleted the fix/env-format-forward-compatibility branch August 8, 2026 07:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant