Difference between revisions of "PHP 7 Migration Guide"

From WHMCS Documentation
Line 1: Line 1:
−
Here's our 5 step guide for how to upgrade the PHP version your site hosting WHMCS is running.
+
The version of PHP that the server hosting your WHMCS installation runs is important in order to run WHMCS successfully.
  
−
This guide applies to upgrades from PHP 5.x to PHP 7.0, 7.1, 7.2 or 7.3.
+
<div class="docs-alert-success">
 +
* The steps below apply to upgrades from PHP 5 to PHP 7.0, 7.1, 7.2, and 7.3.
 +
* We recommend performing the steps below in the presented order for the best experience and a minimized risk of disruption or downtime.
 +
</div>
  
−
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.1 ==
  
−
==1. Install Ioncube Loader 10==
+
ionCube Loader 10.1 includes support for a bundled encoding feature. This allows us to encode files that are compatible with all currently-supported versions of PHP. WHMCS 7.5 and later require ionCube Loader 10.1.
  
−
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.
+
* For manual WHMCS updates, make certain that you install the most recent ionCube Loader version before you update.
 +
* For updates using the [[Automatic Updater]], WHMCS will automatically check for the necessary version of ionCube Loader before beginning the update and alert you if you must update ionCube Loader first.
  
−
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.
+
== 2. Upgrade to WHMCS 7.10 ==
  
−
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.
+
WHMCS 7.10 supports all currently-supported versions of PHP. It includes a utility to identify ionCube-encoded custom or third-party code that may not be compatible with newer versions of PHP.
  
