keepcalculator

06 Numbers and Powers

Connect nginx to PHP-FPM: Setup Guide

Card No. 06·84165 · Updated · Standard formula, shown below

To connect nginx to PHP-FPM, you edit the nginx server block to pass PHP requests to the FPM socket or TCP port using the fastcgi_pass directive, then reload nginx. This article explains the configuration steps, how the two processes communicate, and common pitfalls to avoid.

How nginx and PHP-FPM Work Together

nginx is a web server that excels at serving static files and handling many concurrent connections, but it does not execute PHP code. PHP-FPM (FastCGI Process Manager) is a separate service that runs PHP scripts. When a request for a .php file arrives, nginx forwards it to PHP-FPM via the FastCGI protocol. PHP-FPM processes the script and returns the output to nginx, which then sends it back to the client. This separation allows each service to be tuned independently and improves performance under load.

Prerequisites

  • nginx installed and running (e.g., sudo systemctl status nginx).
  • PHP-FPM installed for your PHP version (e.g., php8.2-fpm on Debian/Ubuntu).
  • Root or sudo access to edit configuration files.

Step-by-Step Configuration

  1. Locate the PHP-FPM pool configuration. On most systems it is at /etc/php/<version>/fpm/pool.d/www.conf. It defines the user, group, and the listen address (either a Unix socket or a TCP port).
  2. Check the listen directive. Look for a line like listen = /run/php/php8.2-fpm.sock (socket) or listen = 127.0.0.1:9000 (TCP). Note the exact value.
  3. Edit your nginx site configuration. Usually at /etc/nginx/sites-available/your-site. Inside the server block, add a location block for PHP files:
location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
}

If your FPM listens on TCP, replace the fastcgi_pass line with fastcgi_pass 127.0.0.1:9000;.

  1. Test the configuration. Run sudo nginx -t to check for syntax errors.
  2. Reload nginx. Use sudo systemctl reload nginx (or sudo nginx -s reload).

After reloading, create a test PHP file (e.g., info.php with <?php phpinfo(); ?>) in your web root and access it via your domain. If you see the PHP info page, the connection works.

Socket vs. TCP: Which to Choose?

PHP-FPM can listen on either a Unix domain socket or a TCP/IP port. Unix sockets are generally faster because they avoid network stack overhead and are more secure on a single host. TCP is useful when PHP-FPM runs on a different machine or when you need to connect over a network. For most single-server setups, a Unix socket is recommended. Ensure the socket path in nginx matches exactly what FPM uses, and that the FPM user has write permissions to the socket directory.

Common Errors and Fixes

  • 502 Bad Gateway: Usually means nginx cannot reach PHP-FPM. Check that FPM is running (sudo systemctl status php8.2-fpm) and that the fastcgi_pass path/port is correct.
  • 404 Not Found for .php files: Often caused by a missing try_files directive. Add try_files $uri =404; inside the PHP location block to prevent nginx from passing non-existent files to FPM.
  • Access denied or permission errors: The FPM pool user (often www-data) must have read access to the PHP files and write access to the socket directory. Check file ownership and permissions.
  • PHP files download instead of executing: This indicates the location ~ \.php$ block is missing or not matching. Verify the regex and that the block is inside the correct server block.

Performance Tuning

Adjust the FPM pool settings in www.conf to match your workload. The pm directive controls process management: dynamic starts a base number of children and adjusts based on demand; ondemand starts processes only when needed; static keeps a fixed number. For high-traffic sites, dynamic with sensible pm.max_children, pm.start_servers, pm.min_spare_servers, and pm.max_spare_servers values is common. Monitor memory usage to avoid exhausting RAM. Also ensure nginx has enough worker connections (worker_connections) to handle concurrent requests.

Security Considerations

  • Restrict PHP execution to trusted directories. Avoid allowing uploads to be executed as PHP. Use a location block to disable PHP in upload directories.
  • Set cgi.fix_pathinfo=0 in php.ini to prevent path traversal vulnerabilities.
  • Run PHP-FPM as an unprivileged user (e.g., www-data) and ensure the socket file is not world-writable.
  • Use HTTPS to protect data in transit, especially if your site handles sensitive information.

Frequently Asked Questions

What is the difference between fastcgi_pass and proxy_pass?

fastcgi_pass is specifically for FastCGI servers like PHP-FPM, while proxy_pass is for general HTTP proxying (e.g., to Node.js or Apache). They use different protocols and headers; using the wrong one will not work.

Why do I get a 502 Bad Gateway after changing the PHP version?

After upgrading PHP, the FPM socket path changes (e.g., from php7.4-fpm.sock to php8.2-fpm.sock). Update the fastcgi_pass directive in your nginx config to match the new socket path.

Can I use PHP-FPM with Apache instead of nginx?

Yes, Apache can use PHP-FPM via mod_proxy_fcgi, but the configuration is different. nginx is often chosen for its efficiency and simpler FastCGI integration.

How do I set up multiple PHP versions on the same server?

Run separate PHP-FPM instances on different sockets or ports. In nginx, create separate server blocks or use conditional fastcgi_pass based on the domain or path.

What is the include snippets/fastcgi-php.conf line for?

This file contains common FastCGI parameters (like SCRIPT_FILENAME) that nginx needs to pass to PHP-FPM. It simplifies configuration and avoids duplication.

Why does my PHP script show a blank page?

Check the PHP error log (usually at /var/log/php-fpm.log or in the FPM pool configuration). It may be a syntax error, a missing extension, or a fatal error that is not displayed. Also ensure display_errors is set appropriately for development.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →