Welcome to Coding the Duke, a series of articles that looks at the code behind the Duke of URL application and the development of OpenSRS clients in PHP using the OpenSRS-PHP library.

In the last installment of Coding the Duke, I showed you the code for one of the simplest OpenSRS client applications you can write — a “domain lookup” app built on the OpenSRS-PHP library and the LOOKUP DOMAIN API call. I also provided a brief overview of OpenSRS, its protocols and the XCP protocol in particular.

In this installment, we'll write a slightly more complex application. It'll be our first pass at building a domain name suggester — an application that suggests up to 100 domain names based on a given word or phrase. Like the application from the previous article, this will be a “bare bones” program; we'll make it more usable in the upcoming articles.

This article builds on the material covered in the previous two. If you haven't read them yet, here they are:

• Coding the Duke #1: Introducing OpenSRS-PHP
• Coding the Duke #2: A Simple Domain Lookup

The NAME SUGGEST API Call

As its name implies, the NAME SUGGEST API call suggests a number of available domain names based on a given word or phrase. It returns up to a maximum of 100 suggestions and will suggest available names for any combinations of the following top-level domains:

• .com
• .net
• .org
• .biz
• .info

NAME SUGGEST does more that its name implies; it's also capable of doing domain name availability checks in a manner similar to LOOKUP DOMAIN.

If that's not enough functionality for you, NAME SUGGEST lets you combine domain lookup and name suggestion in a single operation. You can provide it with a word or phrase and it'll check the availability of that name across all gTLDs and ccTLDs and provide domain name suggestions based on the word or phrase for the .com, .net, .org, .biz and .info TLDs.

For the time being, we'll concern ourselves with only the name suggestion capability of the NAME SUGGEST API call. In later articles, we'll explore this API CALL in greater depth.

The table below shows the required parameters for the NAME SUGGEST API call:

Key	What the Value Does
action	Specifies the action to take. In the case of NAME SUGGEST, it's the string NAME_SUGGEST.
object	Specifies the object upon which the action is taken. In the case of NAME SUGGEST, it's the string DOMAIN.
attributes	An associative array containing the named parameters for the API call, with each element in the array corresponding to a parameter. Here are the required elements for the attributes array for NAME SUGGEST (there are a number of optional ones as well; see the OpenSRS API Specification for details): Key What its Value Is searchstring The word or phrase on which the results will be based. tlds An array containing the top-level domains that should be returned as suggestions. Allowed values for elements of this array are: .com .net .org .biz .info

Turning it Into PHP Code

If you were to take the table above and turn it into a PHP array assigned to the variable $cmd, it would look like this:

$cmd = array(
    'action'     => 'NAME_SUGGEST',
    'object'     => 'DOMAIN',
    'attributes' => array(
        'searchstring' => /* Word or phrase on which suggestions
                             are based goes here */,
        'tlds'         => /* Array of TLDs for returned suggestions
                             goes here */ 
    )
);

Let's suppose we want to get some suggestions for .com domain names based on the word “garlic”. It doesn't take much to take the array assignment shown above and turn it into an application that provides those suggestions:

<?php
require_once 'openSRS.php';
$srs = new openSRS('LIVE', 'XCP');    
$cmd = array(
    'action'     => 'NAME_SUGGEST',
    'object'     => 'DOMAIN',
    'attributes' => array(
        'searchstring' => 'garlic',
        'tlds'         => array('.com')
    )
);
$result = $srs->send_cmd($cmd);
print_r($result);
?>

If you take the code above and run it, you'll see a lot of output. Here's just a small snippet of the result:

