Env

Env

Razy provides a static .env file loader that parses environment variables and populates $_ENV, $_SERVER, and putenv(). It supports variable interpolation, multiline values, auto-casting, and the export prefix.

---

Table of Contents

• Quick Start
• Loading .env Files
• Reading Variables
• Setting Variables
• .env File Syntax
• Auto-Casting
• API Reference

---

Quick Start

use Razy\Env;

// Load .env file
Env::load(__DIR__ . '/.env');

// Read values
$dbHost = Env::get('DB_HOST', 'localhost');
$debug  = Env::get('APP_DEBUG'); // auto-cast: 'true' ??true

// Required values (throws RuntimeException if missing)
$secret = Env::getRequired('APP_SECRET');

---

Loading .env Files

use Razy\Env;

// Load ??throws RuntimeException if file not found
Env::load('/path/to/.env');

// Load with overwrite ??overrides existing env variables
Env::load('/path/to/.env', overwrite: true);

// Load if exists ??silently skip if file doesn't exist
$loaded = Env::loadIfExists('/path/to/.env.local');     // returns bool
$loaded = Env::loadIfExists('/path/to/.env.local', overwrite: true);

// Check initialization state
Env::isInitialized(); // true after first load()

// Parse raw content without loading into environment
$vars = Env::parse(file_get_contents('.env'));
// Returns: ['DB_HOST' => 'localhost', 'DB_PORT' => '3306', ...]

---

Reading Variables

use Razy\Env;

// Get with default
$host = Env::get('DB_HOST', 'localhost');

// Get with auto-casting enabled (default)
$debug = Env::get('APP_DEBUG');       // 'true' ??true (bool)
$port  = Env::get('DB_PORT');          // remains string '3306'

// Get without casting
$raw = Env::get('APP_DEBUG', null, cast: false); // 'true' (string)

// Check existence
if (Env::has('REDIS_URL')) {
    $redis = Env::get('REDIS_URL');
}

// Required ??throws RuntimeException if not set
$secret = Env::getRequired('APP_SECRET');
$apiKey = Env::getRequired('API_KEY', cast: false);

// Get all loaded variables
$all = Env::all(); // ['DB_HOST' => 'localhost', 'APP_DEBUG' => 'true', ...]

Resolution order: loaded cache ??$_ENV ??$_SERVER ??getenv()

---

Setting Variables

use Razy\Env;

// Set a variable (updates $_ENV, $_SERVER, and putenv)
Env::set('CUSTOM_VAR', 'custom_value');

// Reset all loaded state
Env::reset();

---

.env File Syntax

Basic Key-Value

APP_NAME=MyApp
DB_HOST=localhost
DB_PORT=3306

Quoted Values

# Double-quoted ??supports escape sequences and interpolation
APP_TITLE="My Application"
GREETING="Hello, ${APP_NAME}!"

# Single-quoted ??literal (no interpolation, no escapes)
REGEX='^[a-z]+$'

# Unquoted ??trimmed, no interpolation
SIMPLE_VALUE=hello world

Comments

# This is a comment
APP_NAME=MyApp  # Inline comments in unquoted values
APP_DESC="Has # inside"  # Hash inside quotes is not a comment

Export Prefix

export APP_ENV=production
export DB_HOST=db.example.com

Variable Interpolation

Only in double-quoted values:

BASE_URL="https://example.com"
API_URL="${BASE_URL}/api/v1"
FULL_URL="$BASE_URL/api"

Multiline Values

Only in double-quoted values:

RSA_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA0Z3VS5JJcds3xfn/yQ==
-----END RSA PRIVATE KEY-----"

Escape Sequences

In double-quoted values:

Sequence	Result
\\	Backslash
\"	Double quote
\n	Newline
\r	Carriage return
\t	Tab
\$	Literal dollar sign

Empty Values

EMPTY_VALUE=
ALSO_EMPTY=""

---

Auto-Casting

When $cast = true (default), the following string values are converted:

.env Value	PHP Type	PHP Value
true	bool	true
false	bool	false
null	null	null
(empty)	string	''

// .env: APP_DEBUG=true
$debug = Env::get('APP_DEBUG');         // bool true
$debug = Env::get('APP_DEBUG', cast: false); // string 'true'

// .env: LOG_LEVEL=null
$level = Env::get('LOG_LEVEL');         // null
$level = Env::get('LOG_LEVEL', cast: false); // string 'null'

---

API Reference

Method	Signature	Description
load	(string $path, bool $overwrite = false): void	Load .env file (throws on missing)
loadIfExists	(string $path, bool $overwrite = false): bool	Load if file exists
parse	(string $content): array	Parse raw content to key-value array
get	(string $key, mixed $default = null, bool $cast = true): mixed	Get variable
has	(string $key): bool	Check existence
set	(string $name, string $value): void	Set variable
all	(): array	All loaded variables
isInitialized	(): bool	Check if loaded
getRequired	(string $key, bool $cast = true): mixed	Get or throw RuntimeException
reset	(): void	Clear all loaded state

??Previous: Pipeline Authenticator