Tips For Successful Updates

At WHMCS, we work to ensure that updates are safe and straightforward. To reduce obstacles and the potential for problems, we take steps like avoiding template changes in maintenance updates and maintaining backwards compatibility with features and functionality.

When you choose to update WHMCS, we recommend following the process below. This will help you avoid many issues and help ensure success.

Preparing for Updates

Always consult the desired version's release notes. They contain important information about new features, changes, deprecations or removals, and template changes.

Before an update, check that your system meets all of the new version's requirements:

  • Does your system meet the version's documented system requirements?
  • If you want to use the Automatic Updater, does your system meet the utility's additional system requirements?
  • Do you have enough available disk space?
  • Does the PHP open_basedir directive contain the entire WHMCS document root?
  • For any extensions or modules that you use, do the related WHMCS Marketplace listings indicate compatibility? You may need to contact the vendor or developer for confirmation.

If you use custom system themes or order form templates, make certain that these exist within their own directories. Updates will often overwrite changes that you make to the default themes or templates.

You can find information about template changes and links to view those changes in our GitHub® template repositories in the desired version's release notes.

We recommend using Git™ to update most customizations, including custom themes and order form templates. However, we recommend using override files to make the following customizations:

Testing Before Production

We recommend creating an exact replica of your installation for testing the update process, third-party addons or extensions, and templates on a separate development installation. WHMCS staff performs comprehensive automated and manual testing before releasing new code,  but differences in environments, setup configuration, and customization can always impact the behavior of a new version.

To create your test installation, create a full copy of the files and database and update the configuration.php file to use your development license key and new database credentials.

If you buy your license directly from WHMCS, you can contact our Customer Service team for a free testing and development license.

Before you begin testing, you should make certain that this testing installation can't send emails or actually charge your customers.

To do this:

  1. To prevent sending emails:
    1. Go to the Mail tab at Configuration > System Settings > General Settings (Setup > General Settings prior to WHMCS 8.0).
    2. Perform the appropriate action for your WHMCS version:
      • 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.
  2. To prevent charging customers:
    1. Go to Configuration > System Settings > Payment Gateways (Setup > Payments > Payment Gateways prior to WHMCS 8.0).
    2. Click Manage Existing Gateways.
    3. Check the appropriate checkbox (for example, Test Mode or Sandbox Mode) for each of your gateways.
  3. To prevent domain registrations:
    1. Go to Configuration > System Settings > Domain Registrars (Setup > Products/Services > Domain Registrars in WHMCS 8.0).
    2. Check the appropriate checkbox (for example,Test Mode or Sandbox Mode) for each of your registrars.
  4. To prevent automation from accessing your servers:
    1. Go to Configuration > System Settings > Servers (Setup > Products/Services > Servers prior to WHMCS 8.0).
    2. Invalidate the username and password credentials for each of your servers.

When you are ready, you can start testing the features in WHMCS that you use the most. We recommend checking:

  • The Admin Area
    Log in as an admin and use the interface. 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 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.

Creating Backups

You should always create backups before applying any update.

Before you update, create backups of the WHMCS database and the entire WHMCS directory. If you experience problems while updating, doing this will allow you to quickly revert your changes.

You can use a tool like phpMyAdmin for creating database backups. You can also use mysqldump from the command line to back up the WHMCS MySQL® database.

Updating WHMCS

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

The Automatic Updater utility is typically the most successful method. It  downloads, validates, and extracts the new files and updates the database in one process.

To use this, navigate to Utilities > Update WHMCS and click Update Now.  If the update is a recent release, you may need to click Check for Updates first.

For Advanced Users

The manual option is always available for advanced users.

  • Always upload the full version distribution file and extract it directly on the server. Uploading individual files can take longer and is prone to errors.
  • Ensure that all files upload, extract, and overwrite successfully. Permissions issues or lack of disk space are frequent causes of update failures.

On the command line, the process might look like the following example: 

mysqldump -u [username] -p [databaseName] >  whmcsdatabasebackup-$(date +%F).sqlmkdir  /home/whmcs/public_html/upgradestaging && cd  /home/whmcs/public_html/upgradestaging 
unzip /path/to/whmcs_v770_full.zip 
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
Click to copy

Validating Success

After the update success message displays, check to ensure that WHMCS is working properly.

We recommend testing all of the important features and functions in WHMCS, like logging in as a client and as an admin, viewing products, submitting support tickets, and placing new orders.

We also recommend monitoring the alert messages at Configuration > System Health (Help > System Health Status prior to WHMCS 8.0) for the following 24 hours.

Update Service: Have our team upgrade your installationServices