Revision as of 16:17, 13 September 2012

Registrar Modules, also referred to as Domain Modules, allow you to create modules to allow for the registration and management of domains in WHMCS.

The core functionality of a registrar module is for registering, initiating transfers, performing renewals & allowing for the viewing and changing of both nameservers and WHOIS information for those domains. But they can do a whole lot more if you want them to.

Other types of modules that can be created in WHMCS are Payment Gateways, Provisioning Modules and Addons.

Getting Started

Begin by downloading the Registrar Module Template file for sample code to refer to here: http://www.whmcs.com/members/dl.php?type=d&id=16

Naming Conventions

Registrar Modules are stored in the /modules/registrars/ directory. The module name you choose must be unique, and should be all lowercase, containing only letters & numbers, always starting with a letter.

Within the module itself, all functions must then be prefixed with the module filename, followed by an underscore, and then the function name. For example if your module was called "mymodule" the register function would be named "mymodule_RegisterDomain".

Product Configuration Options

As with all module types in WHMCS, the required function of all provisioning modules is the configuration function. This is what defines the settings that can be configured for this registrar module within the WHMCS Admin Area. The name of this function must be mymodule_getConfigArray matching the name of your module.

The supported field types are Text, Password, Yes/No Checkboxes, Dropdown Menus, Radio Buttons & Text Areas

Below are examples of the available parameters for each field type. Registrar modules support an unlimited number of options defined in this way.

$configarray = array(
    "username" => array (
        "FriendlyName" => "UserName",
        "Type" => "text", # Text Box
        "Size" => "25", # Defines the Field Width
        "Description" => "Textbox",
        "Default" => "Example",
    ),
    "password" => array (
        "FriendlyName" => "Password",
        "Type" => "password", # Password Field
        "Size" => "25", # Defines the Field Width
        "Description" => "Password",
        "Default" => "Example",
    ),
    "usessl" => array (
        "FriendlyName" => "Enable SSL",
        "Type" => "yesno", # Yes/No Checkbox
        "Description" => "Tick to use secure connections",
    ),
    "package" => array (
        "FriendlyName" => "Package Name",
        "Type" => "dropdown", # Dropdown Choice of Options
        "Options" => "Starter,Advanced,Ultimate",
        "Description" => "Sample Dropdown",
        "Default" => "Advanced",
    ),
    "disk" => array (
        "FriendlyName" => "Disk Space",
        "Type" => "radio", # Radio Selection of Options
        "Options" => "100MB,200MB,300MB",
        "Description" => "Radio Options Demo",
        "Default" => "200MB",
    ),
    "comments" => array (
        "FriendlyName" => "Notes",
        "Type" => "textarea", # Textarea
        "Rows" => "3", # Number of Rows
        "Cols" => "50", # Number of Columns
        "Description" => "Description goes here",
        "Default" => "Enter notes here",
    ),
);
return $configarray;

Supported Functions

What follows here is a brief overview of all the possible functions that a product provisioning module in WHMCS can contain. All functions within a module are optional and can be omitted from the module if they don’t apply. Remember, within the code itself, all functions are prefixed with the module filename, followed by an underscore, and then the function name as shown in bold in these descriptions.

• Register - This function is called when the registration of a new domain is requested from WHMCS
• Transfer - This function is called when a request to initiate the transfer of a domain is sent from WHMCS
• Renew - This function is called when an existing domain is requested for renewal within WHMCS

