Resolving Nginx Serving PHP Files as Downloads Instead of Executing Them: A Configuration and Troubleshooting Guide

Problem Background and Root Cause Analysis

When deploying a LEMP (Linux, Nginx, MySQL, PHP) stack on Ubuntu-based Digital Ocean servers, users often encounter a typical issue: accessing .php files results in the browser treating them as downloadable files instead of executing the PHP code to return dynamic content. The root cause of this phenomenon is that Nginx is not correctly configured to pass PHP requests to PHP-FPM (FastCGI Process Manager) for processing.

Unlike Apache servers, which handle PHP directly via the mod_php module, Nginx, as a reverse proxy server, relies on external processors like PHP-FPM to execute PHP scripts. When the location block in Nginx is misconfigured or the PHP-FPM service is not running correctly, Nginx defaults to treating .php files as static files, triggering download behavior in the browser.

Core Configuration Checks and Correction Steps

To resolve this issue, it is essential to systematically check and correct several key configuration aspects. The following steps are based on practical troubleshooting experience to ensure configuration completeness and security.

1. Verify Nginx Server Block Configuration

First, inspect the server block configuration in the /etc/nginx/sites-available/default file. Ensure the index directive includes index.php, and that the location ~ \.php$ block is properly enabled and configured.

server {
    listen 80 default_server;
    listen [::]:80 default_server ipv6only=on;

    root /var/www/html;
    index index.php index.html index.htm;

    server_name localhost;

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

    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_split_path_info ^(.+?\.php)(/.+)?$;
        fastcgi_pass unix:/var/run/php5-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
    }
}

Key points explained: try_files $uri =404; ensures the requested PHP file exists, avoiding security risks; fastcgi_pass points to the PHP-FPM Unix socket path; include fastcgi_params; loads necessary FastCGI parameters.

2. Configure PHP-FPM and PHP.ini

Confirm that the PHP-FPM service is installed and running. Use sudo systemctl status php5-fpm to check the service status. Edit the /etc/php5/fpm/php.ini file to set cgi.fix_pathinfo = 0, preventing potential security vulnerabilities.

3. Check File Permissions and Ownership

Ensure correct permissions for PHP files in the web root directory (e.g., /var/www/html). Use the following commands to set permissions:

sudo chown -R www-data:www-data /var/www/html
sudo find /var/www/html -type d -exec chmod 755 {} \;
sudo find /var/www/html -type f -exec chmod 644 {} \;

This ensures the Nginx process (typically running as the www-data user) has read and execute permissions for the files.

4. Restart Services and Test Configuration

After completing configuration modifications, restart the Nginx and PHP-FPM services:

sudo service nginx restart && sudo service php5-fpm restart

Create a test file info.php with the content <?php phpinfo(); ?> and access it via the browser at http://your_server_ip/info.php. If the PHP information page is displayed, the configuration is successful.

Additional Troubleshooting Suggestions

Beyond the core steps, the following supplementary measures may help address edge cases:

• Browser Cache Clearing: Old cache can cause the browser to mishandle responses. Clear the cache or test using incognito mode.
• FastCGI Parameter Verification: Ensure fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; is explicitly set in the configuration to correctly pass the script path.
• Log Analysis: Check Nginx error logs (/var/log/nginx/error.log) and PHP-FPM logs for detailed error information.

Summary and Best Practices

By systematically configuring the integration between Nginx and PHP-FPM, the issue of PHP files being served as downloads can be completely resolved. Key points include correctly setting the location directive in the server block, verifying PHP-FPM operation, adjusting PHP.ini security settings, and ensuring proper file permissions. Following these steps not only fixes the current problem but also enhances server security and performance.