Guides & TutorialsInstalling WHMCSSystem ConfigurationSetting Up a Development and Testing Environment

Setting Up a Development and Testing Environment

Creating a testing and development environment will let you verify all of your customizations without any changes to your production system. This helps to protect your data and customizations.

We recommend setting this up before you upgrade WHMCS and whenever you write modules, themes, or other customizations.

Make sure to also perform basic steps like creating a full backup and checking our release notes for changes before upgrading.

1. Get a Development License

Contact WHMCS Customer Service to get a development license. 

  • You can get one free development license for every active license that you purchase directly from whmcs.com. 
  • If you purchase your WHMCS license through a reseller, you will need to buy the development license.

The addons for your paid license will be available in your test installation, with the exception of Live Chat. Installations using this type of license must be private and must return a Forbidden error or login prompt if accessed.

2. Meet the System Requirements

Your testing and development environment should meet the same system requirements as a production installation. 

3. Duplicate your WHMCS Installation

For the most accurate results, your installation should be identical to your production setup, with the same data and configuration.

There are several methods to duplicate your installation. The method that you use will depend on many factors, including the hosting control panel you use.

If you're using cPanel, copy your WHMCS installation in the File Manager interface:

  1. Log in to cPanel and go to Files >> File Manager.
  2. Select the folder for your production installation.
  3. Click Copy.
  4. Enter the new location (the location of your development installation).
  5. Edit the configuration.php file in your development environment to reflect the new location.

4. Duplicate your Database

You must also duplicate the data that WHMCS operates on. This means creating a second database, exporting the existing database, and then importing it to your new database. Like duplicating the installation, there are several ways to do this that partially depend on the hosting control panel you use.

If you're using cPanel, you could follow this process:

  1. Use the MySQL Databases interface to create the new database.
  2. Use phpMyAdmin to export the existing data and import it into your new database.

5. Password Protect your Installation's Directory

The development license requires you to make the development installation inaccessible, either using password protection or other methods that return an error or a login prompt.

In cPanel, you can password protect the installation's directory in Files >> Directory Privacy.

6. Update the System URL

Make sure to update the system URL in the General tab at Configuration > System Settings > General Settings to use the new testing environment's URL.

If you can't access the installation to do this in the interface yet, in WHMCS 8.8 and later, you can set the systemUrl setting in the configuration.php file:

$systemUrl="https://www.example.com/whmcs/"
Click to copy

In WHMCS 8.7 and earlier, you can use this MySQL command or update the value manually in phpMyAdmin:

UPDATE `tblconfiguration` SET value ='https://www.example.com/whmcs/' WHERE setting='SystemURL';
Click to copy

7. Prevent Sending Mail

To prevent sending test mail from your development installation to your real customers:

  1. Go to Configuration > System Settings > General Settings
  2. In the General tab, set Disable Email Sending to ON.

You can also use a service like Mailtrap.io to serve this purpose.

You may also want to set your payment gateways and domain registrars to test mode and disconnect from your production servers. You can also prevent accidentally charging customers by adding extra characters to the encryption hash in your development environment's configuration.php file. This makes WHMCS unable to read encrypted data, ensuring that it can't use encrypted data to charge credit cards or perform other actions.

You must exercise caution when you do this. Accidentally making this type of change on your production installation could cause serious problems.

Testing a New Version

After you copy your production installation and have confirmed that everything is functional, you can upgrade WHMCS. We recommend that you use the Automatic Updater for this, since it streamlines the process for you.

After upgrade, go through WHMCS and exercise all of the features and functions that you use most. Check both the Client Area and Admin Area, and make sure to place several orders for your various products. Advance these test orders through every step of the process, including marking them as paid and ensuring correct provisioning.

Monitor Configuration > System Health and look for any problems or incompatibilities. The Cron Job Activity Report email will confirm whether your automation tasks are successful.

After you have completed everything successfully, you can upgrade your production installation.