Environment Management 🔐

# .env  — this file lives next to your code but is NEVER committed to git.
# Each line is KEY=value. No spaces around the =, no PHP, no quotes needed
# unless the value has spaces or special characters.

# Which environment is this? Drives debug, error display, etc.
APP_ENV=local
APP_DEBUG=true

# Database connection. The password stays HERE, never in your code.
DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=blog
DB_USER=root
DB_PASSWORD="s3cr3t p@ss"   # quotes because the value has a space

# A third-party API key — a textbook secret. Different per environment.
STRIPE_KEY=sk_test_4eC39HqLyjWDarjtT1zdp7dc

<?php
// HOW phpdotenv WORKS (the standard PHP library: composer require vlucas/phpdotenv)
//
//   use Dotenv\Dotenv;
//   $dotenv = Dotenv::createImmutable(__DIR__);  // looks for a .env in this folder
//   $dotenv->load();                             // reads it into $_ENV + getenv()
//
// After load(), every KEY=value in the .env is available three ways:
//   getenv("DB_HOST")   $_ENV["DB_HOST"]   $_SERVER["DB_HOST"]
//
// To run this example without Composer, the snippet below parses the same .env
// text by hand so you can SEE what phpdotenv does for you.

$dotenv = <<<ENV
APP_ENV=local
APP_DEBUG=true
DB_HOST=127.0.0.1
DB_PASSWORD="s3cr3t p@ss"
ENV;

// Tiny stand-in for phpdotenv: split lines, split on the first "=", store it.
foreach (explode("\n", $dotenv) as $line) {
    $line = trim($line);
    if ($line === "" || str_starts_with($line, "#")) {
        continue;                                   // skip blanks and # comments
    }
    [$key, $value] = explode("=", $line, 2);        // split on the FIRST = only
    $value = trim($value, " \"'");                  // strip spaces and quotes
    $_ENV[$key] = $value;                           // phpdotenv fills $_ENV like this
    putenv("$key=$value");                          // ...and getenv() like this
}

// Now read them back — exactly how you would after phpdotenv's load().
echo "From \$_ENV:   " . $_ENV["DB_HOST"] . "\n";  // 127.0.0.1
echo "From getenv: " . getenv("DB_PASSWORD") . "\n"; // s3cr3t p@ss
echo "APP_ENV:     " . $_ENV["APP_ENV"] . "\n";     // local
?>

From $_ENV:   127.0.0.1
From getenv: s3cr3t p@ss
APP_ENV:     local

<?php
// PROBLEM: getenv("FOO") returns the literal boolean false when FOO is not set,
// and an env value is ALWAYS a string ("false" is the text f-a-l-s-e, not false!).
// A small env() helper fixes both: it supplies a default and converts types.

function env(string $key, mixed $default = null): mixed
{
    $value = $_ENV[$key] ?? getenv($key);
    if ($value === false || $value === null) {
        return $default;                 // not set → fall back to the default
    }
    // Turn the common string values into real PHP types.
    return match (strtolower($value)) {
        "true"  => true,
        "false" => false,
        "null"  => null,
        default => $value,               // anything else stays a string
    };
}

// Pretend phpdotenv already loaded these two:
$_ENV["APP_DEBUG"] = "true";
$_ENV["DB_HOST"]   = "10.0.0.5";

// Required value that exists → you get it.
echo "DB host:   " . env("DB_HOST") . "\n";              // 10.0.0.5

// "true" the string becomes the boolean true.
$debug = env("APP_DEBUG");
echo "Debug on?  " . ($debug === true ? "yes" : "no") . "\n"; // yes

// Missing key → you get YOUR default, not a crash and not false.
echo "Cache TTL: " . env("CACHE_TTL", 3600) . "\n";      // 3600 (the default)
?>

DB host:   10.0.0.5
Debug on?  yes
Cache TTL: 3600

<?php
// 12-FACTOR RULE: the SAME code runs everywhere. Only the config changes.
// You don't ship a "dev build" and a "prod build" — you ship one app and feed
// it a different .env on each machine (dev / staging / production).

function env(string $key, mixed $default = null): mixed
{
    $value = $_ENV[$key] ?? false;
    return $value === false ? $default : $value;
}

// On production this comes from the server's .env. Here we set it by hand.
$_ENV["APP_ENV"] = "production";

$appEnv = env("APP_ENV", "local");   // default to "local" if nothing is set

// One switch drives behaviour that should differ between environments.
$config = match ($appEnv) {
    "production" => [
        "debug"      => false,            // never leak stack traces to users
        "cache"      => true,
        "log_level"  => "error",         // only the important stuff
    ],
    "staging" => [
        "debug"      => false,
        "cache"      => true,
        "log_level"  => "warning",
    ],
    default => [                          // "local" / dev
        "debug"      => true,             // show full errors while building
        "cache"      => false,            // always see fresh code
        "log_level"  => "debug",          // log everything
    ],
};

echo "Environment: $appEnv\n";
echo "Debug:       " . ($config["debug"] ? "ON" : "OFF") . "\n";
echo "Caching:     " . ($config["cache"] ? "ON" : "OFF") . "\n";
echo "Log level:   " . $config["log_level"] . "\n";
?>

Environment: production
Debug:       OFF
Caching:     ON
Log level:   error

<?php
// 🎯 YOUR TURN — read two values out of the loaded environment.
// phpdotenv has already filled $_ENV for you (we set it by hand below).

$_ENV["APP_NAME"]  = "My Blog";
$_ENV["APP_ENV"]   = "staging";

// 1) Read APP_NAME out of $_ENV
$name = ___;                  // 👉 use  $_ENV["APP_NAME"]

// 2) Read APP_ENV using the getenv-style superglobal too
$where = ___;                 // 👉 use  $_ENV["APP_ENV"]

echo "$name is running on: $where\n";

// ✅ Expected output:
//    My Blog is running on: staging
?>

My Blog is running on: staging

<?php
// 🎯 YOUR TURN — never let a MISSING setting crash your app.
// Finish env() so a missing key falls back to the default you pass in.

function env(string $key, mixed $default = null): mixed
{
    $value = $_ENV[$key] ?? false;
    // 👉 if $value is false (the key wasn't set), return $default; otherwise $value
    return ___;               // 👉 e.g.  $value === false ? $default : $value
}

// PAGE_SIZE is NOT set, so env() must hand back the default of 20.
echo "Page size: " . env("PAGE_SIZE", 20) . "\n";

// ✅ Expected output:
//    Page size: 20
?>

Page size: 20

# .gitignore  — tell git to NEVER track the real secrets file
.env
.env.local
.env.*.local


# .env.example  — COMMIT this. Same keys, no real values.
APP_ENV=local
APP_DEBUG=true
DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=
DB_USER=
DB_PASSWORD=
STRIPE_KEY=