PHP-FPM Code and FileSystem Layout for EasyApache 4

Overview

This document provides detailed information regarding the PHP FastCGI Process Manager (PHP-FPM) daemon, specifically covering:

• The PHP-FPM filesystem layout.
• How PHP-FPM is implemented within your system.

PHP-FPM offers an efficient alternative FastCGI daemon for PHP, enabling websites to manage significant loads effectively. It allows a host to allocate specific resources to process a domain’s requests through worker pools that are available to respond to PHP requests. These dedicated pools significantly enhance a website's capacity to process more requests.

Compared to traditional CGI-based methods, such as SUPHP, PHP-FPM operates more rapidly in multi-user PHP environments. Crucially, it avoids overloading a system’s memory with PHP from Apache processes, unlike methods such as the ruid2+php-dso process. PHP-FPM is designed exclusively for executing PHP requests, allowing it to service content more quickly than other approaches.

Warning: We strongly advise that you only activate Apache PHP-FPM if your server has a minimum of 2 GB of available RAM, or at least 30 MB of RAM per domain. Enabling PHP-FPM on a server with insufficient RAM may lead to severe performance issues.

PHP-FPM Implementation

The Cpanel::PHPFPM (Cpanel/PHPFPM.pm) module forms the foundation of EasyApache’s support for PHP-FPM. The module’s integrated defaults are responsible for generating configuration files that provide fully functional PHP-FPM pools for each domain.

The system utilizes the following primary configuration files:

• /var/cpanel/ApachePHPFPM/system.yaml
• /var/cpanel/ApachePHPFPM/system_pool_defaults.yaml

You will need to create these two files manually by following these steps:

1. Create the /var/cpanel/ApachePHPFPM/ directory.

   mkdir -p /var/cpanel/ApachePHPFPM/

2. Create the two necessary files.

   1 2	touch /var/cpanel/ApachePHPFPM/system.yaml touch /var/cpanel/ApachePHPFPM/system_pool_defaults.yaml

File Contents

Each configuration file holds directives that differ from the built-in default values.

Note:

• The system does not strictly require these files to function, as the built-in defaults are sufficient for PHP-FPM to run.
• Only include differences in directives within these files.

The following example illustrates the contents of the system.yaml file:

Note:

• This example demonstrates a different value for the daemonize setting compared to its built-in default.
• The system-pool-defaults.yaml file applies its values to every pool you create.
• Every domain on the system requires a dedicated pool.
• Ensure to replace any unacceptable characters such as .[]() with an underscore (_).

The table below provides examples of unacceptable value names and their corrected versions.

Note: If you prepend any PHP settings with the disable functions or disable_classes flags, the system will append the new php.ini value to the existing one in the user’s .htaccess files. For further details, please consult securephp.net’s FastCGI Process Manager (FPM) documentation.

The Filesystem Configuration Files

The system stores the configuration files that govern PHP-FPM in the following locations:

• /opt/cpanel/ea-php80/root/etc/php-fpm.conf — This file contains the system-wide configurations for PHP-FPM.
• /opt/cpanel/ea-php80/root/etc/php-fpm.d/[domain].conf — This file is specific to your domain; for instance, it might appear as cptest1.tld.conf.

These two files are generated from the .yaml files located within the /var/cpanel directories.

Note:

• Do not manually edit these configuration files.
• The system duplicates these configuration files for each PHP version you select.
• The /opt/cpanel/ea-php80/root/etc/php-fpm.d/[domain].conf file will display ea-php80 or php80 as its version indicator.
• You must adapt ea-php80 to match the PHP version currently running on your system. For example, if your system uses PHP version 7.3 or 7.4, replace ea-php80 with ea-php73 or ea-php74, respectively.

Required Files

Note: The required file /var/cpanel/userdata/[user]/[domain].php-fpm.yaml should only be used if you intend to run PHP-FPM.

• /var/cpanel/userdata/[user]/[domain].php-fpm.yaml — This file specifically controls a domain’s PHP-FPM pool. The system utilizes both the built-in default values and the system_pool_defaults values to generate the corresponding [domain].conf file.

Optional Files

Note: Use the following optional files only if you wish to modify the default parameters. All domain pools will inherit these defaults unless they are overridden by a specific .yaml file.

• /var/cpanel/ApachePHPFPM/system.yaml — This file contains system-level settings. It is also used by the system to generate the /opt/cpanel/ea-php5?/root/etc/php-fpm.conf file, where the ? signifies that this file is used across all PHP versions in the php-fpm.conf file.
• /var/cpanel/ApachePHPFPM/system_pool_defaults.yaml — The system uses this file to generate and configure each domain’s pool and each user’s pool.

Important: If you modify a user’s pool through WHM’s MultiPHP Manager interface (WHM » Home » Software » MultiPHP Manager), the system will no longer apply the global system default settings to that specific user.

Restore PHP to Your System

The system is unable to remove configurations or other related files when packages are manually uninstalled. Manually removing packages could inadvertently eliminate essential dependencies required by your hosted websites.

Warning: We do not recommend removing any ea-php packages via your server’s package manager. If PHP is removed from your system while it is still in use by any hosted websites, those websites will likely encounter errors. Furthermore, Apache might completely fail to display the affected websites. Before removing a package, always confirm that no hosted websites are utilizing the PHP version you intend to remove by checking WHM’s MultiPHP Manager interface (WHM » Home » Software » MultiPHP Manager).

To restore PHP versions to your system, execute the following commands:

Note: Should the above commands fail, please contact your system administrator for assistance.