{
    "slug": "twelve_factor_app",
    "term": "Twelve-Factor App",
    "category": "architecture",
    "difficulty": "intermediate",
    "short": "A methodology for building scalable, maintainable SaaS applications using twelve best practices for configuration, processes, and services.",
    "long": "The Twelve-Factor App methodology (Heroku, 2011) defines: I. Codebase (one repo), II. Dependencies (declared, isolated), III. Config (in environment), IV. Backing services (attached resources), V. Build/release/run (strict separation), VI. Processes (stateless), VII. Port binding (self-contained), VIII. Concurrency (scale-out), IX. Disposability (fast startup/graceful shutdown), X. Dev/prod parity, XI. Logs (treated as event streams), XII. Admin processes. For PHP, Factor III (config in environment) and Factor VI (stateless processes) have the largest security and scalability implications.",
    "aliases": [
        "12-factor app",
        "twelve factor methodology",
        "12factor"
    ],
    "tags": [
        "architecture",
        "devops",
        "cloud",
        "principles"
    ],
    "misconception": "The twelve-factor app is a cloud-native checklist that only applies to microservices. The methodology applies to any web application — monoliths benefit just as much from config in environment variables, stateless processes, and dependency isolation as microservices do.",
    "why_it_matters": "The Twelve-Factor methodology provides a portable, scalable application design — applications built to its principles deploy identically to any cloud, scale horizontally without refactoring, and have no dev/production divergence.",
    "common_mistakes": [
        "Storing config in code instead of environment variables — factor III.",
        "Local filesystem state that does not survive container restarts — factor VI (stateless processes).",
        "Admin tasks (migrations, scripts) run inside the web server process — factor XII (run admin as one-off processes).",
        "Hardcoded service URLs instead of environment-variable-configured backing services — factor IV."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "microservices",
        "devops",
        "continuous_deployment",
        "hardcoded_credentials"
    ],
    "prerequisites": [
        "cloud_native_patterns",
        "containerisation",
        "continuous_deployment"
    ],
    "refs": [
        "https://12factor.net/"
    ],
    "bad_code": "// Violates factor III — config in code:\ndefine('DB_HOST', 'db.prod.internal'); // Should be: getenv('DB_HOST')\ndefine('API_KEY', 'sk-prod-abc123');    // Should be: getenv('API_KEY')\n\n// Violates factor VI — filesystem state:\nfile_put_contents('/tmp/user_sessions/' . $id, $data); // Lost on restart",
    "good_code": "# Key factors and PHP implications:\n\n# I — Codebase: one repo, deploy to many envs via env vars\n# II — Dependencies: composer.json, no system-wide packages\ncomposer install --no-dev\n\n# III — Config: env vars, never hardcoded\n\\$dsn = sprintf('pgsql:host=%s;dbname=%s', \\$_ENV['DB_HOST'], \\$_ENV['DB_NAME']);\n\n# VI — Processes: stateless — no local filesystem writes\n# Upload files → S3, sessions → Redis (not filesystem)\nini_set('session.handler', 'redis');\n\n# VII — Port binding: PHP-FPM binds to a port, nginx proxies\n# IX — Disposability: fast startup (OPcache), graceful shutdown\n# XI — Logs: write to stdout, let platform aggregate\nerror_log = /dev/stderr  ; in php.ini",
    "quick_fix": "Audit your PHP app against the 12 factors: config in env vars, stateless processes, admin tasks as one-off processes, logs to stdout — start with the three most impactful: config, processes, logs",
    "severity": "medium",
    "effort": "high",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/twelve_factor_app",
        "html_url": "https://codeclaritylab.com/glossary/twelve_factor_app",
        "json_url": "https://codeclaritylab.com/glossary/twelve_factor_app.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": "[Twelve-Factor App](https://codeclaritylab.com/glossary/twelve_factor_app) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/twelve_factor_app"
            }
        }
    }
}