Revision as of 13:08, 23 December 2015

Registrar Modules allow for the registration and management of domains within WHMCS.

Registrar Modules are also referred to as Domain Modules.

The core functionality of a registrar module will allow for

• registering domains
• initiating transfers
• performing renewals
• allow the viewing and changing of nameservers
• allow the viewing and changing of WHOIS information for those domains

But they can do a whole lot more if you want them to.

There are other types of module in WHMCS. These are Payment Gateways, Provisioning Modules and Addons.

Getting Started

Begin by downloading the Registrar Module Template: http://www.whmcs.com/members/dl.php?type=d&id=16

Naming Conventions

Registrar Modules are found in the /modules/registrars/ directory. The module name chosen must be unique and should be all lowercase. The name must only contain letters & numbers whilst always starting with a letter.

Inside the module, function naming will follow a certain format. Functions have a prefix of the module filename, underscore, then the function name. For example, a module "mymodule" would have the register function "mymodule_RegisterDomain".

Product Configuration Options

As with all modules in WHMCS, the required function is the configuration function. This defines the settings that are available on a registrar basis when a domain uses the module. The name of this function must be mymodule_getConfigArray matching the name of your module.

There is a limited number of supported field types. These 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

Here is an overview of all functions that a WHMCS registrar module can contain. Functions within a module are optional and need not be in the module if they don’t apply. Remember, all functions should have the prefix filename_ and then the function name. The function name is below in bold in the function descriptions.

• RegisterDomain - Called when the registration of a new domain comes from WHMCS
• RenewDomain - Called when a request to renew a domain comes from WHMCS
• TransferDomain - Called when an existing domain transfer request comes from WHMCS

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

• ClientArea - 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. Output via a template file within the module folder named "clientarea.tpl" is also possible. Discussion of this function in more detail later on in the docs.
• ClientAreaCustomButtonArray - Used to define custom functions that the module supports. Customers can invoke and run these from the client area. The functions can perform actions or product page output in the client area. Example usages for this are to provide domain management pages, bandwidth reporting pages, etc…
• ClientAreaAllowedFunctions - Like the above, used to define custom functions. These are functions that customers can invoke, but are not shown as buttons by default. (i.e. custom client area output will invoke them).

Domain Cron Synchronisation

Implementation of domain sync into a registrar module ensures domains in WHMCS stay in sync with the registry. 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.

Let's look at Transfer Syncing. If present in your module, this function will run for every domain in the Pending Transfer status when the domain sync cron runs. The function should then return a true response for completed. Or a failed status 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) {

# Your available parameters are:

    $params['domainid'];
    $params['domain'];
    $params['sld'];
    $params['tld'];
    $params['registrar'];
    $params['regperiod'];
    $params['status'];
    $params['dnsmanagement'];
    $params['emailforwarding'];
    $params['idprotection'];

# Other parameters used in your _getConfigArray() function would also be available for use in this function

# Put your code to check on the domain transfer status here

$values = array();

# - if the transfer has completed successfully

$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

}

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

function modulename_Sync($params) {

# Your available parameters are:

    $params['domainid'];
    $params['domain'];
    $params['sld'];
    $params['tld'];
    $params['registrar'];
    $params['regperiod'];
    $params['status'];
    $params['dnsmanagement'];
    $params['emailforwarding'];
    $params['idprotection'];

# Other parameters used in your _getConfigArray() function would also be available for use in this function


# Put your code to check on the domain status here

$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 are in the Setup > General Settings > Domains area. There are 3 key settings:

1. Domain Sync Enabled - Check to allow the domain sync cron to actually run
2. Sync Next Due Date - Enable this setting to update next due date to match the expiry field as part of the sync.
3. Domain Sync Notify Only - Enable this to allow WHMCS to run the sync checks and report any inconsistencies. But, no changes to the domains will occur. With this enabled you receive an email report listing any discrepancies between the registrar and WHMCS.

Module Parameters

The module parameters are the data/values passed into each function when called. Every module function receives the same parameters. These parameters provide information about the specific domain the module command runs for. The parameters also contain the settings from the registrar itself. Extra variables may be available depending upon the function running.

Core Module Functions

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

Response Handling

Many of the registrar module functions expect 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 so, registrar module functions in WHMCS expect array based returns. Refer to the sample module template for specific details of each function return.

Success Handling

Most of the functions within a registrar module have a set return. However, there are some that do not have a return value such as Register, Transfer and Renew. We recommend returning a success array so that the code can be read as being successful if up to this point:

return array("success" => true);

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 recommend using the GetNameservers function to return a friendly error when a domain is not yet registered. Admins will often view a domains details before registration, or during the timeframe of a transfer process. Something like "Domain Not Yet Registered" as opposed to "Error Domain Not Found" for example.

Custom Functions

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

The convention for custom function names follow the same as any other function of a module. It must begin with the module filename_, and then the custom function name.

The easiest way to show this is with an example. So let’s take an example of a Push Function that will use a template, "pushdomain.tpl":

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',
		),
	);

}

The above shows how to define custom functions, use the parameters passed, and return 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 extra client area page for extra 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

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

Hooks that the module define are within the “hooks.php” file of the custom registrar module folder. This will then be 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 modules in WHMCS, we recommend you make use of the built in module logging functionality. This will aid both yourself, and end users should you plan to release the module. Debugging the calls the 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

App Store

WHMCS offers an app store which accepts submission of the completed module. Displayed listings are found under the Addons tab within the administration area and online at http://www.whmcs.com/appstore . This is a great way to make WHMCS users aware of the module.

Submission of a listing requires a login for whmcs.com/members, if you do not have one please Contact Us. Once logged in, visit the app store page at the above URL and click the "Submit your Addon" link. We aim to review submissions in 1-2 weeks.