NGINX error: PHP files downloading instead of executing

The Problem

Encountering a scenario where PHP files download instead of executing is a common issue with NGINX web servers. This problematic behavior usually occurs when NGINX is not properly configured to handle PHP files through PHP-FPM (FastCGI Process Manager). To ensure a seamless and functional web environment, resolving this error is paramount. In this article, we’ll explore the reasons behind this error and provide practical solutions to fix it.

Possible Causes of the Error

Before diving into the solutions, it’s important to understand what causes PHP files to download instead of execute. Typically, this error arises when NGINX lacks the correct location block to handle PHP files or when the PHP-FPM service is not configured or running correctly. The absence of these configurations prevents NGINX from serving PHP files dynamically, leading to their download.

Solutions

Solution 1: Ensure Correct MIME Type

Checking and setting the correct MIME type in NGINX is crucial. NGINX needs to use the text/html MIME type for PHP files to enable their execution.

Steps:

1. Edit the NGINX configuration file (nginx.conf) for your website.
2. Locate the http block and ensure the include directive for the MIME types file is present (usually mime.types).
3. Verify the MIME types file itself contains the line specifying PHP files as text/html.
4. Restart the NGINX server to apply changes.

Notes: This solution is one of the simplest checks and is effective if the error is due to an incorrect MIME type configuration. However, in most scenarios, this is not the case as NGINX typically includes MIME types by default.

Solution 2: Configure NGINX to Use PHP-FPM

One of the primary reasons for this error is inadequate configuration of NGINX to pass PHP requests to a PHP-FPM backend for execution. This configuration includes setting up the proper location blocks and setting the fastcgi parameters.

Steps:

1. Open the NGINX server block configuration file for your site.
2. Inside the server block, add or correct the location ~ \.php$ block to include the correct directives for handling PHP files.
3. Ensure that the fastcgi_pass directive points to the PHP-FPM socket or TCP listening address.
4. Include the necessary fastcgi parameters using the include fastcgi_params; directive.
5. Save your changes and restart the NGINX server to apply them.

Example:

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

Notes: This solution addresses the core configuration requirement for executing PHP with NGINX. It is widely applicable and usually resolves the problem as long as PHP-FPM is also correctly set up and active.

Solution 3: Verify PHP-FPM Service Status

Sometimes the issue may not be the web server configuration, but rather that the PHP-FPM service isn’t running. Ensuring the service is active and listening for connections is essential.

Steps:

1. Check the status of PHP-FPM using the command systemctl status php7.4-fpm. Substitute php7.4-fpm for your specific version.
2. If the service is not active, start it using the command systemctl start php7.4-fpm.
3. Enable PHP-FPM to start on boot using the command systemctl enable php7.4-fpm.
4. After starting PHP-FPM, restart NGINX to allow it to connect to the PHP-FPM service.

Notes: This is a critical check because no matter the configuration, if PHP-FPM is not running, PHP files will not execute. Always ensure that the PHP-FPM service matches the version of PHP installed on your system.

Conclusion

Correctly configuring your NGINX server to handle PHP scripts is essential to create dynamic and interactive websites. If you’ve followed the above solutions, your PHP files should be executing, rather than downloading. Keep in mind Configuration differences can exist across different server environments, so you may need to tailor solutions to fit your setup. When in doubt, check official documentation or consult with professionals.