Revision as of 17:16, 11 November 2021

Here's our 5 step guide for how to upgrade the PHP version your site hosting WHMCS is running.

This guide applies to upgrades from PHP 5.x to PHP 7.0, 7.1, 7.2 or 7.3.

We recommend performing the steps below in the order listed for the most optimal experience. In most cases this will allow you to make the transition with minimal disruption or downtime to your system or workflows.

1. Install Ioncube Loader 10

ionCube Loader 10.1 includes support for a new bundled encoding feature from ionCube that makes it possible to encode files in a way that is compatible for all currently supported versions of PHP.

WHMCS 7.5 and later require at least ionCube Loader 10.1. If you intend to update WHMCS manually, you should ensure you have the latest loaders from ionCube installed prior to updating.

If you are using the automatic updater, you don't need to take any pre-update action. The WHMCS update utility will automatically validate and ensure you have the necessary version of ionCube before allowing the update to commence. If you do not, it will alert you that you need to upgrade ionCube before continuing.

2. Upgrade to WHMCS 7.10

WHMCS 7.10 supports all currently supported versions of PHP, giving you the widest possible choice of PHP Versions. It also includes a utility designed to help you identify any custom or 3rd party code that is encoded with ionCube and may not be compatible with newer versions of PHP.

WHMCS 7.4 or earlier is encoded with an ionCube encoding that only supports up to a maximum of PHP 7.0.x.

For a full index of PHP compatibility by WHMCS Version, please refer to the PHP Compatibility Guide.

3. Run the WHMCS PHP Version Compatibility Utility

Available in WHMCS 7.5 and later, the PHP Version Compatibility Utility can help in identifying custom and 3rd party files which are encoded with ionCube and may not be compatible with newer versions of PHP.

Accessed via the Utilities > System sub-menu, this tool will determine what versions of PHP an ionCube encoded file can work with where possible, and therefore allow you to proactively identify any custom or 3rd party code which may need updating prior to upgrading your PHP version.

We recommend running this tool prior to any change of PHP Version on your system.

More information on this tool and how to use it can be found in the documentation for the PHP Version Compatibility Assessment utility.

4. Assert Compatibility of Custom and 3rd Party Code

PHP 7 dropped many deprecated functions that must be removed from older code to prevent runtime errors. As well, there are a few notable changes specific to PHP 7.1 and PHP 7.2 that may also affect older code.

• For any code you have authored, you will need to manually verify this.
• For any code you use from 3rd party vendors, you should check with the vendor that any code you use is compatible with the version of PHP you wish to upgrade to. In many cases, you may find that 3rd party vendors have already released updates that are designed to ensure compatibility with newer PHP versions.

5. Upgrade PHP

If you've completed steps 1-4, you should now have asserted the following:

• That you have the necessary ionCube loaders for your target PHP version
• That you have a version of WHMCS that supports your target PHP version
• That any custom or 3rd party code that is encoded with ionCube is encoded in such a way as to be compatible with your target PHP version
• That any custom or 3rd party code is compatible with your target PHP version

With those assertions complete, you should now be able to proceed to upgrade the PHP version your site is running with minimal risks.

If you're running cPanel and EasyApache 4, you can switch the version of PHP your site is running using the MultiPHP selector feature found inside your cPanel control panel.

For other control panels or systems, please consult the vendors documentation.

If after upgrading PHP to a newer version, you experience any of the following error conditions when visiting any URL within WHMCS:

• A 500 internal server error
• A blank page
• An oops error page

This indicates there is an incompatibility with the newly selected PHP version. Please see our PHP 7 Migration Troubleshooting Guide for steps to debug and resolve these issues.

For an immediate solution, reverting to the previously installed and used PHP version should allow you to re-gain access to the WHMCS system.

Last Updated: March 2020