{
    "slug": "nginx_php_fpm_config",
    "term": "nginx + PHP-FPM Production Config",
    "category": "devops",
    "difficulty": "intermediate",
    "short": "The canonical nginx + PHP-FPM setup for PHP production — nginx handles static files and slow clients, PHP-FPM runs PHP via FastCGI, with proper timeout, buffer, and security settings.",
    "long": "nginx as a reverse proxy in front of PHP-FPM provides: serving static files directly (no PHP overhead), buffering slow client uploads before passing to FPM (protecting worker count), SSL termination, gzip compression, and security headers. PHP-FPM pool configuration controls worker count, memory limits, and request timeouts. Key settings: pm.max_children (max concurrent PHP processes), pm.max_requests (restart workers after N requests to prevent memory leaks), fastcgi_read_timeout (PHP execution time limit in nginx).",
    "aliases": [
        "nginx config",
        "PHP-FPM pool",
        "fastcgi",
        "production PHP setup"
    ],
    "tags": [
        "devops",
        "nginx",
        "php",
        "performance"
    ],
    "misconception": "More PHP-FPM workers always means better performance — each worker consumes ~30-60MB; too many workers exhaust RAM and cause swapping, which is worse than fewer workers.",
    "why_it_matters": "A misconfigured nginx/PHP-FPM stack is one of the most common causes of PHP application performance problems — timeouts, worker exhaustion, and memory leaks all stem from missing configuration.",
    "common_mistakes": [
        "pm.max_children set too high — workers exceed available RAM, causing swap and severe slowdowns.",
        "No fastcgi_read_timeout — nginx kills long-running PHP processes before they complete.",
        "Not setting PHP-FPM pm.max_requests — workers accumulate memory leaks without restarts.",
        "Missing fastcgi_param PHP_VALUE to override php.ini per virtual host."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "php_fpm",
        "reverse_proxy_vs_load_balancer",
        "php_opcache_tuning",
        "queue_worker_tuning"
    ],
    "prerequisites": [
        "php_fpm",
        "security_headers",
        "ssl_certificate_types"
    ],
    "refs": [
        "https://www.nginx.com/resources/wiki/start/topics/examples/phpfcgi/"
    ],
    "bad_code": "# Minimal nginx config — missing critical settings:\r\nserver {\r\n    listen 80;\r\n    root /var/www/html;\r\n    index index.php;\r\n    location ~ \\.php$ {\r\n        fastcgi_pass 127.0.0.1:9000;\r\n        include fastcgi_params;\r\n        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;\r\n        # No timeout, no buffering, no security headers\r\n    }\r\n}\r\n; php-fpm.conf — no limits:\r\npm = dynamic\r\npm.max_children = 50  ; May exceed available RAM",
    "good_code": "# Production nginx config:\nserver {\n    listen 443 ssl http2;\n    root /var/www/html/public;\n    \n    # Serve static files directly:\n    location ~* \\.(css|js|png|jpg|woff2)$ {\n        expires 1y; add_header Cache-Control 'public, immutable';\n    }\n    location ~ \\.php$ {\n        fastcgi_pass unix:/run/php-fpm.sock;\n        fastcgi_read_timeout 30;\n        fastcgi_buffers 16 16k;\n        fastcgi_buffer_size 32k;\n        include fastcgi_params;\n        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;\n    }\n}\n; php-fpm pool.conf:\npm = dynamic\npm.max_children = 20     ; RAM / ~50MB per worker\npm.max_requests = 500     ; Restart after 500 requests",
    "quick_fix": "Serve PHP via fastcgi_pass unix:/run/php/php8.3-fpm.sock; set fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name to prevent path traversal via Nginx",
    "severity": "high",
    "effort": "medium",
    "created": "2026-03-16",
    "updated": "2026-04-28",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/nginx_php_fpm_config",
        "html_url": "https://codeclaritylab.com/glossary/nginx_php_fpm_config",
        "json_url": "https://codeclaritylab.com/glossary/nginx_php_fpm_config.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": "[nginx + PHP-FPM Production Config](https://codeclaritylab.com/glossary/nginx_php_fpm_config) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/nginx_php_fpm_config"
            }
        }
    }
}