Configuring Nginx for PHP-FPM

Nginx passes PHP requests to a FastCGI socket or address; it does not execute PHP itself.

What It Does and When to Use It

Forward only existing public PHP scripts to FPM; verify socket and application paths. The web server handles HTTP, the PHP worker executes scripts, and CLI has separate configuration and lifecycle.

Requirements, Inputs and Expected Behavior

Confirm the runtime, extension, environment variables, and permissions before running the examples in production. Use try_files and SCRIPT_FILENAME carefully to prevent executing arbitrary paths.

Example 1: Basic Operation

Forward only existing public PHP scripts to FPM; verify socket and application paths.

server {
  listen 80;
  server_name app.example.test;
  root /srv/app/public;
  index index.php;
  location / { try_files $uri /index.php$is_args$args; }
  location ~ \.php$ {
    try_files $uri =404;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
    fastcgi_pass unix:/run/php/php8.4-fpm.sock;
  }
  location ~ /\. { deny all; }
}

Example 2: Behavior and Validation

Diagnose configuration parsing and the matching FPM service.

sudo nginx -t
sudo systemctl status php8.4-fpm --no-pager

Practical Example: Application Use

Test an actual response and inspect errors without enabling browser-visible diagnostics.

curl -sSI http://127.0.0.1/health
sudo tail -n 30 /var/log/nginx/error.log

Important Behavior and Edge Cases

The second example highlights: Diagnose configuration parsing and the matching FPM service. The practical example adds: Test an actual response and inspect errors without enabling browser-visible diagnostics.

Comparison with Related Approaches

Approach	What changes
Web server, worker and PHP CLI	The web server handles HTTP, the PHP worker executes scripts, and CLI has separate configuration and lifecycle.
Choosing safely	Check the effective configuration in the SAPI serving requests before changing production.

Common Beginner Mistakes

Mistake	Correct approach
Checking the PHP CLI INI instead of FPM	Inspect phpinfo or configuration through the protected web SAPI.
Exposing worker status publicly	Restrict FPM diagnostics to localhost or a monitored private network.
Skipping operational constraints	Use try_files and SCRIPT_FILENAME carefully to prevent executing arbitrary paths.

Key Takeaways

Nginx passes PHP requests to a FastCGI socket or address; it does not execute PHP itself.
Test an actual response and inspect errors without enabling browser-visible diagnostics.
Check the effective configuration in the SAPI serving requests before changing production.