• GetNameservers - This function is called whenever a domains details are requested/viewed within WHMCS. It can return up to 5 nameservers that are set for the domain.
• SaveNameservers - This function is called when a change is made to the nameserver values displayed inside WHMCS.
• GetRegistrarLock - This function is called whenever a domains details are requested/viewed within WHMCS. It should return the current lock status of a domain - either locked or unlocked.
• SaveRegistrarLock - This function is called when the lock status setting is toggled within WHMCS.
• GetContactDetails - This function is called when the WHOIS information is requested to be viewed
• SaveContactDetails - This function is called when revised WHOIS information is submitted
• GetDNS - This function is called when the DNS Host Records are requested to be viewed within WHMCS
• SaveDNS - This function is called when any changes to DNS Host Records information is submitted
• IDProtectToggle - This function is called when the ID Protection setting is toggled on or off
• GetEPPCode - This function is called when the EPP Code is requested for a transfer out
• ReleaseDomain - This function is called when a domain release is requested (eg. UK IPSTag Changes)
• RegisterNameserver - This function is called when a child nameserver is requested to be registered
• ModifyNameserver - This function is called when a child nameserver is requested to be edited
• DeleteNameserver - This function is called when a child nameserver is requested to be deleted
• RequestDelete - This function is called when a domain is requested to be deleted

• ClientArea - This function can be used to define module specific client area output. It accepts a return of HTML for display on the domain details page of the client area. The output can alternatively be specified via a template file within the module folder named “clientarea.tpl” to allow for end user customisation. This function is discussed in more detail later on in the docs.
• ClientAreaCustomButtonArray - This function can be used to define custom functions that your module supports that customers are allowed to invoke and run from the client area. These functions can just perform actions, or give domain page output in the client area, for example giving additional functionality available specific to your registrar.
• ClientAreaAllowedFunctions - Similar to the above, this function can be used to define custom functions that customers are allowed to invoke themselves, but are not shown as buttons by default (ie. your custom client area output will invoke them)

Domain Cron Sychronisation

Domain synchronization can be implemented into a registrar module to ensure domains in WHMCS stay in sync with the domain registrar. This can include syncing status changes, renewals, and expiry dates. This is particularly useful when it comes to transfers where completion of the transfer, and expiry dates can never be known by WHMCS automatically.

First let's look at Transfer Syncing. If present in your module, this function is called for every domain in the Pending Transfer status each time your domain sync cron runs. The function should then return either a true response for either completed or failed if the transfer has changed status since the last check. If failed, you can also return a reason. If there has been no change yet, then you should return nothing.

function modulename_TransferSync($params) {

# Put your code to check on the domain status here

$values = array();

$values['completed'] = true; #  when transfer completes successfully
$values['expirydate'] = '2013-10-28'; # the expiry date of the domain (if available)

# - or if failed

$values['failed'] = true; # when transfer fails permenantly
$values['reason'] = "Reason here..."; # reason for the transfer failing (if available) - a generic failure reason is given if no reason is returned

# - or if errored

$values['error'] = "Message here..."; # error if the check fails - for example domain not found

return $values; # return the details of the sync

}

There there is regular Domain Syncing. If present in your module, then this function is called for 50 of the domains assigned to that module on a rolling basis each time the domain sync cron file runs. Once all domains have been synced it will start from the beginning again. This can be used to detect any changes done at registrars directly, such as changes to dates or statuses.

function modulename_Sync($params) {
       
$values = array();

$values['active'] = true; # set to true if the domain is active
$values['expired'] = true; # or set to true if the domain has expired

$values['expirydate'] = '2013-10-28'; # populate with the domains expiry date if available

return $values; # return the details of the sync

}

Settings relating to domain syncing can be found in the Setup > General Settings > Domains area. There are 3 key settings:

1. Domain Sync Enabled - This must be ticked in order to allow the domain sync cron to actually run
2. Sync Next Due Date - This setting can be enabled if you want the syncronisation process to automatically update next due dates to match the same date as the expiry fields
3. Domain Sync Notify Only - This option is there if you want WHMCS to run the sync checks, and report any inconsisitencies to you, but not actually make any updates to the domains automatically. With this enabled you simply get an email report listing any discrepancies between data at the registrar and held in WHMCS.

Module Parameters

The module parameters are the data/values passed into each function when called. Every module function is passed the same core parameters - the settings of any fields defined in the configuration function above, along with the domainid, sld & tld to be managed. Additional variables will depend upon the function being called.

Core Module Functions