Array ( [_OPS_version] => 0.9 [protocol] => XCP [response_text] => Command completed successfully [action] => REPLY [response_code] => 200 [attributes] => Array ( [lookup] => Array ( [count] => 1 [response_text] => [response_code] => 0 [is_success] => 1 [items] => Array ( [0] => Array ( [domain] => garlic.com [status] => taken ) ) ) [suggestion] => Array ( [count] => 100 [response_text] => [response_code] => 0 [is_success] => 1 [items] => Array ( [0] => Array ( [domain] => garlicgood.com [status] => available ) [1] => Array ( [domain] => garlicmothers.com [status] => available ) [2] => Array ( [domain] => garlicsten.com [status] => available ) [3] => Array ( [domain] => garliccity.com [status] => available ) [4] => Array ( [domain] => garlic-good.com [status] => available ) [5] => Array ( [domain] => garlic-mothers.com [status] => available )…

What the Result Means

As with the result of the LOOKUP DOMAIN API call covered in the previous article, the result of NAME SUGGEST is an associative array.

Here's an illustration of the more important elements of the associative array that you get in response to the NAME SUGGEST call:

Key	What the Value Does
response_code	An integer that represents the server's response. Response codes fall into these broad categories: 200 - 299: The operation was successfully performed. In the case of NAME SUGGEST, a response code of 200 means that the operation was performed successfully. 300 - 399: Temporary failure or deferral. Typically this means that you've sent too many commands in too short a span of time or you've exceeded the maximum number of simultaneous connections allowed. 400 and up: Error. Perhaps authentication failed, you sent something that the server doesn't understand, performed something you're not allowed to do or have exceeded some quota.
response_text	The English version of the response code. This is subject to change, so if you're testing the server's response, it's generally better to use the response code.
is_success	1 if the operation was performed successfully, 0 otherwise.
attributes	An associative array containing any data that might be returned as a result of the operation: Key What its Value Is lookup An associative array containing the results of the domain name lookup based on the given word or phrase. See the table below for details. suggestion An associative array containing the domain name suggestions based on the given word or phrase. See the table below for details.

Extracting Information from the Result

The information that we really want is contained within the lookup and suggestion arrays within the attributes array. Both lookup and suggestion have the same structure, which is shown below:

Key	What the Value Does
count	The number of results returned (that is, the number of items in the items array).
items	If this is in the “lookup” array: this is an array of associative arrays containing the results of the lookup. If this is in the “suggestion” array: this is an array of associative arrays containing the suggested domain names. Whether this is the lookup or suggestion array, the items array contains arrays with the structure shown below: Key What it Does domain If this is in the “lookup” array: this is a domain name that has been looked up. If this is in the “suggestion” array: this is a domain name suggestion. status This is one of: available taken undetermined

As you can see, the really useful information is rather deeply buried in the result array. To make getting at this information a little bit easier, I wrote a function called extractResults:

function extractResults($resultType, $rawResult)
{
    return $rawResult['attributes'][$resultType]['items'];
} // extractResults()

extractResults expects two arguments:

• $resultType: A string specifying which results to extract. It can be either lookup or suggestion.
• $rawResult: The unprocessed array resulting from the send_cmd method of the OpenSRS-PHP object.

wrote a function called displayResults that makes use of ExtractResults:

function displayResults($resultType, $rawResult)
{
    $results = extractResults($resultType, $rawResult);
foreach($results as $result) {
        echo("{$result['domain']} : {$result['status']}<br />”);
} // foreach
} // displayResults()

displayResults expects two arguments:

• $resultType: A string specifying which results to display. It can be either lookup or suggestion.
• $rawResult: The unprocessed array resulting from the send_cmd method of the OpenSRS-PHP object.

An App With More Readable Output

Now we have the constituent pieces of a simple domain name suggestion app, the code for which is shown below:

<?php
require_once 'openSRS.php';
$srs = new openSRS('LIVE', 'XCP');    
$cmd = array(
    'action'     => 'NAME_SUGGEST',
    'object'     => 'DOMAIN',
    'attributes' => array(
        'searchstring' => 'garlic',
        'tlds'         => array('.com')
    )
);
$result = $srs->send_cmd($cmd);
echo("<h1>Lookup Results</h1>");
displayResults('lookup', $result);
echo("<h1>Suggestion Results</h1>");
displayResults('suggestion', $result);
function extractResults($resultType, $rawResult)
{
    return $rawResult['attributes'][$resultType]['items'];
} // extractResults()
function displayResults($resultType, $rawResult)
{
    $results = extractResults($resultType, $rawResult);
foreach($results as $result) {
        echo(”{$result['domain']} : {$result['status']}<br />”);
} // foreach
} // displayResults()
?>

What's Next

More on the NAME SUGGEST API call, and improvements to the app's user interface.

Posted on Monday, December 11th, 2006 at 8:25 pm by Tucows.
Filed under: Domain Names, Programming.
Both comments and pings are currently closed.