README

Lightweight .env file loader for PHP. Zero dependencies.

Why This Library?

There are established .env loaders for PHP, most notably vlucas/phpdotenv. This library exists because we needed something simpler:

Zero dependencies — Nothing to install besides this package.
Thread-safe by design — Only writes to $_ENV. No putenv()/getenv(), which are not thread-safe in async runtimes (Swoole, RoadRunner, FrankenPHP).
No magic — No variable expansion (${VAR}), no multiline values, no interpreted escape sequences (\n, \t). What you write is what you get.
Minimal footprint — Easy to audit, easy to understand.

If you need variable expansion, multiline values, or getenv() support, use phpdotenv instead.

Installation

composer require sodaho/env-loader

Usage

Basic Usage

use Sodaho\EnvLoader\EnvLoader;

// Loads .env into $_ENV (does not overwrite existing, no required keys)
EnvLoader::load(__DIR__ . '/.env');

echo $_ENV['DB_HOST'];

Options

// Overwrite existing $_ENV variables
EnvLoader::load('.env', overwrite: true);

// Require specific keys (throws exception if missing)
EnvLoader::load('.env', required: ['DB_HOST', 'DB_NAME']);

// Required keys as comma-separated string
EnvLoader::load('.env', required: 'DB_HOST,DB_NAME');

// Combine options
EnvLoader::load('.env', overwrite: true, required: ['DB_HOST']);

Parse Without Loading

// Returns array without setting $_ENV
$values = EnvLoader::parse('.env');

print_r($values);
// ['DB_HOST' => 'localhost', 'DB_NAME' => 'myapp', ...]

Supported .env Syntax

# Comments
DB_HOST=localhost

# Empty values
EMPTY_VAR=

# Values with equals sign
PASSWORD=val=ue=with=equals

# Double quotes (supports escaped quotes)
MESSAGE="Hello World"
ESCAPED="Say \"Hello\""

# Single quotes (no escape processing)
SINGLE='Hello World'

# Inline comments
API_KEY=secret123 # this is ignored
QUOTED="value with # hash" # comment outside quotes

# export prefix
export DB_PORT=3306

# Whitespace is trimmed
  SPACED_KEY  =  value

Exceptions

All exceptions extend EnvLoaderException for easy catching:

use Sodaho\EnvLoader\EnvLoader;
use Sodaho\EnvLoader\Exception\EnvLoaderException;
use Sodaho\EnvLoader\Exception\FileNotFoundException;
use Sodaho\EnvLoader\Exception\MissingRequiredKeyException;

try {
    EnvLoader::load('.env', required: ['API_KEY']);
} catch (FileNotFoundException $e) {
    // File does not exist
} catch (MissingRequiredKeyException $e) {
    // Required key not found
} catch (EnvLoaderException $e) {
    // Any other EnvLoader error
}

Exception	When
`FileNotFoundException`	File does not exist or is a directory
`FileNotReadableException`	File exists but not readable
`InvalidKeyException`	Key has invalid format (e.g. `123KEY`, `MY-KEY`)
`UnterminatedQuoteException`	Quoted value missing closing quote
`MissingRequiredKeyException`	Required key missing after loading

Key Naming Rules

Valid keys must:

Start with a letter or underscore
Contain only letters, numbers, and underscores

DB_HOST      ✓
_PRIVATE     ✓
API_KEY_2    ✓
123KEY       ✗ (starts with number)
MY-KEY       ✗ (contains hyphen)
MY KEY       ✗ (contains space)

Why $_ENV Only?

This library intentionally writes only to $_ENV, not putenv() or $_SERVER.

Reason: Thread Safety

putenv() and getenv() are not thread-safe. In modern PHP runtimes like:

Swoole
RoadRunner
FrankenPHP
ReactPHP

...concurrent requests can overwrite each other's environment variables, causing hard-to-debug race conditions.

$_ENV is process-local and safe. Use $_ENV['KEY'] instead of getenv('KEY') in your application.

// Safe
$host = $_ENV['DB_HOST'];

// Not recommended (not set by this loader)
$host = getenv('DB_HOST');

When to Use

Development environments
Shared hosting where system ENV is not available
Simple projects without framework
Modern async PHP (Swoole, RoadRunner, FrankenPHP)

When NOT to Use

Production with proper system ENV configuration
When you need variable expansion (${OTHER_VAR})
When you need multiline values
When you must support legacy code using getenv()

Requirements

PHP ^8.2

Acknowledgments

Parts of this project (refactoring, documentation, code review) were developed with AI assistance (Claude).

License

MIT

sodaho / env-loader

Maintainers

Package info

Statistics

Security