Twelve-Factor App

Also Known As

TL;DR

Explanation

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.

Diagram

flowchart TD
    subgraph The 12 Factors
        F1[1 Codebase<br/>one repo] 
        F2[2 Dependencies<br/>explicitly declared]
        F3[3 Config<br/>in environment]
        F4[4 Backing Services<br/>attached resources]
        F5[5 Build Release Run<br/>strict separation]
        F6[6 Processes<br/>stateless]
        F7[7 Port Binding<br/>self-contained]
        F8[8 Concurrency<br/>process model]
        F9[9 Disposability<br/>fast startup]
        F10[10 Dev/Prod Parity<br/>keep similar]
        F11[11 Logs<br/>treat as streams]
        F12[12 Admin Processes<br/>one-off tasks]
    end
style F1 fill:#238636,color:#fff
style F3 fill:#238636,color:#fff
style F6 fill:#1f6feb,color:#fff

Common Misconception

Why It Matters

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.

Code Examples

// Violates factor III — config in code:
define('DB_HOST', 'db.prod.internal'); // Should be: getenv('DB_HOST')
define('API_KEY', 'sk-prod-abc123');    // Should be: getenv('API_KEY')

// Violates factor VI — filesystem state:
file_put_contents('/tmp/user_sessions/' . $id, $data); // Lost on restart

# Key factors and PHP implications:

# I — Codebase: one repo, deploy to many envs via env vars
# II — Dependencies: composer.json, no system-wide packages
composer install --no-dev

# III — Config: env vars, never hardcoded
\$dsn = sprintf('pgsql:host=%s;dbname=%s', \$_ENV['DB_HOST'], \$_ENV['DB_NAME']);

# VI — Processes: stateless — no local filesystem writes
# Upload files → S3, sessions → Redis (not filesystem)
ini_set('session.handler', 'redis');

# VII — Port binding: PHP-FPM binds to a port, nginx proxies
# IX — Disposability: fast startup (OPcache), graceful shutdown
# XI — Logs: write to stdout, let platform aggregate
error_log = /dev/stderr  ; in php.ini

References

• ↗ https://12factor.net/

Tags

Related Terms