How Do You Build a Custom WHMCS Provisioning Module?

What does a WHMCS provisioning module do?

A WHMCS provisioning module, also called a server or product module, carries out the lifecycle of a service on a remote system when billing events happen. The official introduction names the events: payment of a new order, an item becoming overdue, payment of an overdue invoice, and a cancellation request.

That is a different job from the two neighboring tools. A hook reacts to an event with a side effect, which I cover in my WHMCS hooks guide. The API lets other software call WHMCS, covered in my WHMCS API guide. A provisioning module is the code that talks to the remote system: a control panel, a cloud platform, a license server or your own application.

Where do the module files go, and how must they be named?

The files go in a folder of their own under /modules/servers/, and the main PHP file carries the same name as the folder. The getting started page of the documentation gives the naming rule: one word, only lowercase letters and numbers, starting with a letter, and unique. So acmepanel follows the rule, and acme_panel or AcmePanel does not.

The official sample module on GitHub recommends this layout:

modules/servers/acmepanel/
    acmepanel.php    the module functions
    hooks.php        optional hooks that ship with the module
    lib/             your own classes, such as an API client
    templates/       Smarty templates for client area output
    logo.png

Every function in acmepanel.php starts with the file name and an underscore, for example acmepanel_CreateAccount. If the remote system cannot do something, leave that function out, as the sample module advises.

Which functions can a WHMCS provisioning module contain?

The documentation lists seven core functions (Create, Suspend, Unsuspend, Terminate, Renew, ChangePassword and ChangePackage) plus setup and optional functions. This table has the eleven I use most, with the suffix that follows your module name.

The full list is on the supported functions page. It also covers _ClientArea and _AdminCustomButtonArray, _UsageUpdate for the daily disk and bandwidth import, _MetricProvider for usage billing metrics, and _CustomActions, which puts a button on the Active Products/Services panel of the client area home page and sends the customer to a URL.

What does WHMCS pass in the $params array?

WHMCS passes the same $params array to every module function except _ConfigOptions, and it describes the service, the product settings, the client and the server. The keys I use in almost every module are these.

• The service: serviceid, userid, pid, domain, username and password.
• The product's module settings: configoption1 to configoption24, numbered in the order you declare them in _ConfigOptions.
• What the customer chose: customfields and configoptions, both keyed by name, for example $params['configoptions']['Disk Space'].
• The client: clientsdetails, an array with the name, email, address and country.
• The server: serverhostname, serverip, serverusername, serverpassword, serveraccesshash, serversecure and serverport.

Do not confuse configoptionN with configoptions. The first holds the settings staff entered on the product. The second holds the product's configurable options, which the customer picks when ordering. The module parameters page has every key.

Most remote systems return an ID of their own. Store it with service properties: $params['model']->serviceProperties->save(['Remote ID' => $id]) writes to a custom field with that name and creates the field if it is missing.

What does a minimal _CreateAccount function look like?

A minimal module needs the direct-access guard, _MetaData, _ConfigOptions and one core function that returns success or an error string. acmepanel_request() below stands for your own HTTP client, which throws an exception when the panel rejects the request.

<?php
if (!defined('WHMCS')) {
    die('This file cannot be accessed directly');
}

function acmepanel_MetaData()
{
    return ['DisplayName' => 'Acme Panel', 'APIVersion' => '1.1', 'RequiresServer' => true];
}

function acmepanel_ConfigOptions()
{
    return [
        'plan' => ['FriendlyName' => 'Plan', 'Type' => 'dropdown', 'Options' => 'starter,business'],
    ];
}

function acmepanel_CreateAccount(array $params)
{
    $request = [
        'username' => $params['username'],
        'password' => $params['password'],
        'email'    => $params['clientsdetails']['email'],
        'plan'     => $params['configoption1'],
    ];
    $hide = [$params['password'], $params['serverpassword']];

    try {
        $response = acmepanel_request($params, '/accounts', $request);
        logModuleCall('acmepanel', __FUNCTION__, $request, $response, null, $hide);
    } catch (Exception $e) {
        logModuleCall('acmepanel', __FUNCTION__, $request, $e->getMessage(), null, $hide);

        return $e->getMessage();
    }

    return 'success';
}

The return value is the contract. The documentation says the function must return the word success, and that anything else should be an error message a person can understand, because it is shown to staff. Errors from _ChangePassword are also shown to the client, so never return a raw API reply that contains credentials.

How do you make a module's settings easier to fill in?

Mark the everyday fields with 'SimpleMode' => true and let a loader function fetch the rest from the remote system. Both keys sit on the field definitions inside _ConfigOptions, beside FriendlyName and Type, and both cut the number of values staff have to type correctly when they build a product.

Simple Configuration Mode decides which module settings appear by default. Fields carrying SimpleMode show straight away, and the rest stay hidden until the user switches to Advanced Mode. The documentation uses the cPanel module to show the difference.

A loader function fills a field from the remote API instead of a hard-coded dropdown. Add a Loader key naming your function, then have that function return an array of key and label pairs, where the key is the value your module expects to receive. Plan names are the usual case: staff pick from the panel's live list instead of typing a name that has to match it exactly. Here is the Plan field from the example above, rewritten so the panel supplies the list.

function acmepanel_ConfigOptions()
{
    return [
        'plan' => [
            'FriendlyName' => 'Plan',
            'Type'         => 'text',
            'SimpleMode'   => true,
            'Loader'       => 'acmepanel_PlanList',
        ],
    ];
}

function acmepanel_PlanList($params)
{
    // ['starter' => 'Starter', 'business' => 'Business'], read from the panel
}

If the call to the remote API fails, the documentation says to throw an exception rather than return an empty list. WHMCS shows the exception message to the person editing the product, so write it for them: say which system did not answer, not which line of code threw.

How do you log and debug module calls?

Call logModuleCall() around every request to the remote system, then read the Module Log at Configuration > System Logs. Its arguments are the module name, the action, the request, the response, the processed data and an array of strings to scrub from the entry, which is where passwords and tokens go.

Two things surprise people. The Module Log records nothing until you set Module Logging to On, and the logs documentation says the admin role needs the View Module Debug Log permission. And when an automated action fails, it appears at Utilities > Module Queue, where the documentation is blunt: WHMCS will not retry it automatically. Someone has to click Retry. Retry All reruns everything still open in the list, and Mark Resolved takes an item off the list without running it, which is what you want once you have fixed that account by hand.

How do you test a provisioning module before customers use it?

Test it on a staging copy of WHMCS against a test account on the remote system, in this order.

1. Add the server at Configuration > System Settings > Servers and click Test Connection, which runs your _TestConnection function.
2. Create a product at Configuration > System Settings > Products/Services. On the Module Settings tab, choose your module under Module Name and select "Do not automatically setup this product".
3. Order the product for a test client. Run the create, suspend, unsuspend and terminate module commands from the service in the client's profile, and compare each Module Log entry with the remote system.
4. Run every command a second time. Staff will do that in real life, so a create on an existing account and a terminate on a missing one must not cause damage.
5. Switch the product to automatic setup on first payment, pay a test invoice, and confirm that the welcome email arrives only after the account works.