Skip to content

Dotenv should gracefully handle or ignore shell-escaped and multiline environment values #592

@mhkarimi1383

Description

@mhkarimi1383

In CI environments it is very common for environment variables to contain:

  • newlines
  • shell-escaped values (e.g. $'...\n')
  • injected metadata such as commit messages

When generating a .env file from the current process environment (for example
using declare -px or similar mechanisms), PHP dotenv fails hard with:

Failed to parse dotenv file.
Encountered unexpected whitespace at [$'Merge branch \'test\'\n'].

This behavior is problematic because:

  • The environment itself is valid and usable by the shell
  • Other ecosystem tools (Docker, systemd, Node dotenv, Go env loaders, etc.)
    either ignore unsupported entries or treat them as literal strings
  • Dotenv crashes the entire application instead of handling the case defensively

Expected behavior:

  • Unsupported or non-dotenv-compatible variables should be skipped or sanitized
  • Multiline or shell-escaped values should not cause a fatal parsing error
  • At minimum, dotenv should fail gracefully and allow applications to decide how
    to proceed

Current behavior makes CI pipelines fragile, since injected environment variables
outside of the application's control can break builds unexpectedly.

This is especially painful during Composer scripts (e.g. artisan package:discover)
where there is no reasonable recovery path.

Handling this defensively would align dotenv with how other environment loaders
behave in production and CI systems.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions