WHMCS Custom Module Development

What types of WHMCS module can be built?

I build seven kinds of WHMCS module, and each one lives in its own folder with its own function naming. Choosing the right type decides how much of WHMCS's built-in behavior you get for free.

Do I need a module, or is a hook enough?

A hook is enough when you only need to react to something WHMCS already does. A module is needed when WHMCS must call your code as part of a service lifecycle, or when you need your own settings, screens or tables.

A hook fits jobs like "when a ticket opens, post to Slack", "when an invoice is paid, tag the client in the CRM" or "change what the client area home page shows". Hooks live in includes/hooks/, so there is nothing to install or activate. A module fits jobs like "when this order is paid, create an account on our platform", "give staff a page to manage license keys" or "add a new payment method". If you are unsure, tell me the outcome you want and I will tell you which shape is smaller. A module can also carry its own hooks, which is how many addons are built.

Which functions does a provisioning module need?

A provisioning module is a PHP file named after the module, with functions that all start with that name. WHMCS calls them at fixed moments, and you return the word success or an error message.

• modulename_MetaData() returns the display name and the API version the module targets.
• modulename_ConfigOptions() defines the settings shown on the product's module tab, such as plan or location.
• modulename_CreateAccount($params) runs when a service is activated. The $params array carries the service, the client, the server and the product settings.
• modulename_SuspendAccount, _UnsuspendAccount and _TerminateAccount handle overdue, paid and cancelled services.
• modulename_ChangePackage handles upgrades and downgrades.
• modulename_ClientArea returns a template and variables for a service page the customer sees.

I wrap every outside request with logModuleCall(), so each request and response appears in the WHMCS Module Log whenever module logging is switched on. When a customer says "my server was never created", that log is where the answer is.

How do addon modules differ?

An addon module is a self-contained feature with its own screens and data, defined by a different set of functions. The module folder name is the prefix again.

• modulename_config() returns the name, description, version, author and any settings fields.
• modulename_activate() runs once on activation. It is where tables are created, and it returns a status array so WHMCS can show success or the reason for failure.
• modulename_output($vars) draws the admin page.
• modulename_clientarea($vars) returns the page a logged-in client sees, including its title and template.

Addons can also define deactivate and upgrade functions, which matter when you later change the table structure of a module that is already in use.

How does a module store data and call WHMCS?

I use the Capsule database layer for storage and localAPI for actions. Both are supported WHMCS interfaces, so they are much less likely to break when internals change than raw SQL is.

Capsule is WHMCS's database access layer (WHMCS\Database\Capsule). With it I create module tables, usually prefixed mod_, and query them without raw SQL strings, which lowers the risk of SQL injection. When a module needs WHMCS to do something, such as add a payment, update a client or open a ticket, I call the matching command through localAPI rather than writing to WHMCS's own tables. The API runs validation and fires the hooks other code depends on. A direct UPDATE on a core table skips that validation and those hooks, and that is how invoices and balances drift out of step.

Where does custom code go so upgrades do not remove it?

Custom code goes in the module folders, in includes/hooks/, in a custom template folder and in language overrides. A WHMCS upgrade replaces core files and leaves those locations alone. Anything I change outside them is a core edit, and I do not make core edits.

Upgrade-safe does not mean upgrade-proof. A new WHMCS or PHP release can remove or change a function a module relies on. That is why I record the versions each module was tested on, and why a support plan usually includes a retest after each upgrade.

How do I spec, build, test and document a module?

I follow the same five steps every time, because most module bugs come from a missing decision, not from a missing line of code.

1. Spec. A written list of triggers, expected results, settings, screens, outside API calls and error behavior. You approve it before I code.
2. Build in staging. Code goes into a copy of your WHMCS, never straight into production.
3. Test. Order, pay, upgrade, suspend, unsuspend and terminate on test services, then repeat with failures: bad credentials, a slow API and a duplicate request.
4. Document. Install steps, every setting, every function, the database tables and how to remove the module cleanly.
5. Hand over. I deploy on your approval and stay available for two weeks.

Do I receive the source code, and can it be encoded?

You receive the readable source code, and who holds the rights to it is written into the quote before work starts. If you plan to sell the module to others, I can quote ionCube encoding as a separate, optional step. WHMCS itself needs the ionCube Loader, so buyers' servers normally have it already. Encoding is a one-way step, so I keep the unencoded source with you and tell you before it is applied.

Which module requests do I turn down?

I will not edit WHMCS core files, and I will not build modules that switch off or bypass the WHMCS license check. I do not modify other developers' encoded modules, because I cannot read them. I cannot integrate with a service that has no API documentation and no test environment, since guessing at a live billing API puts your money at risk. I do not write modules that store card numbers. A module also does not replace support: after the two included weeks, ongoing fixes are quoted separately.

What does a custom module cost?

Cost follows scope, so I quote a fixed price after the scoping call. The main drivers are the module type, the number of outside API calls and the number of screens. Related work is covered in API integration and automation for hook-only jobs, and the WHMCS services overview lists everything else I do.