cPanel MultiPHP Manager: Per-Domain PHP Versions and PHP-FPM Setup

The Problem: One Server, Multiple PHP Requirements

Shared hosting servers routinely host legacy applications that require PHP 7.4 alongside modern Laravel or WordPress sites that need PHP 8.2 or 8.3. Running a single server-wide PHP version forces either an insecure downgrade or a risky mass upgrade. cPanel's MultiPHP Manager solves this by letting each domain select its own EasyApache 4 PHP package and handler—suPHP, CGI, or PHP-FPM—without manual Apache edits.

How MultiPHP Routes Requests to the Chosen PHP Version

EasyApache 4 installs multiple PHP packages side-by-side (e.g., ea-php74, ea-php81, ea-php82, ea-php83). When you assign a version to a domain in WHM > MultiPHP Manager (or the cPanel per-account interface), cPanel writes a per-vhost configuration fragment in /etc/apache2/conf.d/userdata/ssl/2_4/<user>/<domain>/ that sets the handler. For PHP-FPM, the fragment contains a ProxyPassMatch directive pointing to the domain's dedicated FPM socket (e.g., unix:/opt/cpanel/ea-php82/root/usr/var/run/php-fpm/<user>.sock). Apache then forwards matching .php requests to that socket instead of invoking a global PHP interpreter.

Each cPanel account gets its own FPM pool configuration under the selected PHP version's php-fpm.d directory (e.g., /opt/cpanel/ea-php82/root/etc/php-fpm.d/<user>.conf). The pool runs as the cPanel user, so opcode caches (OPcache) stay warm per user and memory accounting is isolated.

Worked Example: Assign PHP 8.2 with PHP-FPM to example.com

1. Log in to WHM as root.
2. Navigate to MultiPHP Manager (Home > Software > MultiPHP Manager).
3. In the System PHP Version table, locate example.com (or the target domain).
4. Check the checkbox for that domain, then select ea-php82 from the PHP Version dropdown and click Apply.
5. Still in MultiPHP Manager, switch to the PHP-FPM tab. Find example.com, enable the toggle, and click Save.
6. cPanel rebuilds the Apache configuration and writes the FPM pool file. Verify the pool exists:

   ls -l /opt/cpanel/ea-php82/root/etc/php-fpm.d/ | grep example

7. Confirm the pool runs as the correct user:

   ps aux | grep php-fpm | grep example

   You should see a master process and worker processes owned by the cPanel account user, not root.
8. Create a phpinfo.php in the domain's document root and load it in a browser. Verify PHP Version shows 8.2.x and Server API reads FPM/FastCGI.

Tuning FPM Pool Settings for Shared Hosting

The default pool settings are conservative. On busy servers, the two knobs that matter most are pm.max_children and pm.max_requests. Edit the pool file directly (or use WHM > MultiPHP Manager > PHP-FPM > Edit for the domain):

; /opt/cpanel/ea-php82/root/etc/php-fpm.d/example.com.conf
pm = dynamic
pm.max_children = 50
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 10
pm.max_requests = 500

pm.max_children caps concurrent PHP workers. Each worker consumes roughly 30–60 MB with OPcache enabled. On a 4 GB VPS hosting 30 accounts, setting pm.max_children = 50 per account would allow 1,500 workers—far exceeding physical memory. A safer starting point is 10–15 per account on small instances; monitor pm.status_path or systemctl status ea-php82-php-fpm for max children reached warnings before raising it.

pm.max_requests recycles workers after N requests to mitigate memory leaks in third-party extensions. 500 is a reasonable baseline; increase to 1000 if you see excessive respawn overhead in logs.

Common Mistakes That Break MultiPHP

1. .htaccess Handler Overrides

Legacy .htaccess lines like AddHandler application/x-httpd-php74 .php or SetHandler proxy:unix:/path/to/socket|fcgi://localhost conflict with MultiPHP's generated vhost fragments. The result is either a 500 error or the domain silently falling back to the system default PHP. Remove all manual PHP handler directives from .htaccess and let MultiPHP manage routing.

2. Pinning to End-of-Life PHP Packages

cPanel periodically removes EOL EasyApache 4 packages (e.g., ea-php73, ea-php74) from repositories. A domain pinned to a removed package will either fail to start FPM or fall back to the system default after an yum update or EasyApache 4 rebuild. Before updating, run /usr/local/cpanel/scripts/easyapache4 --check to see which PHP versions are still available, and migrate affected domains to a supported version first.

3. Over-Enabling PHP-FPM on Memory-Constrained VPS

Each FPM pool reserves memory for its master process and idle workers even when the site receives zero traffic. On a 1–2 GB VPS with 20+ accounts, enabling FPM everywhere can starve MySQL or the OS. Use suPHP or CGI for low-traffic legacy sites; reserve FPM for high-concurrency applications. Check current memory pressure with free -h and ps aux --sort=-%mem | head -20 before enabling FPM globally.

4. Editing Apache Config or Userdata Manually

Files under /etc/apache2/conf.d/userdata/ and /var/cpanel/userdata/ are managed by cPanel. Manual edits are overwritten by /scripts/rebuildhttpdconf, /scripts/rebuildphpconf, or nightly upcp runs. If you must adjust a setting not exposed in the UI, use the appropriate cPanel hook or the MultiPHP INI Editor (WHM > Software > MultiPHP INI Editor) for per-version php.ini values like memory_limit or upload_max_filesize.

Verification Checklist After Changes

• In WHM MultiPHP Manager, confirm the domain shows the intended ea-phpXX version and the PHP-FPM toggle is On.
• Load a phpinfo() page on the domain; verify PHP Version and Server API: FPM/FastCGI.
• Inspect the generated pool file: cat /opt/cpanel/ea-phpXX/root/etc/php-fpm.d/<user>.conf — confirm user = <cpanel-user> and listen = /opt/cpanel/ea-phpXX/root/usr/var/run/php-fpm/<user>.sock.
• After any EasyApache 4 update (yum update ea-php* or WHM > EasyApache 4 > Run), re-test one domain per PHP version to catch silent fallbacks.

Limitations and When to Avoid MultiPHP

• No per-directory PHP versions. MultiPHP operates at the vhost (domain/subdomain) level. You cannot run PHP 7.4 in /legacy and PHP 8.3 in /app under the same domain.
• PHP-FPM pools add baseline memory overhead. Each pool's master process consumes ~10–15 MB idle. On dense shared servers, this can exceed the memory saved by dropping suPHP.
• Version changes require Apache reload. Switching a domain's PHP version triggers a graceful Apache restart, momentarily affecting all sites on the server.
• Custom PHP extensions must be installed per ea-php version. If an application needs imagick or redis, install the matching ea-phpXX-php-imagick package for each PHP version in use.

Practical Way to Confirm It Works

Create a test script public_html/phpver.php:

<?php
echo 'PHP Version: ' . PHP_VERSION . "\n";
echo 'Server API: ' . php_sapi_name() . "\n";
echo 'FPM Pool User: ' . get_current_user() . "\n";
?>

Request it via curl -s https://example.com/phpver.php. Output should match the version selected in MultiPHP Manager, show FPM/FastCGI, and report the cPanel account username—not nobody or root.