Custom Modules
In WHMCS, provisioning, addons, and payment gateways all use modules to interact with third-party systems or otherwise automate your business’s activities. For example, if you accept payments through Stripe™, you use the Stripe module. In addition to the many modules that WHMCS includes by default, you can add third-party modules or customize your own.
Module Templates
Modules in WHMCS use templates to define and control the output that users see. You can customize module templates using an overrides system that allows customizations within your active Client Area theme directory.
- When you use this system, updates will not overwrite your custom modules.
- Module template files can exist in either the
root
directory of the module or in atemplates
subdirectory.
Create an Override Template
To create an override template, copy the original template file within the following directory structure inside your custom template:
/templates/yourtemplatename/modules/moduletype/modulename/
In this directory structure, yourtemplatename
is the name of your template, moduletype
is the type of module (for example, server
), and modulename
is the module name.
For example:
- For the
cpanel
server provisioning module, you could customize the/modules/servers/cpanel/templates/overview.tpl
file by creating the following template file:/templates/example/modules/servers/cpanel/overview.tpl
- For the licensing provisioning module, you could customize the
/modules/servers/licensing/templates/managelicense.tpl
file by creating the following template file:/templates/example/modules/servers/licensing/managelicense.tpl
- For the Client Area view template of the Project Management addon, you could customize the
/modules/addons/project_management/templates/clientview.tpl
file by creating this template file:/templates/example/modules/addons/project_management/clientview.tpl
Version-Specific Templates
Modules can also provide templates that work with specific Client Area themes.
In WHMCS 8.1 and higher, for example, there are two themes included by default: Twenty-One and Six. Six implements the Bootstrap 3 framework, while Twenty-One uses Bootstrap 4. Because of differences in how they apply styling and structures, a template that works for one may not work for the other.
This allows you to define a default template that has additional templates to use in conjunction with specific system themes. For example, this could provide an older Bootstrap 3-compatible template for use with Six.
For more information about using version-specific templates, see our Developer Documentation.
Service Properties
Many provisioning modules require storage of additional information for products. You can fufill this requirement using service properties.
Service properties are key/value
pairs for a specific service or product addon. They facilitate storing and working with extra data. Service properties use custom fields to store this data in a consistent format that provisioning modules can access programmatically.
The system passes a model instance that represents the service or addon that the module is performing an action against to all module function invocations as part of the module parameters.
Example
For example:
/**
* @param array $params
*
* @return string
*/
function samplemodule_CreateAccount(array $params)
{
try {
// Perform actions to provision service and receive back an order number
$orderNumber = '12345';
// Save order number to Service Properties
$params['model']->serviceProperties->save(['Order Number' => $orderNumber]);
return 'success';
} catch (\Exception $e) {
return $e->getMessage();
}
}
function samplemodule_SuspendAccount(array $params)
{
try {
// Utilise Service Properties to retrieve the Order Number
$orderNumber = $params['model']->serviceProperties->get('Order Number');
// Perform actions using order number here
return 'success';
} catch (\Exception $e) {
return $e->getMessage();
}
}
The save
method will look up a custom field with the given name. If it does not find an existing field, it will create a new custom field to store the value.
Supported Fields
When using service properties against a service (for example, a directly-created product and not an addon), the system may use a dedicated core field rather than a custom field.
This occurs for the following field names:
Username
Password
Domain
License Key
Dedicated IP
Disk Usage
Disk Limit
Bandwidth Usage
Bandwidth Limit
Last Update
Using these field names with an addon will create a custom field.
Customize Ports in Server Modules
To add support for port customization to your server or provisioning modules, define the defaults within the MetaData
function.
The following example provides a custom module with a default port of 80
and an SSL port of 443
:
function template_MetaData()
{
return array(
'DisplayName' => 'Server Module Display Name',
'DefaultNonSSLPort' => '80',
'DefaultSSLPort' => '443',
);
}
function template_CreateAccount($params)
{
$serverPort = $params['serverport'];
}
Last modified: 2025 February 18