PHP Processor

PHP processor in a nutshell

The PHP processor essentially takes requests and passes them to the PHP interpreter for execution, allowing dynamic content generation and server-side scripting.

PHP is a great choice for dynamic web applications because it enables server-side scripting and dynamic content generation. It can be set up with relative ease and is battle-tested in many production environments. It powers frameworks like WordPress, Laravel, and Symfony, and it runs a large portion of the web.

PHP support in short

• Supports PHP via FastCGI using PHP-FPM (Linux/Windows) or PHP-CGI (Windows)
• Easy configuration
• Supports multiple PHP versions on the same server
• Efficient process management for handling PHP requests

PHP and Gruxi - friend or foe?

PHP is well supported in Gruxi on both Linux and Windows. PHP setups on Windows can be awkward with some web servers, but Gruxi aims to make it straightforward. Many PHP developers work on Windows (including the author of Gruxi), so the Windows experience is a priority.

In short: definitely friends.

Configuration fields

The PHP Processor has these configuration fields in the admin portal:

Name

Name is just a label for the processor and can be set to anything you like and only uses for your reference in the admin portal.

URL Match Patterns

The PHP processor will only handle requests that match the URL patterns you specify, and it will pass other requests to the next processor in line. Default is * (match all requests), but you can make this more specific by using URL matching rules to only proxy requests from one or more specific paths (for example, /my-blog/*).

Served By

This is where you specify how you want to serve PHP. You can choose between PHP-FPM and Windows PHP-CGI. The options available here depend on your platform and setup. In general, PHP-FPM is the recommended choice for Linux setups and can also be used on Windows via Docker or WSL, while Windows PHP-CGI is designed for native Windows setups.

Local Web Root

The local web root is the directory on your server where your PHP application is located. This is the root directory that Gruxi will use when processing PHP requests. For example, if your PHP application is located in C:\my-php-app on Windows or /var/www/html/my-php-app on Linux, you would set the local web root to that path.

Request Timeout

Request Timeout (in seconds) is the maximum amount of time that Gruxi will wait for a PHP request to complete before timing out. This is important to prevent hanging requests and to ensure that your server remains responsive. You can adjust this value based on the expected execution time of your PHP scripts.

Server software FastCGI spoof

Some PHP frameworks (such as WordPress) have different behavior when they detect certain server software in the HTTP headers. Gruxi allows you to spoof the server software header to improve compatibility with these frameworks.

Example for WordPress: Set it to "nginx" to ensure WordPress works correctly with permalinks and other features.

Choosing PHP versions, thread safe or non-thread safe?

For use with Gruxi, prefer the NTS (non-thread-safe) version of PHP for better performance and compatibility. The thread-safe build usually works too, but it can add overhead.

For the PHP version, the latest stable release is generally the best choice to get the newest features, performance improvements, and security patches.

Make sure to use PHP 7.1 or later with Gruxi if using PHP-CGI on Windows

This is because PHP 7.1 introduced important improvements to FastCGI support on Windows, which Gruxi relies on for efficient PHP handling. Using an older version of PHP may lead to compatibility issues and suboptimal performance when serving PHP applications with Gruxi on Windows.

PHP-FPM with Linux (or Windows via Docker)

Depending on your platform, Gruxi can use either FastCGI via PHP-FPM (Linux style setup) or FastCGI via PHP-CGI (Windows style setup) to handle PHP requests. Both methods are efficient and provide good performance for PHP applications.

For PHP-FPM, you need PHP installed with the FPM module enabled. Gruxi communicates with the PHP-FPM service over a TCP connection, and PHP-FPM handles its own process management. This is common and recommended on Linux systems. For this setup, you point Gruxi to the IP and port of the PHP-FPM service (running locally or inside Docker).

On Windows, it is still possible to use PHP-FPM if you have a setup for that, such as running PHP-FPM inside a WSL instance or in Docker.

PHP-CGI on Windows

For PHP-CGI, which is a way to run PHP on Windows systems, Gruxi will directly start and manage the PHP-CGI processes itself.

You need PHP installed on the file system, then create a Managed External Systems entry in the configuration and reference it from the site's PHP processor. Gruxi will then spawn PHP-CGI processes (as configured) to handle incoming requests.

See Managed External Systems for how to configure PHP-CGI instances on Windows.

Multiple PHP versions

Gruxi makes it easy to have multiple PHP versions installed and switch between them for different sites. This is useful for testing applications against different PHP versions or hosting multiple applications that require different PHP versions.

Windows

When using PHP-CGI on Windows, it is also easy to have multiple versions of PHP installed, and have different sites use different versions of PHP by just pointing to the correct PHP-CGI handler in the site configuration. This is great both in production and for local development.

Essentially, you download the PHP versions you want and create a Managed External Systems entry for each one, pointing to that version’s php-cgi.exe. Then, on each site's PHP processor, you select which PHP handler you want to use.

Linux and PHP-FPM

On Linux, you can also have multiple PHP versions installed with PHP-FPM, and point different sites to different PHP-FPM services running different PHP versions. This is a common setup on Linux servers. This means you can have, for example, PHP 7.4 and PHP 8.0 installed on the same server, each with its own PHP-FPM service running on different ports, and then configure your sites in Gruxi to use the appropriate PHP-FPM service based on the PHP version they require.

To switch to another PHP version, you can point the FastCGI IP:Port to the new instance running the desired PHP version, and update the FastCGI Web Root if needed. This allows you to easily switch between different PHP versions.

Troubleshooting and tips

"File not found" responses when using PHP-FPM in Docker?

A common pitfall here is that the FastCGI Web Root is not set correctly, which can lead to issues with resolving paths and serving the PHP application correctly. Make sure to set the FastCGI Web Root to the correct path where the web root is located inside the Docker container. If you get errors like "File not found" or similar, double-check the FastCGI Web Root setting and ensure it matches the web root in your Docker container.

Essentially, the FastCGI Web Root should be set to the path where the PHP application is located inside the Docker container, and it should correspond to the Local Web Root on your Windows filesystem. For example, if your PHP application is located in C:\my-php-app on Windows and it is mounted to /var/www/html in the Docker container, then the FastCGI Web Root should be set to /var/www/html.