The core module functions are the Register, Transfer, Renew, GetNameservers, SaveNameservers, GetContactDetails & SaveContactDetails. We recommend that all registrar modules should include these functions as a minimum.

Response Handling

Many of the registrar modules are expected to return data. For example GetNameservers should return the nameservers for a domain, GetContactDetails should return the current WHOIS Info for a domain, etc... And therefore registrar module functions in WHMCS expect array based returns. Please refer to the sample module file template for specific details of what each function wants returning.

Error Handling

Should an error occur, you need to return a user friendly error message in an "error" return variable. For example:

return array( 'error' => 'Error Message Goes Here...' );

We particularly recommend using the GetNameservers function (which is called whenever a domains details are requested to be viewed) to return a friendly error when a domain is not yet registered. As admins will often view a domains details prior to registration, or during the timeframe of a transfer being processed. Something along the lines of "Domain Not Yet Registered" as opposed to "Error Domain Not Found" for example.

Custom Functions

Custom functions allow you to define additional operations that can be performed using the module. The custom functions can perform actions, or define additional client area pages/output. Permissions can be granted for who can use each custom function, be it just clients, just admins, or both.

The naming convention for custom functions follows the same as any other function within a module so it must begin with the module filename, followed by an underscore, and then the custom function name.

The easiest way to demonstrate this is with an example so let’s take an example of a Push Function that we want to give clients, that will make use of a template file called "pushdomain.tpl" within our custom registrar module folder.

function mymodule_push($params) {

	$domainid = $params['domainid'];
	$sld = $params['sld'];
	$tld = $params['tld'];

	return array(
		'templatefile' => 'pushdomain',
		'breadcrumb' => array( 'clientarea.php?action=domaindetails&domainid='.$domainid.'&modop=custom&a=push' => 'Push Domain' ),
		'vars' => array(
			'var1' => 'valuehere',
			'var2' => 'anothervaluehere',
		),
	);

}

In the above you can see how the custom functions are defined, being passed all the same module parameters as all other functions, & returning an array response. The response can either be a simple empty array/error for an action function, or a complex array return like the above to define an additional client area page for additional domain management functionality.

Now we need to allow clients to use this. The following function defines that clients are allowed to invoke the push function, and will add a menu option to the Domain Actions dropdown within the client area for it.

function mymodule_ClientAreaCustomButtonArray() {
    $buttonarray = array(
	 "Push Domain" => "push",
	);
	return $buttonarray;
}

The key value of the array is what get’s displayed to admins/clients on the button or menu options for the commands. And the value is the custom function name excluding the modulename_ prefix.

If you want to provide clients with a custom button or way to invoke a function, then this can be done as follows within a .tpl file described in the previous Client Area Output section:

<form method="post" action="clientarea.php?action=domaindetails">
<input type="hidden" name="domainid" value="{$domainid}" />
<input type="hidden" name="modop" value="custom" />
<input type="hidden" name="a" value="reboot" />
<input type="submit" value="Reboot VPS Server" />
</form>

Hooks (New for V5.0+)

Registrar modules can now also define hook functions, that can take effect system wide and allow registrar modules to integrate deeper into WHMCS more than ever before. For example you could have certain additional actions occurring when specific events occur in WHMCS, or simply use them to define a Widget for use on the admin homepage to provide additional registrar specific functionality to the WHMCS admins/staff.

To create hooks that your module should define within WHMCS, you simply need to create a file named “hooks.php” within the custom registrar module folder, and that will then be automatically detected and any hooks loaded on every page of WHMCS.

The hook functions within that file should be defined in exactly the same way as normal.

Please refer to Hook Documentation for more info on creating and working with hooks in WHMCS.

Module Logging

As with all provisioning modules in WHMCS, we recommend you make use of the built in module logging functionality to aid both yourself, and end users should you plan to release your module publically, in debugging the calls your module makes in the same standardised way as all modules in WHMCS do by default. Please refer to the URL below for more details on how to do this.

http://docs.whmcs.com/Provisioning_Module_Developer_Docs#Module_Logging