Advanced PHP Configuration

Last modified: March 7, 2023

Overview

This document provides advanced PHP configuration file information. Use this document to ensure that you set the appropriate .ini files for your configuration.

The php ini files

The system searches for and reads php.ini files when PHP starts. When it loads a directive that a php.ini file specifies, it loads the first incident of each directive that it finds. The system searches for php.ini files in the following order:

A SAPI module specific location, such as the PHPIniDir directive in Apache, the PHP_INI_Path environmental variable, or the php_ini parameter in NSAPI.
The PHPRC environmental variable.
The current working directory.
The webserver’s SAPI module or PHP directory.

Important:

If a php-sapi.ini file exists, where sapi represents the SAPI in use, the system reads that file instead of the php.ini file.
The Apache web server changes to the root directory at startup, which causes PHP to read php.ini files that exist in the root user’s directories.

In cPanel & WHM, the system also scans the .ini files that exist in the /opt/cpanel/ea-php##/root/etc/php.d/ directory. The system reads these files in alphabetical order.

Note:

To see the files that PHP loaded, you can execute the php_ini_scanned_files() function with your PHP script or run PHP with the --ini option.

PHP handlers and configuration files

CGI

The CGI handler executes PHP applications through the mod_cgi or the mod_cgid Apache modules.

The system only uses the values that the /opt/cpanel/ea-php##/root/etc/php.ini file or the .ini files in the /opt/cpanel/ea-php##/root/etc/php.d/ directory specify. The system reads these files in alphabetical order.

DSO

The DSO handler embeds the PHP language inside the Apache webserver. DSO allows you to use Apache directives (for example, the php_value and php_admin_value directives).

The system only uses the values that the /opt/cpanel/ea-php##/root/etc/php.ini file or the .ini files in the /opt/cpanel/ea-php##/root/etc/php.d/ directory specify. The system reads these files in alphabetical order.

FCGI Process Manager (FPM)

FastCGI serves PHP applications through the mod_proxy_fcgi Apache module.

The system loads the PHP INI values in the following order:

The values that the /opt/cpanel/ea-php##/root/etc/php.ini file or the .ini files in the /opt/cpanel/ea-php##/root/etc/php.d/ directory specify. The system reads these files in alphabetical order.
The /opt/cpanel/ea-php##/root/etc/php-fpm.conf file.

Note:

If a key that starts with php_admin_* exists, it will override the system default value or any previously found value.
The .conf files in the /opt/cpanel/ea-php##/root/etc/php-fpm.d/ directory.

Important:

Do not edit the /opt/cpanel/ea-php##/root/etc/php-fpm.conf file or the files in the /opt/cpanel/ea-php##/root/etc/php-fpm.d/ directory. If you wish to make changes, you must edit the PHP-FPM .yaml files.

For more information, read our PHP-FPM documentation.

FCGI daemon (FCGId)

FCGId serves PHP applications through the mod_fcgid Apache module. The mod_fcgid Apache module is an alternative to the mod_cgi Apache module.

Important:

You can only use FCGId with MultiPHP on systems that run cPanel & WHM version 74 or later.
On systems prior to cPanel & WHM version 78, if your default PHP version uses FCGId, then all PHP versions will use FCGId.

For more information, read our Apache Module: FCGId documentation.

LSAPI

LSAPI provides a fast and stable way to serve PHP applications. cPanel & WHM’s version of LSAPI differs from the one that CloudLinux provides. This version disables Checkpoint/Restore in Userspace (CRIU), connection pooling, and opcache preservation.

suPHP

This option provides the ability to run PHP scripts as the user with the mod_suphp Apache module.

The system uses the first instance of a directive that it finds. The system loads PHP INI directives in the following order:

Warning:

We strongly recommend that you allow your system to load the .ini files and directives as it finds them. This guarantees the most predictable results.
We strongly recommend that you do not specify a location for your .ini file with the [phprc_paths] section of the suphp.conf file, the suPHP_ConfigPath directive, or set the PHPRC environmental variable. Unexpected behavior may occur.

The .user.ini file that exists in the same directory as the PHP script.
Important:
- Do not set the user_ini.filename directive.
- If the system does not find a .user.ini file, it searches up the directory tree until finds one and uses that file as if it existed in the PHP file's directory.
- The system ignores directives that are not allowed in .user.ini files.
The php.ini file that exists in the same directory as the PHP script.
The .ini files in the PHP version’s /opt/cpanel/ea-php##/root/etc/php.d/ directory.

Note:

PHP scans the files in alphabetical order. To see the files that PHP loaded, you can run the php_ini_scanned_files() command or run PHP with the --ini option.
The PHP version’s global php.ini file.
The PHP default setting.

If you specified a location for your .ini file, the system does not load configurations in the /opt/cpanel/ea-php##/root/etc/php.d/ directory. Instead, it loads the settings in the php.ini file that the directive specifies. We strongly recommend that you do not specify the location of a php.ini file.

The presence of one of the following sets the location of .ini file that the system reads:

The suPHP_ConfigPath directive.
The [phprc_paths] section of the suphp.conf file.
If you set a file location with the PHPRC environmental variable.

Important:

We strongly recommend that you do not set the [phprc_paths] section, the suPHP_ConfigPath directive or set the PHPRC environmental variable. Unexpected behavior may occur.
If you specify the location of an .ini file, you must provide a complete .ini file. Run the following command to ensure that your users receive a complete php.ini file:

cat /opt/cpanel/ea-php##/root/etc/php.ini /opt/cpanel/ea-php##/root/etc/php.d/*.ini &gt; /path/to/specified/php.ini