How PHP-FPM and Nginx Communicate: A Complete Guide to FastCGI Configuration

PHP-FPM Overview

PHP‑FPM (PHP FastCGI Process Manager) implements the FastCGI protocol and adds process management. It runs a single master process that listens for connections from Nginx and multiple worker processes, each embedding a PHP interpreter that actually executes PHP code.

Nginx Overview

Nginx is a high‑performance HTTP server, reverse proxy, and also supports IMAP/POP3/SMTP. The article briefly distinguishes forward proxy (client‑to‑proxy) and reverse proxy (proxy‑to‑origin server) with illustrative images.

PHP‑FPM + Nginx Communication

FastCGI reduces the overhead of spawning a new CGI process for each request by keeping persistent processes managed by a FastCGI process manager. The communication steps are:

When Nginx receives a dynamic HTTP request, it initializes the FastCGI environment.

In the Nginx configuration a line such as fastcgi_pass 127.0.0.1:9000; or fastcgi_pass unix:/tmp/php-cgi.sock; tells Nginx where to forward the request.

Nginx forwards the request via a socket to the FastCGI master process.

The master selects an idle worker, sends CGI environment variables and STDIN to it.

The worker processes the PHP script and returns STDOUT and error output through the same socket.

The worker closes the connection and waits for the next request.

Configuration Variants

Nginx also has master and worker processes; its workers handle each network request.

PHP‑FPM, like Nginx, has a master process listening on a port (default 9000) and multiple workers that handle PHP requests.

FastCGI is a protocol; many implementations exist, PHP‑FPM being one of them. It typically listens on 127.0.0.1:9000 on the local machine.

FastCGI configuration files are usually placed alongside nginx.conf and come in two common forms:

/usr/local/openresty/nginx/conf/fastcgi.conf

fastcgi_params

(the default file shipped with Nginx)

When Nginx needs to process a PHP request, its worker forwards the request to a PHP‑FPM worker, effectively acting as a reverse proxy.

Example location block for PHP files:

location ~ \.php$ {
    try_files $fastcgi_script_name =404;
    include fastcgi_params;
    # fastcgi_pass unix:/var/run/php-fpm.sock;
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

Key directives explained: include fastcgi_params; – loads the FastCGI parameter definitions. fastcgi_pass 127.0.0.1:9000; – sends the request to the FastCGI server listening on that address.

fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

– tells PHP‑FPM the full path of the script to execute.

fastcgi_pass Transport Methods

Nginx can communicate with PHP‑FPM via two transport mechanisms:

TCP Socket – uses an IP address and port, allowing communication across different servers.

Unix Socket – a file‑system socket that does not use the network stack and works only when Nginx and PHP‑FPM run on the same machine.

TCP Socket Example

In nginx.conf: fastcgi_pass 127.0.0.1:9000; In php-fpm.conf: listen=127.0.0.1:9000; Communication flow: Nginx ⇆ socket ⇆ TCP/IP ⇆ socket ⇆ PHP‑FPM If Nginx and PHP‑FPM are on different machines, the data travels through the network layers and routers.

Unix Domain Socket Example

In nginx.conf: fastcgi_pass unix:/tmp/php-fpm.sock; In PHP‑FPM configuration: listen = /tmp/php-fpm.sock; (the socket file is created by PHP‑FPM).

Communication flow:

Nginx ⇆ socket ⇆ PHP‑FPM

include fastcgi_params

The fastcgi_params (and fastcgi.conf) files contain a list of FastCGI variables that Nginx passes to PHP‑FPM. Typical contents include:

$ cat fastcgi_params

fastcgi_param  QUERY_STRING        $query_string;
fastcgi_param  REQUEST_METHOD      $request_method;
fastcgi_param  CONTENT_TYPE         $content_type;
fastcgi_param  CONTENT_LENGTH       $content_length;

fastcgi_param  SCRIPT_NAME          $fastcgi_script_name;
fastcgi_param  REQUEST_URI          $request_uri;
fastcgi_param  DOCUMENT_URI         $document_uri;
fastcgi_param  DOCUMENT_ROOT        $document_root;
fastcgi_param  SERVER_PROTOCOL      $server_protocol;
fastcgi_param  REQUEST_SCHEME       $scheme;
fastcgi_param  HTTPS                $https if_not_empty;

fastcgi_param  GATEWAY_INTERFACE    CGI/1.1;
fastcgi_param  SERVER_SOFTWARE      nginx/$nginx_version;

fastcgi_param  REMOTE_ADDR          $remote_addr;
fastcgi_param  REMOTE_PORT          $remote_port;
fastcgi_param  SERVER_ADDR          $server_addr;
fastcgi_param  SERVER_PORT          $server_port;
fastcgi_param  SERVER_NAME          $server_name;

# Required for PHP built with --enable-force-cgi-redirect
fastcgi_param  REDIRECT_STATUS      200;

These variables become part of the $_SERVER superglobal in PHP, allowing scripts to access client IP, request method, and other request metadata.