System Environment Guide
WHMCS is compatible with most web server environments. Installing WHMCS in your web environment is usually straight forward. As well, WHMCS is continually providing updates which can support for environment updates from the upstream providers. However, as new technologies emerge and your current system's environment has access to new updates, it's important that you are aware of how they might affect your WHMCS deployment. This guide is designed help you and your system administrator prepare and manage your environment.
Contents
Overview
WHMCS is designed for a traditional LAMP (Linux, Apache, MySQL, PHP) environment. The minimum requirements and basic version compatibility related to those sub-systems are provided in our [System_Requirements].
The development of WHMCS is such that alternative technologies may be viable, however they are not tested and assistance from our Support Team will be limited. For example, if you wish to use NGINX instead of Apache, it may be technically possible. However, our Support will have limited knowledge about how to properly configure NGINX or debug behaviors that are specific to NGINX.
If you require the use of something other than Linux, Apache, or MySQL please consult with your system administrator to evaluate the immediate possibilities for (in)compatibility and long-term viability so that your internal system management strategy is accommodate for your specific requirements.
Operating System
WHMCS is designed to run in a standard Linux operating/file system. WHMCS relies on PHP for interaction with the file system. In some operating systems (such as Windows) or environments (such a jails or chroots) the file system may have restrictions or inherent behaviors which may be hard to detect or uncommon. When possible, WHMCS provide notices that indicates incompatibility. If you require a different operating/file system, please discuss with your system administrator. Our Support Team is available to provide limited assistance to your system administrator for your custom environment.
Also of note, WHMCS relies heavily on the Linux Cron sub-system to trigger background tasks and perform periodic automation tasks such as deferred provisioning, service synchronization, invoice generation, billing, and more.
need more here
Web Server
WHMCS is designed to work with the Apache web server version 2.x. While there are no special Apache configuration required for WHMCS, there are some advantages available to you and your WHMCS deployment that you may wish to consider.
Extensions
- mod_rewrite
- The Apache mod_rewrite module allows Apache to inspect and modify URLs and redirects through the use of .htaccess files within your web server docroot. WHMCS can create and manage an .htaccess file, and thus generate and consume friendly URLs in various parts of the product. This feature is described in more detail at Friendly URLs.
Handler
- Server-wide Handlers (CGI, mod_php)
- need more here
- Vhost User Handlers (SuExec, SuPHP, mod_ruid2)
- need more here
- Pool-based Handlers (FastCGI, PHP-FPM)
- need more here
Database
WHMCS is designed to work with the MySQL database. Binary compatible alternatives (such as MariaDB) should be suitable, however their default configurations and optimizations are likely to be different and you should consult with your system administrator or database administrator.
Version Compatibility
WHMCS supports MySQL 5.2-5.7. At this time, MySQL 8 (current in RC status) is not supported.
| WHMCS Version (Status) | MySQL v5.2 | MySQL v5.3 | MySQL v5.4 | MySQL v5.5 | MySQL v5.6 | MySQL v5.7 | MySQL v8.0 |
|---|---|---|---|---|---|---|---|
| v6.3 (EOL) | Y | Y | Y | Y | Y | N | N |
| v7.0 (EOL) | Y | Y | Y | Y | Y | N | N |
| v7.1 (EOL) | Y | Y | Y | Y | Y | N | N |
| v7.2 (EOL) | Y | Y | Y | Y | Y | N | N |
| v7.3 (EOL) | Y | Y | Y | Y | Y | Y | N |
| v7.4 (EOL) | Y | Y | Y | Y | Y | Y | N |
| v7.5 (EOL) | Y | Y | Y | Y | Y | Y | N |
| v7.6 (EOL) | Y | Y | Y | Y | Y | Y | N |
| v7.7 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v7.8 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v7.9 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v7.10 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v8.0 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v8.1 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v8.2 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v8.3 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v8.4 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v8.5 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v8.6 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v8.7 (EOL) | Y | Y | Y | Y | Y | Y | Y |
| v8.8 (LTS) | Y | Y | Y | Y | Y | Y | Y |
| v8.9 (LTS) | Y | Y | Y | Y | Y | Y | Y |
| v8.10 (Active) | Y | Y | Y | Y | Y | Y | Y |
Database Grant Privileges
When installing or updating WHMCS, or when activating or deactivating modules, the following grant privileges are required:
- ALTER
- CREATE
- DROP
- INDEX
For day to day use, only the following database grant privileges are required. All others may be disabled.
- DELETE
- INSERT
- SELECT
- UPDATE
- LOCK TABLES
If you choose to restrict the grant privileges for day to day use, don't forget to grant the former privileges so database schema changes and optimizations can be performed by the update process.
Database Interaction
WHMCS internals utilize a PDO based database connection. If the PHP environment is v5.6, both a PDO and a MySQL handle will be used for compatibility with legacy code.
If you have developing code for the WHMCS platform, it is recommended that you interact with the database via the Local API, DBAL & ORM, or Models. All three methods will abstract database connection details and system compatibility for you and will be supported by WHMCS for the foreseeable future. The SQL Helper Functions are still present, although deprecated. Due to their ubiquitous usage, we anticipate supporting them as long as possible but recommend that you use one of the other methods above. You can learn more at Interacting with the Database on our developer's site.
PHP
WHMCS is written in PHP. Your environment's PHP will need to be a version supported by the version of WHMCS you are using. In general, this will be one of the PHP versions that is either under active development or is receiving security fixes from the upstream PHP maintainers.
Whenever possible, it is usually preferable to utilize a version of PHP that is under active development. Unfortunately, there can be a number of circumstances that may complicate the viability of using the latest stable release of PHP. These can range from a lack of control panel build support to incompatibility for other web applications on your server to backwards breaking behavior in PHP that inhibit IonCube support. Regardless, WHMCS always provides support for a security-monitored PHP version available from the PHP maintainers and is continually prioritizing compatibility of their future releases.
Version Compatibility
| 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) | Y | Y | Y | Y | N | N | N | N | N | N |
| v7.0 (EOL) | N | N | N | Y | Y | N | N | N | N | N |
| v7.1 (EOL) | N | N | N | Y | Y | N | N | N | N | N |
| v7.2 (EOL) | N | N | N | Y | Y | N | N | N | N | N |
| v7.3 (EOL) | N | N | N | Y | Y | N | N | N | N | N |
| v7.4 (EOL) | N | N | N | Y | Y | N | N | N | N | N |
| v7.5 (EOL) | N | N | N | Y | Y | Y | Y | N | N | N |
| v7.6 (EOL) | N | N | N | Y | Y | Y | Y | Y | N | N |
| v7.7 (EOL) | N | N | N | Y | Y | Y | Y | Y | N | N |
| v7.8 (EOL) | N | N | N | Y | Y | Y | Y | Y | N | N |
| v7.9 (EOL) | N | N | N | Y | Y | Y | Y | Y | N | N |
| v7.10 (EOL) | N | N | N | Y | Y | Y | Y | Y | N | N |
| v8.0 (EOL) | N | N | N | N | N | N | Y | Y | Y | N |
| v8.1 (EOL) | N | N | N | N | N | N | Y | Y | Y | N |
| v8.2 (EOL) | N | N | N | N | N | N | Y | Y | Y | N |
| v8.3 (EOL) | N | N | N | N | N | N | Y | Y | Y | N |
| v8.4 (EOL) | N | N | N | N | N | N | Y | Y | Y | N |
| v8.5 (EOL) | N | N | N | N | N | N | Y | Y | Y | N |
| v8.6 (EOL) | N | N | N | N | N | N | Y | Y | Y | Y |
| v8.7 (EOL) | N | N | N | N | N | N | Y | Y | Y | Y |
| v8.8 (LTS) | N | N | N | N | N | N | Y | Y | Y | Y |
| v8.9 (LTS) | N | N | N | N | N | N | Y | Y | Y | Y |
| v8.10 (Active) | N | N | N | N | N | N | Y | Y | Y | Y |
IonCube
IonCube is a set of encoding and decoding tools that provide obfuscation and performance for PHP software. The decoder tool is called a "loader" and is installed within the web server environment. The encoder tool, called an "Encoder," is used by the PHP developer as part of their publication process.
WHMCS is encoded with IonCube. A minimum requirement for WHMCS is to have the IonCube loader extension installed and enabled in your web server environment. We recommend running the latest version of the IonCube loader available for your PHP version.
Usually, IonCube will published a complementing loader several weeks following a new PHP version. Utilizing this latest loader will afford you two benefits. First, it means that you have the potential for running previously encoded files using a new base PHP version and running unencoded (raw) PHP code that is compatible with the base PHP version. Second, it means you have the potential for running newly encoded files generated with a new IonCube Encoder (if one was published).
The IonCube Encoder, used by PHP developers, requires the developer to itemize which PHP versions environment should be supported. This is important to note for two reasons: First, due to the complexity of PHP internals, there is often limitations on which target PHP versions can be bundle at once. Second, IonCube usually publishes a complementing encoder several weeks to months following a new PHP version. Given these two factors, it is common for PHP applications to not support the latest PHP version on the initial PHP release date. Furthermore, there likely will be further requirements about the oldest PHP version supported by their publication as well as which loader will be required.
Each WHMCS version has always supported at least two PHP versions. Each new version of WHMCS has always supported at least one of the PHP versions supported in the previous WHMCS publication. This perpetual overlap of PHP version support across WHMCS publications means that you always have a path to upgrade your PHP environment without having to update the WHMCS software at the same time. As well, it allows the WHMCS Updater to safely automate your updates based on your current environment. Providing this overlap is integral to enabling your environment maintenance strategy, giving you the best balance of security, stability and forward compatiblity as soon as possible.
Version Compatibility
| 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 |