Configuring NGINX for PHP Files in /install/ Directory for phpBB

PHP files in /install/ directory are downloading instead of executing when NGINX is not properly configured to process PHP scripts via PHP-FPM. This occurs when the configuration is missing or incorrectly configured the location block for processing PHP files, especially in the phpBB installation directory. To fix this issue, you need to properly configure NGINX with the path to PHP-FPM and add specific rules for the /install/ directory.

Contents

• Main causes of the problem
• Checking current NGINX configuration
• Proper NGINX configuration for phpBB
• Configuration for /install/ directory
• Additional solutions and checks
• Steps to apply changes

Main causes of the problem

The main reasons why PHP files are downloading instead of executing in NGINX:

1. Incorrect fastcgi_pass configuration - if the fastcgi_pass parameter points to a non-existent socket or is incorrectly configured PHP-FPM, NGINX won’t be able to pass PHP files for processing.

2. Missing configuration for PHP files - the server block may be missing a location block for processing .php files.

3. Conflict with SSL certificates - as shown in research, Certbot can remove important PHP processing settings when installing SSL.

4. Incorrect file permissions - the web server (www-data, nginx, apache) may not have read and execute permissions for PHP files.

5. php.ini issues - the cgi.fix_pathinfo parameter may be set to 1, which causes path processing problems.

Checking current NGINX configuration

Before making changes, check your current configuration:

1. Open your site’s configuration file:

sudo nano /etc/nginx/sites-available/your-site.conf

2. Check for the following critical elements:

• A server block with the correct server_name
• A location block for processing .php files
• The correct path to the PHP-FPM socket

Important: The configuration should contain a block that processes all .php files, including those in the /install/ directory.

Proper NGINX configuration for phpBB

The basic configuration for phpBB should include the following elements:

server {
    listen 80;
    server_name your-domain.com www.your-domain.com;
    root /var/www/phpbb;
    index index.php index.html index.htm;

    # Deny access to sensitive files
    location ~ /(config\.php|common\.php|cache|files|images/avatars/upload|includes|store|vendor) {
        deny all;
        return 403;
    }

    # PHP file processing
    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # URL rewrite processing for clean URLs
    location / {
        try_files $uri $uri/ @rewriteapp;
    }

    location @rewriteapp {
        rewrite ^(.*)$ /app.php/$1 last;
    }
}

Key points:

• fastcgi_pass should point to the correct PHP-FPM socket
• SCRIPT_FILENAME should correctly point to the file in the document root
• Use try_files $uri =404 for security

Configuration for /install/ directory

For proper phpBB 3.2+ installer operation, special configuration for the /install/ directory is required:

# Special handling for phpBB installer
location /install/ {
    try_files $uri $uri/ @rewrite_installapp =404;
    
    # PHP file processing in /install/
    location ~ \.php(/|$) {
        include fastcgi_params;
        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        fastcgi_param PATH_INFO $fastcgi_path_info;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $realpath_root;
        try_files $uri $uri/ /install/app.php$is_args$args;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
    }
}

# Internal rewrite for installer
location @rewrite_installapp {
    rewrite ^(.*)$ /install/app.php/$1 last;
}

phpBB 3.2+ features:

• The installer uses app.php instead of index.php
• Requires special processing for paths like /install/app.php/update
• Proper configuration of PATH_INFO and SCRIPT_FILENAME is necessary

Note: As mentioned in research, phpBB 3.2.x uses new installation logic through app.php, which requires additional configuration in NGINX.

Additional solutions and checks

If the problem persists, perform the following checks:

PHP-FPM Configuration

1. Open php.ini:

sudo nano /etc/php/8.1/fpm/php.ini

2. Ensure that:

cgi.fix_pathinfo = 0

3. Check PHP-FPM pool configuration:

sudo nano /etc/php/8.1/fpm/pool.d/www.conf

File Permission Check

sudo chown -R www-data:www-data /var/www/phpbb
sudo chmod -R 755 /var/www/phpbb
sudo chmod -R 644 /var/www/phpbb/*.php

PHP-FPM Operation Check

sudo systemctl status php8.1-fpm
sudo systemctl restart php8.1-fpm

Steps to apply changes

1. Configuration syntax check:

sudo nginx -t

2. Restart services:

sudo systemctl restart nginx
sudo systemctl restart php8.1-fpm

3. Clear browser cache - as noted in sources, clearing the cache can solve the problem.

4. Check file permissions in the /install/ directory.

5. Testing by accessing http://your-domain.com/install/app.php

If the problem persists, check the logs:

sudo tail -f /var/log/nginx/error.log
sudo tail -f /var/log/php8.1-fpm.log

Sources

1. phpBB — NGINX Unit Configuration Guide
2. nginx config for phpbb and laravel - Stack Overflow
3. Sample nginx configuration file for phpBB - GitHub
4. Nginx configuration for phpBB - Nginx Library
5. Working nginx config? - phpBB Community
6. New 3.2.X installer does not work under nginx + PHP7? - phpBB Development
7. Trying to install phpBB (3.2.7) on CentOS 7 with Nginx - Super User

Conclusion

• Main cause of PHP files downloading - incorrect NGINX configuration for processing PHP via PHP-FPM, especially in the /install/ directory.
• Key elements of the fix: correct fastcgi_pass, SCRIPT_FILENAME, location blocks for .php files, and special rules for /install/.
• Required steps: configuration syntax check, restarting NGINX and PHP-FPM, clearing browser cache.
• For phpBB 3.2+ special handling of app.php and proper PATH_INFO configuration is required.
• Always check logs of NGINX and PHP-FPM when problems occur to diagnose specific errors.

With proper configuration, PHP files in the /install/ directory should execute correctly instead of downloading.