Top Tips For A Seamless Update

Updating a business-critical piece of software like WHMCS can be  intimidating, but at WHMCS, we put a lot of effort into ensuring  updating WHMCS is as safe and straightforward as possible. We take a  great deal of care to reduce obstacles wherever possible, for example by  avoiding template changes in maintenance updates wherever possible, and  maintaining backwards compatibility with features and functionality for  as long as possible. In this article I'll share my top tips for making  sure a WHMCS update goes smoothly.

I've split these tips into four main sections;

  • Preparation:  Things to consider and prepare for before the update.
  • Testing: Things to be aware of and test prior to updating.
  • Execution: Tips for executing the update process on your production system.
  • Validation: And finally some recommended validation checks for once the update is complete.


It's  important to check that the requirements for the new version are met.  The latest system requirements are always available in our documentation.

If you intend to use the Automatic Updater, there are some additional system requirements  for that tool. Most importantly, ensure  there's enough free disk space, and that PHP open_basedir contains the entire WHMCS document root.

You should also consult the Release Notes.  Release Notes often contain important information about new features  and changes, as well as deprecation and removal notices and any template changes.

The next consideration is for custom  modules and third party extensions, including hooks. Each should be  checked for compatibility with the new version.

Review the WHMCS Marketplace  listing, which will be updated by individual vendors when support for a  new version is added. If yours is not listed in the Marketplace,  contact the vendors directly. An update may be required to these  extensions or modules.

Now let's consider system themes and order form templates. Always ensure that all your system theme and order form template customizations are contained within their own directory,  as any changes you make to the default themes and order form templates will likely be  overwritten.

The Release Notes contain a Template Changes section with links to our template repositories on Github. These repositories and the links we provide allow you to see visual differences of  the changes between two versions, making it easy to see the  changes you need to apply to custom system themes and order form templates.  

Because our system themes and order form templates are available on GitHub, you can leverage the power of Git to make the process of faster and reduce the  potential for human error. Our Customising templates...the easy way blog post has a step by step walkthrough to help you get started.

A  number of customizations can also be made with override files. Override files allow you to customise parts of the products in a way that is  safely preserved through the update process. For this reason we  recommend making the following customizations via override files. Click  on an item below to learn more.



It's a good idea to create an exact replica of your installation for testing purposes. This is useful both for testing out updates and testing new WHMCS features and your customizations. All direct license holders are entitled to a free second license for private testing and development purposes. If you don't already have one, you can request a development license by contacting our Customer Service team.

To create your test installation, create a full copy of the files and database. Remember to update the configuration.php file in your copy to use your development license key and new database credentials. You can then use this installation to test the update process, third-party addons or extensions, and templates on a separate development installation.

Often, you will want to ensure that the duplicate installation can't send emails or actually charge your customers. To do this, perform these actions:

Disable Email Sending

To do this, go to Configuration > System Settings > General Settings > Mail (Setup > General Settings > Mail prior to WHMCS 8.0).

  • For WHMCS 8.1 and later, toggle Disable Email Sending to ON. The system will log an error at Configuration > System Logs each time that you enable or disable this setting.
  • For WHMCS 8.0 and earlier, select SMTP as your Mail Provider (Mail Type in WHMCS 7.10 and earlier). Leave the SMTP credentials blank so that SMTP will fail.

Set Payment Gateways to Test Mode

To do this, go to Configuration > System Settings > Payment Gateways (Setup > Payments > Payment Gateways prior to WHMCS 8.0). Click Manage Existing Gateways and then check the appropriate checkbox (for example, Test Mode or Sandbox Mode) for each of your gateways.

Set Domain Registrars to Test Mode

To do this, gotoConfiguration > System Settings > Domain Registrars (Setup > Products/Services > Domain Registrars in WHMCS 8.0). Check the appropriate checkbox (for example,Test Mode or Sandbox Mode) for each of your registrars.

Disconnect from Live Servers

To do this, go to Configuration > System Settings > Servers (Setup > Products/Services > Servers prior to WHMCS 8.0)and invalidate the username and password credentials for each of your servers.

Now  you are ready to test the most important actions and functionality that  you use. Before we publish any new version, we run a whole suite of  automated and manual tests to ensure everything is working as we expect,  but differences in environments, setup configuration and customization can always impact the behaviour of a new version. Here are some of the  areas you should check:

  • The Admin Area: If some pages look broken; a hard refresh of browser or clearing browser cache usually fixes this.
  • The Client Area: Log in as a client and navigate to the service details and domain  details pages. Try submitting a ticket, remembering that, when masquerading as a  client, you won't receive a new ticket notification email.
  • The Order Process: Place a new order. In the admin area, mark it as paid, to ensure provisioning is triggering as expected.
  • Automation Tasks: At the daily automation settings time, look for the Cron Job  Activity Report email to confirm the automation tasks completed  successfully.

When finished, perform the update.


The first step in executing a successful update is to take backups.  Typically, you can use a web based tool such as phpMyAdmin, but you can also use mysqldump from the command line to  backup the WHMCS MySQL database.

Also make a copy of the entire WHMCS directory using your preferred method. This way, in the unlikely  event there is a problem, you can quickly revert your changes.

The update process will need to create and alter tables in the MySQL database. Make sure that the MySQL user has all available permissions granted for the duration of the update process.

The Automatic Updater  is typically the most successful method.  Using the Automatic Updater will download, validate, extract the new files, and update the database at once.

To do this, navigate to Utilities > Update WHMCS and click Update Now.  If the update was only recently released, you may need to click Check for Updates first.

The manual option is always available for power users. If you do decide to update this way, here are some tips:

  • Always  upload the full version distribution zip file and extract it directly on the server. Uploading individual files can take longer and it's easier for  files to be missed.
  • Ensure that all files upload, extract, and overwrite successfully. Permissions issues or lack of disk space are a  frequent cause of update failures.

For power users using the command line, the process might look something like:

mysqldump -u [username] -p [databaseName] >  whmcsdatabasebackup-$(date +%F).sqlmkdir  /home/whmcs/public_html/upgradestaging && cd  /home/whmcs/public_html/upgradestaging 
unzip /path/to/ 
cp /home/example/public_html/whmcs/configuration.php /home/example/public_html/upgradestaging/whmcs/ 
php -f home/example/public_html/upgradestaging/whmcs/install/bin/installer.php 
rm -rf /home/example/public_html/upgradestaging/whmcs/install/ 
mv /home/example/public_html/whmcs /home/example/public_html/whmcs_backup_xxxx-xx-xx/ 
mv /home/example/public_html/upgradestaging/whmcs/ /home/example/public_html/whmcs/ 
rm -rf /home/example/public_html/upgradestaging


When the update success message is displayed, you're nearly there. The  final step is to check everything is working as expected.

As before in the testing phase, we recommend testing key areas of  functionality such as can you login as a client, can you view product  details, can you submit a support ticket and can you place a new order.

I also recommend monitoring Configuration > System Health (Help > System Health Status prior to WHMCS 8.0) for any attention items in the following 24 hours.

If you follow the process outlined above, your chances for success when updating WHMCS are far higher.

Originally published on the WHMCS blog.