Difference between revisions of "PHP Upgrade Guide"
(→Before you upgrade) |
|||
| (2 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
| − | In order to comply with each version's requirements, you must sometimes upgrade the PHP version on your WHMCS installation's server. | + | The version of PHP that the server hosting your WHMCS installation runs is important in order to run WHMCS successfully. In order to comply with each version's requirements, you must sometimes upgrade the PHP version on your WHMCS installation's server. |
| + | |||
| + | * WHMCS 8.0 and higher requires PHP 7.2 or later. You won't see WHMCS 8.0 in the [[Automatic Updater]] if you do not run PHP 7.2 or PHP 7.3. | ||
| + | * We recommend upgrading to PHP 7.4 after you successfully upgrade to WHMCS 8.0. WHMCS 8.0 introduced PHP 7.4 support. For more information, see [[Updating]]. | ||
| + | * For more information about PHP support in WHMCS versions, see [[PHP Version Compatibility]]. | ||
| − | + | <div class="docs-alert-success"> | |
| − | + | We recommend performing all of the tasks below in the presented order for the best experience and a minimized risk of disruption or downtime. | |
| − | + | </div> | |
| − | + | ||
| + | == Upgrading PHP == | ||
| + | |||
| + | When you upgrade PHP on the server that hosts your WHMCS installation, you will need to perform the following tasks: | ||
| + | |||
| + | # Ensure ionCube Loader® compatibility. | ||
| + | # Ensure ionCube-encoded file compatibility. | ||
| + | # Ensure custom and third-party code compatibility. | ||
| + | # If necessary for the new PHP version, upgrade to a compatible WHMCS version. | ||
| + | # Upgrade PHP. | ||
| + | # Make additional configuration updates. | ||
| + | |||
| + | See the sections below for more information on each step. | ||
| + | |||
| + | === Ensure ionCube Loader Compatibility === | ||
| + | |||
| + | ionCube Loader includes support for a bundled encoding feature that WHMCS uses to encode its files. If you use the [[Automatic Updater]], WHMCS will not allow you to begin upgrading WHMCS until you are using the necessary version of ionCube Loader. | ||
| + | |||
| + | You must install the correct ionCube Loader version for your desired version of WHMCS '''before''' you update: | ||
| + | |||
| + | {{:IonCube Loader Version Matrix}} | ||
| + | |||
| + | We recommend using the most recent compatible ionCube Loader version. | ||
| + | |||
| + | === Ensure ionCube-Encoded File Compatibility === | ||
| + | |||
| + | Go to '''Utilities > System > [[PHP Version Compatibility]]''' to locate any ionCube-encoded files that won't work with a higher version. | ||
| + | |||
| + | WHMCS does not control these files but, if their encoding is incompatible with your environment, they may negatively affect WHMCS. Make certain that you update these files to ensure compatibility before continuing. | ||
| + | |||
| + | === Ensure Custom and Third-Party Compatibility === | ||
| − | + | New PHP versions may introduce changes or remove [https://secure.php.net/manual/en/migration70.deprecated.php deprecated functions]. | |
| − | + | To reduce issues, manually verify your custom code and check with third-party vendors to ensure that their code is compatible your desired PHP version. Often, third-party vendors have already released updates to ensure this compatibility. | |
| + | |||
| + | See PHP's documentation for more information about changes in each PHP version: | ||
| + | |||
| + | * [https://www.php.net/manual/en/migration70.php PHP 7.0] | ||
| + | * [http://php.net/manual/en/migration71.php PHP 7.1] | ||
| + | * [http://php.net/manual/en/migration72.php PHP 7.2] | ||
| + | * [https://www.php.net/manual/en/migration73.php 7.3] | ||
| + | * [https://www.php.net/manual/en/migration74.php 7.4] | ||
| + | * [https://www.php.net/manual/en/migration80.php 8.0] <div class="docs-alert-warning">WHMCS does not support PHP 8.0. However, changes for PHP 8.0 may impact custom and third-party code.</div> | ||
| + | * [https://www.php.net/manual/en/migration81.php 8.1] | ||
| − | + | === Upgrade to a Compatible WHMCS Version === | |
| − | |||
| − | |||
| − | + | If your current WHMCS version does not support the desired new version of PHP, upgrade WHMCS to a version that does. | |
| − | + | You can do this using the '''[[Automatic Updater]]''' utility at '''Utilities > Update WHMCS''' or by [https://go.whmcs.com/1709/Updating-WHMCS-Manually performing an update manually]. | |
| + | |||
| + | For a full index of PHP compatibility by WHMCS version, see [[System Environment Guide#PHP|System Environment Guide]]. | ||
<div class="docs-alert-warning"> | <div class="docs-alert-warning"> | ||
| − | + | After you do this, ensure that your ionCube Loader version is still up-to-date and that there are not additional items to address at '''Utilities > System > [[PHP Version Compatibility]]'''. | |
</div> | </div> | ||
| − | + | === Upgrade PHP === | |
| + | |||
| + | Before you upgrade PHP, make '''certain''' that: | ||
| + | |||
| + | * You have the necessary ionCube Loader version for your target PHP version. | ||
| + | * You are running [[PHP_Version_Support_Matrix|a version of WHMCS that supports your target PHP version]]. | ||
| + | * Any custom or third-party code (and its encoding, if applicable) is compatible with your target PHP version. | ||
| + | |||
| + | Then, proceed to upgrade the PHP version your site is running. | ||
| + | |||
| + | If you use cPanel & WHM and EasyApache 4 to host your WHMCS installation, you can use '''[https://docs.cpanel.net/cpanel/software/multiphp-manager-for-cpanel/ MultiPHP Manager]''' and '''[https://docs.cpanel.net/cpanel/software/multiphp-ini-editor-for-cpanel/ MultiPHP INI Editor]''' to change your PHP version. | ||
| + | * For steps, see [https://help.whmcs.com/m/updating/l/1309170-how-to-upgrade-php-for-whmcs-using-cpanel-multiphp Upgrade Using cPanel MultiPHP]. | ||
| + | * For other control panels or systems, consult the vendor's documentation. | ||
| − | + | === Make Additional Configuration Updates === | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | After upgrading PHP, you may need to update your configuration to reflect the change. These changes depend on the configuration you choose for your WHMCS installation and any customizations that you use. | |
| + | For example, some WHMCS installations may require updates to the cron configuration and editing the cron's <tt>php.ini</tt> file. | ||
| + | |||
==Errors== | ==Errors== | ||
| − | + | ||
| − | + | If you experience any of the following error conditions when visiting a URL in WHMCS, there may be compatibility issues with your new PHP version: | |
| − | + | ||
* A 500 internal server error | * A 500 internal server error | ||
* A blank page | * A blank page | ||
* An oops error page | * An oops error page | ||
| − | + | ||
| − | + | For help, see [[PHP Upgrade Troubleshooting Guide]]. For an immediate solution, reverting to the previous PHP version should allow you to regain access to the WHMCS system. | |
Latest revision as of 18:01, 23 November 2022
The version of PHP that the server hosting your WHMCS installation runs is important in order to run WHMCS successfully. In order to comply with each version's requirements, you must sometimes upgrade the PHP version on your WHMCS installation's server.
- WHMCS 8.0 and higher requires PHP 7.2 or later. You won't see WHMCS 8.0 in the Automatic Updater if you do not run PHP 7.2 or PHP 7.3.
- We recommend upgrading to PHP 7.4 after you successfully upgrade to WHMCS 8.0. WHMCS 8.0 introduced PHP 7.4 support. For more information, see Updating.
- For more information about PHP support in WHMCS versions, see PHP Version Compatibility.
We recommend performing all of the tasks below in the presented order for the best experience and a minimized risk of disruption or downtime.
Contents
Upgrading PHP
When you upgrade PHP on the server that hosts your WHMCS installation, you will need to perform the following tasks:
- Ensure ionCube Loader® compatibility.
- Ensure ionCube-encoded file compatibility.
- Ensure custom and third-party code compatibility.
- If necessary for the new PHP version, upgrade to a compatible WHMCS version.
- Upgrade PHP.
- Make additional configuration updates.
See the sections below for more information on each step.
Ensure ionCube Loader Compatibility
ionCube Loader includes support for a bundled encoding feature that WHMCS uses to encode its files. If you use the Automatic Updater, WHMCS will not allow you to begin upgrading WHMCS until you are using the necessary version of ionCube Loader.
You must install the correct ionCube Loader version for your desired version of WHMCS before you update:
| WHMCS Version (Status) | PHP v5.2 | PHP v5.3 | PHP v5.4 | PHP v5.6 | PHP v7.0 | PHP v7.1 | PHP v7.2 | PHP v7.3 | PHP v7.4 | PHP v8.1 |
|---|---|---|---|---|---|---|---|---|---|---|
| v6.3 (EOL) | 4.6.1 | 4.6.1 | 4.6.1 | 4.6.1 | -- | -- | -- | -- | -- | -- |
| v7.0 (EOL) | -- | -- | -- | 5.0.21 | 6.0.2 | -- | -- | -- | -- | -- |
| v7.1 (EOL) | -- | -- | -- | 5.0.21 | 6.0.2 | -- | -- | -- | -- | -- |
| v7.2 (EOL) | -- | -- | -- | 5.0.21 | 6.0.2 | -- | -- | -- | -- | -- |
| v7.3 (EOL) | -- | -- | -- | 5.0.21 | 6.0.2 | -- | -- | -- | -- | -- |
| v7.4 (EOL) | -- | -- | -- | 5.0.21 | 6.0.2 | -- | -- | -- | -- | -- |
| v7.5 (EOL) | -- | -- | -- | 10.1.0 | 10.1.0 | 10.1.0 | 10.2.0 | -- | -- | -- |
| v7.6 (EOL) | -- | -- | -- | 10.1.0 | 10.1.0 | 10.1.0 | 10.2.0 | 10.3.1 | -- | -- |
| v7.7 (EOL) | -- | -- | -- | 10.1.0 | 10.1.0 | 10.1.0 | 10.2.0 | 10.3.1 | -- | -- |
| v7.8 (EOL) | -- | -- | -- | 10.1.0 | 10.1.0 | 10.1.0 | 10.2.0 | 10.3.1 | -- | -- |
| v7.9 (EOL) | -- | -- | -- | 10.1.0 | 10.1.0 | 10.1.0 | 10.2.0 | 10.3.1 | -- | -- |
| v7.10 (EOL) | -- | -- | -- | 10.1.0 | 10.1.0 | 10.1.0 | 10.2.0 | 10.3.1 | -- | -- |
| v8.0 (EOL) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | -- |
| v8.1 (EOL) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | -- |
| v8.2 (EOL) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | -- |
| v8.3 (EOL) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | -- |
| v8.4 (EOL) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | -- |
| v8.5 (EOL) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | -- |
| v8.6 (EOL) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | 12.0.1 |
| v8.7 (EOL) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | 12.0.1 |
| v8.8 (LTS) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | 12.0.1 |
| v8.9 (LTS) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | 12.0.1 |
| v8.10 (Active) | -- | -- | -- | -- | -- | -- | 10.2.0 | 10.3.1 | 10.4.3 | 12.0.1 |
We recommend using the most recent compatible ionCube Loader version.
Ensure ionCube-Encoded File Compatibility
Go to Utilities > System > PHP Version Compatibility to locate any ionCube-encoded files that won't work with a higher version.
WHMCS does not control these files but, if their encoding is incompatible with your environment, they may negatively affect WHMCS. Make certain that you update these files to ensure compatibility before continuing.
Ensure Custom and Third-Party Compatibility
New PHP versions may introduce changes or remove deprecated functions.
To reduce issues, manually verify your custom code and check with third-party vendors to ensure that their code is compatible your desired PHP version. Often, third-party vendors have already released updates to ensure this compatibility.
See PHP's documentation for more information about changes in each PHP version:
- PHP 7.0
- PHP 7.1
- PHP 7.2
- 7.3
- 7.4
- 8.0 WHMCS does not support PHP 8.0. However, changes for PHP 8.0 may impact custom and third-party code.
- 8.1
Upgrade to a Compatible WHMCS Version
If your current WHMCS version does not support the desired new version of PHP, upgrade WHMCS to a version that does.
You can do this using the Automatic Updater utility at Utilities > Update WHMCS or by performing an update manually.
For a full index of PHP compatibility by WHMCS version, see System Environment Guide.
After you do this, ensure that your ionCube Loader version is still up-to-date and that there are not additional items to address at Utilities > System > PHP Version Compatibility.
Upgrade PHP
Before you upgrade PHP, make certain that:
- You have the necessary ionCube Loader version for your target PHP version.
- You are running a version of WHMCS that supports your target PHP version.
- Any custom or third-party code (and its encoding, if applicable) is compatible with your target PHP version.
Then, proceed to upgrade the PHP version your site is running.
If you use cPanel & WHM and EasyApache 4 to host your WHMCS installation, you can use MultiPHP Manager and MultiPHP INI Editor to change your PHP version.
- For steps, see Upgrade Using cPanel MultiPHP.
- For other control panels or systems, consult the vendor's documentation.
Make Additional Configuration Updates
After upgrading PHP, you may need to update your configuration to reflect the change. These changes depend on the configuration you choose for your WHMCS installation and any customizations that you use.
For example, some WHMCS installations may require updates to the cron configuration and editing the cron's php.ini file.
Errors
If you experience any of the following error conditions when visiting a URL in WHMCS, there may be compatibility issues with your new PHP version:
- A 500 internal server error
- A blank page
- An oops error page
For help, see PHP Upgrade Troubleshooting Guide. For an immediate solution, reverting to the previous PHP version should allow you to regain access to the WHMCS system.