Automating PHP Version Management in cPanel with MultiPHP Manager and the API

Problem: Multiple PHP Runtimes on One cPanel Server

Shared or reseller hosting often runs dozens of sites that depend on different PHP versions. Legacy WordPress blogs might still need PHP 7.4, while a new micro‑service uses PHP 8.2. Manually toggling the PHP version in cPanel for each domain is tedious, error‑prone, and hard to audit. When a new server is provisioned or a patch is applied, the risk of mis‑configuring a site’s runtime grows.

MultiPHP Manager: A Centralized Per‑Domain Override

cPanel’s MultiPHP Manager sits in the main UI under “Software” and provides a table of all accounts and their current PHP versions. A global default is set at the top, but each domain can override it by dragging a PHP icon to the desired version. Internally, cPanel writes a php.ini snippet in /usr/local/etc/php-fpm.d that the PHP‑FPM pool reads at start‑up.

Key facts:

• Global default applies to accounts that have not set a per‑domain override.
• Overrides are stored in /usr/local/cpanel/php/ as php.ini fragments.
• Changing a version via the UI triggers an fpm‑reload to apply the new runtime.

Configuring PHP Versions via the cPanel UI

1. Log into the cPanel account or WHM as root.
2. Navigate to Software > MultiPHP Manager.
3. The table lists all domains. Hover over the PHP icon to see the current version.
4. Click the icon, drag it to the desired PHP version, and drop. The icon updates instantly.
5. Verify the change by visiting http://example.com/info.php where info.php contains phpinfo();.

While this works for a handful of sites, it does not scale. The next section shows how to script the same operation with the cPanel API.

Automating PHP Version Changes with the REST API

cPanel exposes a v3 RESTful API that lets you query and set the PHP version for any domain. The endpoint is: POST /api3/rest/server/php/version

Prerequisites:

• Root or WHM‑level API token. Create one via WHM > Manage API Tokens.
• cPanel version 11.70+ (API v3) – verify by requesting /api3/ from the server.
• Domain must be active and have a PHP‑FPM pool.

Example cURL command to set PHP 8.2 for example.com:

curl -k \
  -H "Authorization: cpanel root:YOUR_API_TOKEN" \
  -d "domain=example.com" \
  -d "php_version=8.2" \
  https://your-host.com:2083/execute/api3/rest/server/php/version

Explanation of parameters:

• domain – the fully qualified domain name.
• php_version – the target PHP major/minor string (e.g., 7.4, 8.0, 8.2).
• Root authentication is required; cPanel root:YOUR_API_TOKEN is the header format.

After the call, verify the change:

curl -k \
  -H "Authorization: cpanel root:YOUR_API_TOKEN" \
  https://your-host.com:2083/execute/api3/rest/server/php/version?domain=example.com

The JSON response will contain "php_version":"8.2" if the request succeeded. A non‑200 HTTP status or an error message indicates a problem (e.g., domain not found, unsupported PHP version, or insufficient privileges).

Performance Trade‑offs and Compatibility Risks

Upgrading to a newer PHP major release offers:

• Better performance via JIT (since PHP 8.0).
• Improved language features and security patches.
• Reduced memory footprint for some workloads.

But there are costs:

• Legacy extensions (e.g., mysql, gd older API) may be removed, causing runtime errors.
• Opcode caching (OPcache) is reset on version changes, potentially causing a temporary performance dip.
• Some applications rely on deprecated functions that were removed in PHP 8.0+. A quick phpinfo() check can reveal missing extensions.
• Security patches for the underlying OS packages must be kept current; a new PHP runtime can expose vulnerabilities if the system is not patched.

Because the API changes the runtime on the fly, a mis‑configured domain can crash the site until the code is updated. Always test in a staging environment before pushing to production.

Actionable Next Steps

1. Create a PHP version matrix. Document which applications require which PHP runtime. Store this in a shared spreadsheet or a simple YAML file.
2. Automate with a CI/CD pipeline. Use the API in a script that runs after a code merge to set the correct PHP version for the target domain. Add a unit test that verifies phpinfo() returns the expected version.
3. Schedule periodic reviews. Every quarter, run a script that queries all domains, compares the current version to the matrix, and flags mismatches.
4. Secure your API token. Store it in a vault (e.g., HashiCorp Vault, AWS Secrets Manager) and rotate it regularly.
5. Backup configuration. Before mass updates, back up /usr/local/cpanel/php and the FPM pool configuration files.

By leveraging MultiPHP Manager’s UI for quick manual changes and its API for bulk, auditable updates, you can keep a diverse set of PHP applications running smoothly while minimizing downtime and manual effort.