How to Use Nginx with PHP-FPM: Simple Setup Guide

To use nginx with php-fpm, configure Nginx to pass PHP requests to the PHP-FPM socket or TCP port using the fastcgi_pass directive inside a location ~ \.php$ block. This setup allows Nginx to serve PHP files efficiently by forwarding them to PHP-FPM for processing.

Syntax

This is the basic syntax to configure Nginx to work with PHP-FPM:

• location ~ \.php$: Matches requests for PHP files.
• fastcgi_pass: Defines where to send PHP requests (socket or TCP).
• fastcgi_index: Default file to serve if directory is requested.
• fastcgi_param SCRIPT_FILENAME: Passes the full path of the PHP script to PHP-FPM.
• include fastcgi_params: Loads standard FastCGI parameters.

nginx

location ~ \.php$ {
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    fastcgi_index index.php;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

Example

This example shows a complete Nginx server block configured to serve PHP files using PHP-FPM via a Unix socket.

nginx

server {
    listen 80;
    server_name example.com;
    root /var/www/html;
    index index.php index.html index.htm;

    location / {
        try_files $uri $uri/ =404;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    location ~ /\.ht {
        deny all;
    }
}

Common Pitfalls

Common mistakes when using Nginx with PHP-FPM include:

• Using the wrong fastcgi_pass address (e.g., TCP port vs Unix socket mismatch).
• Not setting SCRIPT_FILENAME correctly, causing PHP-FPM to fail locating the script.
• Forgetting to include fastcgi_params, which passes necessary environment variables.
• Not having PHP-FPM running or listening on the specified socket or port.

Example of a wrong and right configuration:

nginx

# Wrong: Missing SCRIPT_FILENAME
location ~ \.php$ {
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    include fastcgi_params;
}

# Right: Correct SCRIPT_FILENAME set
location ~ \.php$ {
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

Quick Reference

Directive	Purpose
location ~ \.php$	Matches PHP file requests
fastcgi_pass	Sends PHP requests to PHP-FPM (socket or IP:port)
fastcgi_index	Default PHP file to serve (usually index.php)
fastcgi_param SCRIPT_FILENAME	Full path of PHP script for PHP-FPM
include fastcgi_params	Includes standard FastCGI parameters

Key Takeaways

Configure Nginx to pass PHP requests to PHP-FPM using the fastcgi_pass directive.

Always set SCRIPT_FILENAME correctly to the full path of the PHP script.

Include fastcgi_params to provide necessary environment variables to PHP-FPM.

Ensure PHP-FPM is running and listening on the specified socket or TCP port.

Test configuration changes by reloading Nginx and checking PHP file execution.