Env

Pair framework: Env class

The Env class provides a tiny and predictable way to load environment variables from a .env file into $_ENV, with:

• sensible defaults (fallback values);
• automatic type casting for booleans and numbers;
• a single accessor method to read variables consistently.

This is useful when you want to configure the same Pair application across multiple environments (local, staging, production) without hardcoding values in PHP files.

The .env file is expected to be placed in the project root (APPLICATION_PATH/.env).

---

.env file format

The .env file is a plain text file where each non-empty line is:

KEY=value

You can also add comments (lines starting with #), which will be ignored.

Example:

# Application
APP_NAME=My Pair App
APP_ENV=development
APP_DEBUG=true

# Pair / security
PAIR_SINGLE_SESSION=false

# OAuth2
OAUTH2_TOKEN_LIFETIME=3600

---

Constants

Env::FILE

The absolute path of the .env file.

Env::FILE; // APPLICATION_PATH . '/.env'

Env::DEFAULTS

An associative array containing fallback values used when:

• the .env file is missing, or
• a requested key is not present in $_ENV.

Current defaults:

• APP_NAME (string)
• APP_VERSION (string)
• APP_ENV (string)
• APP_DEBUG (bool)
• DB_UTF8 (bool)
• OAUTH2_TOKEN_LIFETIME (int, from OAuth2Token::LIFETIME)
• PAIR_SINGLE_SESSION (bool)
• PAIR_AUDIT_ALL (bool)
• PAIR_AUTH_BY_EMAIL (bool)
• UTC_DATE (bool)

Defaults are intentionally conservative: they make the app run even when .env is missing.

---

When to call Env::load()

Call Env::load() early in the bootstrap, typically in index.php or right after the Application startup, so that $_ENV is ready before other components read configuration.

Example (simplified index.php idea):

<?php

use Pair\Core\Application;
use Pair\Core\Env;

// start the application
$app = Application::getInstance();

// load .env variables into $_ENV
Env::load();

// now you can safely read Env values
if (Env::get('APP_DEBUG')) {
    ini_set('display_errors', '1');
}

---

Methods

Env::fileExists(): bool

Returns true if the .env file exists at Env::FILE.

Typical usage:

use Pair\Core\Env;

if (!Env::fileExists()) {
    // show a warning, or rely on defaults
}

---

Env::get(string $key): mixed

Returns the value for a given key, following this priority:

1. $_ENV[$key] (if already loaded / set)
2. Env::DEFAULTS[$key] (fallback)
3. null (if not found anywhere)

This allows consistent reads even when .env is not present.

Examples:

use Pair\Core\Env;

// read a boolean
$debug = Env::get('APP_DEBUG'); // true/false (or default)

// read a string
$appName = Env::get('APP_NAME'); // "Pair Application" by default

// unknown keys return null
$foo = Env::get('SOME_UNKNOWN_KEY'); // null

Env::get() does not throw if a key is missing; it is designed for predictable fallbacks.

---

Env::load(): void

Loads the .env file into $_ENV.

Behavior:

1. If .env does not exist:
   • loads every entry from Env::DEFAULTS into $_ENV
   • returns immediately
2. If .env exists:
   • reads the file line by line
   • ignores:
     • empty lines
     • lines starting with #
     • lines without an = symbol
   • splits each valid line into KEY and value
   • trims both key and value
   • casts types:
     • "true" / "false" (case-insensitive) -> true / false
     • numeric integers -> (int)
     • numeric floats -> (float)
     • everything else stays as string
   • assigns the final value into $_ENV[$key]

Example: type casting

Given this .env:

APP_DEBUG=true
OAUTH2_TOKEN_LIFETIME=3600
DISCOUNT=12.5
APP_NAME=My App

After Env::load():

use Pair\Core\Env;

Env::load();

var_dump(Env::get('APP_DEBUG'));            // bool(true)
var_dump(Env::get('OAUTH2_TOKEN_LIFETIME')); // int(3600)
var_dump(Env::get('DISCOUNT'));             // float(12.5)
var_dump(Env::get('APP_NAME'));             // string("My App")

Example: fallback to defaults when .env is missing

If the .env file does not exist, Pair will still work using defaults:

use Pair\Core\Env;

Env::load();

echo Env::get('APP_ENV');   // "production"
echo Env::get('APP_DEBUG'); // false

---

Suggested best practices

• Keep secrets (API keys, tokens, DSNs) in .env and out of Git.
• Call Env::load() once during bootstrap (do not reload repeatedly).
• Use Env::get() instead of reading $_ENV directly, so defaults always apply.
• Prefer boolean and numeric values in .env when you want type-safe reads.

---

Notes

• The .env loader is intentionally minimal: it focuses on predictable parsing and safe defaults.
• Lines without = are ignored, as well as comments starting with #.

See also: Configuration-file, Application, index.php, Logger.