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