−
==2. Upgrade to WHMCS 7.10==
+
For a full index of PHP compatibility by WHMCS version, see [[System Environment Guide#PHP|PHP Compatibility Guide]].
  
−
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.
+
== 3. Run the WHMCS PHP Version Compatibility Utility ==
  
−
WHMCS 7.4 or earlier is encoded with an ionCube encoding that only supports up to a maximum of PHP 7.0.x.
+
The PHP version compatibility utility in WHMCS 7.5 and later can identify ionCube-encoded custom or third-party code may not be compatible with newer versions of PHP. We recommend running this utility before any change you make to your system's PHP version.
  
−
For a full index of PHP compatibility by WHMCS Version, please refer to the [[System Environment Guide#PHP|PHP Compatibility Guide]].
+
You can find this utility at '''Utilities > System > [[PHP Version Compatibility]]'''.
  
−
==3. Run the WHMCS PHP Version Compatibility Utility==
+
== 4. Assert Compatibility of Custom and 3rd Party Code ==
  
−
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.
+
PHP 7 removed many [https://secure.php.net/manual/en/migration70.deprecated.php deprecated functions] and you must remove those from older code in order to prevent runtime errors. Additional changes in [http://php.net/manual/en/migration71.php PHP 7.1] and [http://php.net/manual/en/migration72.php PHP 7.2] may also affect older code.
  
−
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.
+
* Manually verify this in any code that you wrote or customized.
 +
* Check with third-party vendors to ensure that their code is compatible with the version of PHP that you want to use. Often, third-party vendors have already released updates to ensure this compatibility.
  
−
We recommend running this tool prior to any change of PHP Version on your system.
+
== 5. Upgrade PHP ==
  
−
More information on this tool and how to use it can be found in the documentation for the [[PHP Version Compatibility Assessment]] utility.
+
Before you upgrade PHP, make '''certain''' that:
  
−
==4. Assert Compatibility of Custom and 3rd Party Code==
+
* You have the necessary ionCube Loader version for your target PHP version.
 +
* You have a version of WHMCS that supports your target PHP version.
 +
* Any ionCube-encoded custom or third-party code's encoding is compatible with your target PHP version.
 +
* Any custom or third-party code is compatible with your target PHP version.
  
−
PHP 7 dropped many [https://secure.php.net/manual/en/migration70.deprecated.php deprecated functions] that must be removed from older code to prevent runtime errors. As well, there are a few notable changes specific to [http://php.net/manual/en/migration71.php PHP 7.1] and [http://php.net/manual/en/migration72.php PHP 7.2] that may also affect older code.
+
Then, proceed to upgrade the PHP version your site is running:
  
−
* For any code you have authored, you will need to manually verify this.  
+
* If you run cPanel & WHM and EasyApache 4, you can switch the version of PHP your site is running using '''[https://docs.cpanel.net/cpanel/software/multiphp-manager-for-cpanel/ MultiPHP]''' in your cPanel control panel.
−
* 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.
+
* For other control panels or systems, consult the vendor's documentation.
  
−
==5. Upgrade PHP==
+
== Errors ==
  
−
If you've completed steps 1-4, you should now have asserted the following:
+
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:
−
 
 
−
* 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 [https://documentation.cpanel.net/display/68Docs/MultiPHP+Manager+for+cPanel 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 500 internal server error
Line 59: Line 54:
 
* An oops error 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 help, see [[PHP 7 Migration Troubleshooting Guide]]. For an immediate solution, revert to the previous PHP version should allow you to regain access to the WHMCS system.
−
 
 
−
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''
 
''Last Updated: March 2020''

Revision as of 18:10, 27 April 2022

The version of PHP that the server hosting your WHMCS installation runs is important in order to run WHMCS successfully.

  • The steps below apply to upgrades from PHP 5 to PHP 7.0, 7.1, 7.2, and 7.3.
  • We recommend performing the steps below in the presented order for the best experience and a minimized risk of disruption or downtime.

1. Install ionCube Loader 10.1

ionCube Loader 10.1 includes support for a bundled encoding feature. This allows us to encode files that are compatible with all currently-supported versions of PHP. WHMCS 7.5 and later require ionCube Loader 10.1.

  • For manual WHMCS updates, make certain that you install the most recent ionCube Loader version before you update.
  • For updates using the Automatic Updater, WHMCS will automatically check for the necessary version of ionCube Loader before beginning the update and alert you if you must update ionCube Loader first.

2. Upgrade to WHMCS 7.10

WHMCS 7.10 supports all currently-supported versions of PHP. It includes a utility to identify ionCube-encoded custom or third-party code that may not be compatible with newer versions of PHP.

For a full index of PHP compatibility by WHMCS version, see PHP Compatibility Guide.

3. Run the WHMCS PHP Version Compatibility Utility

The PHP version compatibility utility in WHMCS 7.5 and later can identify ionCube-encoded custom or third-party code may not be compatible with newer versions of PHP. We recommend running this utility before any change you make to your system's PHP version.

You can find this utility at Utilities > System > PHP Version Compatibility.

4. Assert Compatibility of Custom and 3rd Party Code

PHP 7 removed many deprecated functions and you must remove those from older code in order to prevent runtime errors. Additional changes in PHP 7.1 and PHP 7.2 may also affect older code.

  • Manually verify this in any code that you wrote or customized.
  • Check with third-party vendors to ensure that their code is compatible with the version of PHP that you want to use. Often, third-party vendors have already released updates to ensure this compatibility.

5. Upgrade PHP

Before you upgrade PHP, make certain that:

  • You have the necessary ionCube Loader version for your target PHP version.
  • You have a version of WHMCS that supports your target PHP version.
  • Any ionCube-encoded custom or third-party code's encoding is compatible with your target PHP version.
  • Any custom or third-party code is compatible with your target PHP version.

Then, proceed to upgrade the PHP version your site is running:

  • If you run cPanel & WHM and EasyApache 4, you can switch the version of PHP your site is running using MultiPHP in your cPanel control panel.
  • For other control panels or systems, consult the vendor's documentation.

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 7 Migration Troubleshooting Guide. For an immediate solution, revert to the previous PHP version should allow you to regain access to the WHMCS system.

Last Updated: March 2020

Retrieved from "http://3.17.75.209/index.php?title=PHP_7_Migration_Guide&oldid=32451"