{
    "slug": "dotenv",
    "term": ".env Files & Environment Variables",
    "category": "php",
    "difficulty": "beginner",
    "short": "Storing configuration in environment variables (not source code), loaded from a .env file in development via libraries like vlucas/phpdotenv.",
    "long": "The Twelve-Factor App methodology mandates configuration in the environment — database credentials, API keys, and environment-specific settings should never be hardcoded or committed to version control. In development, vlucas/phpdotenv loads a .env file into $_ENV and getenv(). In production, variables are set at the infrastructure level (Docker, Kubernetes secrets, AWS Parameter Store). Always add .env to .gitignore; commit a .env.example with placeholder values. Access variables via $_ENV['KEY'] or getenv('KEY') — prefer $_ENV as it's not affected by php.ini's variables_order.",
    "aliases": [
        ".env file",
        "environment variables PHP",
        "vlucas/phpdotenv"
    ],
    "tags": [
        "php",
        "configuration",
        "devops",
        "twelve-factor"
    ],
    "misconception": "Committing a .env file to the repository is fine if credentials are for a dev environment. .env files in version control establish a pattern that leads to production credentials being committed accidentally. Use .env.example with dummy values and keep real .env files out of git.",
    "why_it_matters": "Storing configuration in environment variables (twelve-factor app principle) keeps credentials out of source code and allows the same codebase to run in different environments without modification.",
    "common_mistakes": [
        "Committing the .env file to version control — the whole point is to keep secrets out of the repo.",
        "Not providing a .env.example with all required keys — new developers don't know what to configure.",
        "Loading .env in production when environment variables are already set by the server — causes double-loading conflicts.",
        "Using $_ENV instead of getenv() or a dotenv library — $_ENV is not populated in all PHP configurations."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "hardcoded_credentials",
        "api_key_exposure",
        "php_ini",
        "twelve_factor_app"
    ],
    "prerequisites": [
        "environment_variables_linux",
        "secrets_management",
        "php_ini"
    ],
    "refs": [
        "https://12factor.net/config",
        "https://github.com/vlucas/phpdotenv"
    ],
    "bad_code": "// .env committed to git — credentials exposed:\n# .gitignore is missing .env entry\nDB_PASSWORD=supersecret123\nAPI_KEY=sk-live-abc123\n# Anyone with repo access has these credentials",
    "good_code": "# .env — local secrets, NEVER committed to git\nAPP_ENV=production\nDB_HOST=db.internal\nDB_PASS=super_secret_password\nSTRIPE_SECRET=sk_live_...\n\n# .env.example — template committed to git, no real secrets\nAPP_ENV=local\nDB_HOST=localhost\nDB_PASS=\nSTRIPE_SECRET=\n\n# PHP — vlucas/phpdotenv\n\\$dotenv = Dotenv\\Dotenv::createImmutable(__DIR__);\n\\$dotenv->load();\n\\$dotenv->required(['DB_HOST', 'DB_PASS', 'APP_KEY']); // fail fast if missing\n\n\\$dbPass = \\$_ENV['DB_PASS'];\n\n# In production: set env vars at server/container level — don't deploy .env files",
    "quick_fix": "Use vlucas/phpdotenv to load .env in development; ensure .env is in .gitignore and .env.example documents all required keys without values",
    "severity": "high",
    "effort": "low",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/dotenv",
        "html_url": "https://codeclaritylab.com/glossary/dotenv",
        "json_url": "https://codeclaritylab.com/glossary/dotenv.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[.env Files & Environment Variables](https://codeclaritylab.com/glossary/dotenv) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/dotenv"
            }
        }
    }
}