Common Nginx+PHP Pitfalls and How to Write a Clean Configuration

For many developers, configuring Nginx with PHP is reduced to copying a tutorial, but outdated or flawed examples can lead to serious problems. This article reviews common errors and bad practices in typical Nginx+PHP configurations and shows how to improve them.

Understanding Inheritance in Nginx

Nginx configuration blocks inherit values from outer to inner scopes (e.g., http → server → location). Knowing this helps avoid redundant directives.

Index Directive Placement

Placing index inside a location block causes duplication when adding new locations, because sibling locations do not inherit from each other. Define index at the server level to let all locations inherit it.

Misuse of the if Directive

The if directive is often misunderstood; it should not be used for request checks. Instead, use try_files for file existence checks. The if statement belongs to the rewrite module, and mixing it with non‑rewrite directives can produce unexpected results.

if (!-e $request_filename) {
    rewrite . /index.php last;
}

Replace the above with:

try_files $uri $uri/ /index.php;

FastCGI Parameter Files

Nginx provides two fastcgi parameter files: fastcgi_params and fastcgi.conf. The latter adds a SCRIPT_FILENAME definition:

fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

Note that there is no slash between $document_root and $fastcgi_script_name. Using both files together can cause duplicate parameters because fastcgi_param is an array‑type directive.

Security Consideration with cgi.fix_pathinfo

If PHP’s cgi.fix_pathinfo is enabled, PHP may treat wrong file types as scripts. A simple mitigation is to filter requests with try_files before passing them to PHP:

try_files $uri =404;

Improved Configuration Example

The following configuration incorporates the discussed improvements, resulting in a cleaner and more reliable setup.

server {
    listen 80;
    server_name foo.com;
    root /path;
    index index.html index.htm index.php;

    location / {
        try_files $uri $uri/ /index.php;
    }

    location ~ \.php$ {
        try_files $uri =404;
        include fastcgi.conf;
        fastcgi_pass 127.0.0.1:9000;
    }
}

While this version resolves many issues, some edge cases—such as incompatibilities between try_files and fastcgi_split_path_info —remain and may require additional tweaks.