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.

You can also create custom authentication modules for WHMCS. For more information, see LoginShare Modules.

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 a templates 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