Revision as of 15:43, 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

The domainsync file works with your WHMCS cron in order to make automatic updates on certain functions in your registrar modules. This file basically works with your 2 main functions in the registrar module.

• _TransferSync function

• _Sync function

Displayed below is an example of how these module functions are created, and what values must be returned in order to succesfully synchronise with the domain sync file.

/** Creating _TransferSync function **/

# Please note that the function name must begin with your modulename (modulename.php) 
# followed with an underscore.
# The $params variable returns an array of the available vars in our system 

function yourModuleName_TransferSync($params){
       
$uid= $params["Username"] ;
$pw =  $params["Password"] ;
$TLD = $params["tld"] ;
$SLD = $params["sld"] ;
$Quantity = $params["regperiod"] ;

# Run your API command to make the transfer with your available
#vars and return your response

# You can also purchase an ID protect if enabled
# By using the $params['idprotection'] vars
# For instance:

 if ($params['idprotection']){

     run your API command to add the purchase
}

#Values that must be returned

$values['completed'] = true; #  when transaction/transfer is complete and successful
$values['failed'] = true; # when transaction/transfer has failed
$values['reason'] = $yourReason; # This is your reason for a failed transfer
# A generic reason is within the WHMCS is thrown when the "$values['reason']" is not given

$values['pendingtransfer'] = true; # when transaction/transfer is pending completion
$values['reason'] = $yourpendingreason; # Reason for pending completion status

# A generic reason is within the WHMCS is thrown when the "$values['reason']" is not given

return $values # returns your array of conditional responses

}

########################################################

/** Creating _Sync function **/

# This function is responsible for retrieving the domain expiry date
# Please note that the function name must begin with your modulename (modulename.php) 
# followed with an underscore.
# The $params variable returns an array of the available vars in our system 

function yourModuleName_Sync($params){
       
$uid= $params["Username"] ;
$pw =  $params["Password"] ;
$TLD = $params["tld"] ;
$SLD = $params["sld"] ;
$Quantity = $params["regperiod"] ;

# Run your API command to retreive an expiry date with your available
# vars and return your response

# Values that must be must be returned

$values['status'] = "Active"; # The Domain Status
$values['expirydate'] = $yourRetrievedExpiryDate; #  The expiry date retreived from your API call


return $values; # returns an array of the values assigned to your $values variable
}

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