How to Develop Custom WHMCS Modules: Types, Files, Hooks and Testing
Put a PHP file in the right /modules/ folder, prefix every function with the module name, return 'success' from core functions, add hooks, and test on a private dev install.
A custom WHMCS module is a PHP file, or a folder of files, placed in the right directory under /modules/, with functions named after the module so WHMCS can call them at the right moment: when an order is paid, an invoice goes overdue or an admin opens an addon page. This guide is for PHP developers and hosting or IPTV business owners building a provisioning, addon, gateway or registrar module, and it follows the official docs at developers.whmcs.com. The short version: start from the WHMCS sample module for your type, return exactly what WHMCS expects, put event logic in hooks, and test every function on a private development install.
Key takeaways
- Provisioning modules live in
/modules/servers/, addons in/modules/addons/, gateways in/modules/gateways/and registrars in/modules/registrars/. - Every function is prefixed with the module name, such as
mypanel_CreateAccount, and module names are lowercase and start with a letter. - Core provisioning functions must return the exact string
success, or an error message an admin can act on. - Hooks go in
/includes/hooks/or inhooks.phpin the module's root folder. - Use
localAPI()and the Capsule database layer; the oldselect_query()helpers are deprecated. - WHMCS 9 needs PHP 8.2 or later, so build and test there if you support 9.x.
What types of WHMCS modules can you build?
WHMCS module types each solve a different job, and the type decides the directory, the functions and when WHMCS calls your code. The developer docs list provisioning, addon, payment gateway, registrar and mail provider modules, plus notification providers. The WHMCS glossary defines each term.
| Module type | Main file | What it does | Main functions |
|---|---|---|---|
| Provisioning (server) | /modules/servers/name/name.php | Creates and manages a service on a panel or API, such as cPanel, a VPS platform or an IPTV panel | MetaData, ConfigOptions, CreateAccount, SuspendAccount, TerminateAccount |
| Addon | /modules/addons/name/name.php | Adds admin pages, client area pages or integrations not tied to one product | config, activate, deactivate, output, clientarea |
| Payment gateway | /modules/gateways/name.php plus a callback file | Takes payments by redirect (third party), on-site card entry (merchant) or stored tokens (tokenised) | MetaData, config, link or capture, refund |
| Registrar | /modules/registrars/name/name.php | Registers, transfers, renews and manages domains | getConfigArray, RegisterDomain, TransferDomain, RenewDomain, Sync |
Most custom work is a provisioning module, which connects WHMCS to the system that delivers a service, or an addon module, which adds a feature to WHMCS itself. Our IPTV panel modules are provisioning modules, for example.
How do you name a WHMCS module and lay out its files?
A WHMCS module name must be unique, lowercase and start with a letter. Provisioning and registrar names should be a single word of letters and numbers; addon names may also use the underscore. The folder, the main file and the function prefix all use that name.
/modules/servers/mypanel/
mypanel.php all mypanel_* functions
hooks.php optional module hooks
lib/ classes, namespace WHMCS\Module\Server\Mypanel
templates/ client area .tpl files
Start each PHP file with the direct-access guard used in the WHMCS sample modules. Classes in lib/ are autoloaded under WHMCS\Module\{ModuleType}\{ModuleName}. WHMCS follows the PSR-1 and PSR-2 coding standards and asks for 4-space indents, Unix line endings and UTF-8 without a byte-order mark.
Which functions does a WHMCS provisioning module need?
A WHMCS provisioning module only needs the functions it supports; the supported functions list says the rest can be left out. Nearly every module defines these:
name_MetaData()returns settings such asDisplayName,APIVersion(1.1in the sample) andRequiresServer.name_ConfigOptions()defines up to 24 product settings of typetext,password,yesno,dropdown,radioortextarea. They reach your functions asconfigoption1toconfigoption24in the order defined.- The core functions
CreateAccount,SuspendAccount,UnsuspendAccount,TerminateAccount,Renew,ChangePasswordandChangePackage. WHMCS runs them on payment, on overdue invoices through the cron, on upgrades and from admin buttons. name_TestConnection()checks server credentials and returns an array withsuccessanderror.- Optional:
ClientAreaoutput, custom buttons throughClientAreaCustomButtonArrayandAdminCustomButtonArray, single sign-on, andUsageUpdateorMetricProviderfor usage billing.
Each core function must return the exact word success when it worked, which tells WHMCS to, for example, set the service to Active. Anything else is shown to staff as the error. This follows the WHMCS sample provisioning module:
function mypanel_ConfigOptions()
{
return [
'Package' => ['Type' => 'text', 'Size' => '25'],
];
}
function mypanel_CreateAccount(array $params)
{
try {
// Call the panel API with $params['serverhostname'],
// $params['username'], $params['password'], $params['configoption1']
} catch (Exception $e) {
logModuleCall('mypanel', __FUNCTION__, $params, $e->getMessage());
return $e->getMessage();
}
return 'success';
}
The $params array carries the service: serviceid, userid, pid, domain, username, password, customfields and configoptions keyed by name, clientsdetails, and server fields such as serverhostname, serverusername, serverpassword and serveraccesshash.
How do WHMCS addon modules work?
A WHMCS addon module is a set of functions in /modules/addons/name/name.php, as the official sample addon module shows:
name_config()returnsname,description,author,language,versionand settingsfields.name_activate()andname_deactivate()create or drop your tables and returnstatus(successorerror) anddescription.name_upgrade($vars)applies schema changes whenversionincreases.name_output($vars)prints the admin page under the Addons menu.name_clientarea($vars)returns an array telling WHMCS which client area template to render.
How do payment gateway and registrar modules differ?
A WHMCS payment gateway module is usually one file in /modules/gateways/ plus a callback file in /modules/gateways/callback/ for the processor's notification. Third-party gateways return a payment form from name_link(); merchant and tokenised gateways charge in the background. The callback loads init.php, gatewayfunctions.php and invoicefunctions.php, then calls getGatewayVariables(), checkCbInvoiceID(), checkCbTransID() to reject duplicates, logTransaction() and addInvoicePayment(). Verify the processor's signature before adding any payment.
A WHMCS registrar module defines name_getConfigArray() for its settings and then only the domain functions the registrar supports, from RegisterDomain and GetNameservers to Sync, TransferSync and GetTldPricing.
How do you add hooks to a WHMCS module?
WHMCS hooks run your code when an event happens, without editing core files. Standalone hook files go in /includes/hooks/; a module's hooks go in hooks.php in its root folder. WHMCS detects that file when a provisioning, registrar or addon module is activated, so re-save the module's settings if you add it later. An underscore at the start of a file name stops it running. The hooks guide and hook index cover 19 categories of hook points.
add_hook('PreModuleCreate', 1, function ($vars) {
// Stop provisioning when a required custom field is empty
if (empty($vars['params']['customfields']['MAC Address'])) {
return ['abortcmd' => true];
}
});
The number is the priority, which orders functions that share a hook point. Some hook points accept a return value that changes behavior, such as abortcmd here; most only read data. Our hooks development service writes hooks for existing setups.
How should a WHMCS module read data and call WHMCS?
WHMCS gives modules two safe ways to work with its data. For anything WHMCS already does, such as creating an invoice, call localAPI($command, $values) and check that $results['result'] equals success; the admin username argument is optional from WHMCS 7.2. For your own tables, the database interaction guide says to use Capsule:
use WHMCS\Database\Capsule;
$active = Capsule::table('tblhosting')
->where('packageid', $params['pid'])
->where('domainstatus', 'Active')
->count();
Capsule binds parameters, so user input never ends up concatenated into SQL. The older select_query(), update_query(), insert_query() and full_query() helpers are deprecated and may be removed. For calls from another server, use the External API; our API integration service covers that.
How do you test and debug a custom WHMCS module?
Testing a WHMCS module safely needs a private copy that cannot email customers, charge cards or touch production servers. The WHMCS test environment guide covers the setup:
- Get a development license. WHMCS gives one free per active license bought directly, up to three for Business licenses. Licenses bought through a reseller need a purchased dev license.
- Keep it private. The test install must return Forbidden or a login prompt to the public.
- Cut it off from customers. Set
Disable Email Sendingto On in the Mail tab of General Settings, put gateways and registrars in test mode, and add characters to the encryption hash in the testconfiguration.phpso stored cards can't be read. - Show errors while you work. Enable
Display Errorsin the Other tab atConfiguration > System Settings > General Settings, or add$display_errors = true;toconfiguration.php. Never leave it on in production. - Log API calls. Wrap remote calls in
logModuleCall(), pass API keys in its$replaceVarsargument so they are masked, and set Module Logging to On atConfiguration > System Logs > Module Logwhile testing. - Run every function by hand. Order a test product, then use the module command buttons on the service: Create, Suspend, Unsuspend, Change Package, Change Password and Terminate.
- Run the cron. Suspensions and usage updates run from the system cron. If it doesn't run, see WHMCS cron not running.
- Test failures. Try a wrong API key, an unreachable server and a duplicate username, and confirm the admin sees a clear message and the service stays Pending.
What changes for module developers in WHMCS 9?
WHMCS 9.0 (January 20, 2026) and 9.1 (October 20, 2026) both require PHP 8.2 or later, and 9.1 recommends PHP 8.4. WHMCS 9.0 moved to Smarty 4.0 and removed the {php}, {include_php} and {fetch} tags, so module templates can't use them. WHMCS 9.1 requires ionCube Loader 15.0.0, so test encoded builds against it. Non-Draft invoices are immutable in 9.x, with corrections made through credit and debit notes, so code that edited invoice transactions after issue needs rewriting. WHMCS lists 8.13's end of life as December 31, 2026. The WHMCS 9 upgrade guide has the full checklist, and our legacy module rescue service fixes older modules that break.
Frequently asked questions
Which functions are required in a WHMCS provisioning module?
None are strictly required: the WHMCS docs say to define only what your module supports. A useful module defines MetaData, ConfigOptions, CreateAccount, SuspendAccount, UnsuspendAccount and TerminateAccount, each core function returning success or an error.
Where should WHMCS hook files go?
Standalone hooks go in /includes/hooks/ and module hooks go in hooks.php in the module's root folder. Re-save the module's settings after adding that file so WHMCS picks it up.
Do I need a second WHMCS license to develop modules?
Usually not. WHMCS gives one free development license per active license bought directly from WHMCS, but licenses bought through a reseller need a separately purchased development license.
Should I use raw SQL in a WHMCS module?
No. Use localAPI() for actions WHMCS already supports and the Capsule query builder for your own tables. The legacy select_query() family is deprecated.
Can I list a custom module on the WHMCS Marketplace?
Yes. WHMCS says Marketplace submission is free and recommends it. Test on every WHMCS and PHP version you claim to support first.
Will a module written for WHMCS 8 work on WHMCS 9?
Often, but not always. WHMCS 9 needs PHP 8.2 or later, uses Smarty 4.0 and treats non-Draft invoices as immutable, so test each module on a 9.x staging copy first.
If you'd rather have a module built or reviewed for you, our custom WHMCS module development service covers provisioning, addon, gateway and registrar modules.
Tagged with: