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 this first installment, I'll show you the Duke of URL in action, talk a little bit about OpenSRS and introduce the OpenSRS-PHP library.

Duke of URL

Last week, I put together a little application called Duke of URL. It's a simple little web application that, outputs a list of up to 100 available domain names based on a word or phrase that you enter. By default, it provides .com domains, but you have the option of asking for .net, .org, .biz and .info names if you like. If you haven't tried it yet, visit http://dukeofurl.biz and see if it comes up with some must-register domain names — you never know, they could make you some money!

Duke of URL is a pretty simple application. Most of the heavy lifting is done by OpenSRS, the Tucows service that allows you to provision all sorts of internet services:

• Domain names
• Digital certificates
• Email and anti-spam
• Web page building and blogging tools

I wrote Duke of URL to demonstrate a newly-added call in the OpenSRS API, NAME SUGGEST. As NAME SUGGEST's name suggests (hah!), it provides a list of available domain name suggestions based on a given input string. The NAME SUGGEST call is a useful feature if you sell domain names: often, the domain name a customer wants is already taken, and as a result, they simply shrug their shoulders and never register a domain. By providing alternate domain names based on a keyword or phrase, customers who can't get the domain name they want can get a suitable (or possibly better) alternative name, and you get to make a sale.

(Duke of URL is also good for brainstorming URLs and site names. My friend George and I used it and came up Global Nerdy, which we use for our tech news blog.)

PHP

When Tucows first got into the business of wholesaling internet services, Perl was the language of choice for developing web apps. That's why our original client code — the RCL, short for Reseller Client Library — was (and still is) written in Perl. The RCL isn't a complete client, but a library upon which you can build a Perl-based OpenSRS client application.

Over the past few years, Perl's use in web development has been eclipsed by PHP. In response to this, we developed a new client, CCS (Client Code Suite) in PHP. Unlike the RCL, CCS is a complete application for a web site that provisions domain names and Blogware blogs and ties into our Platypus billing/account management system.

Here's the problem: if you're a PHP programmer looking for a library that will allow you to access the OpenSRS API, you're stuck. CCS is overkill, and RCL's in the wrong language.

Luckily, there's a solution: the OpenSRS-PHP Libary.

OpenSRS-PHP

OpenSRS-PHP is a small library written by Colin Viebrock, who used to work at a Tucows partner, then worked with us for a while, and then went off to pursue other interests (among other things, he helped put together a hilarious show, Top Gun! The Musical). OpenSRS-PHP takes the headache out of assembling the XML message, opening a connection to the OpenSRS servers and getting a response. Most of the time, you simply have to give it the name of the API call you want to make and the required parameters.

OpenSRS-PHP is written in PHP and is compatible with PHP 4 and 5. It requires PEAR, or more specifically the base PEAR package and the Crypt_CBC package. It's open source software licensed under the GPL.

I used OpenSRS-PHP to do the heavy lifting for Duke of URL, and it's also what drives the API Helpdesk utility. Strangely enough, even though it's used in a number of Tucows software projects, it is not an official Tucows library. As such, it's unsupported and documentation on it has been pretty sparse.

I don't think I can help with the support angle, but with the power vested in me as Tucows' Technical Evangelist, I can help with the lack of documentation. This series of articles will cover building OpenSRS client software using the OpenSRS-PHP library, and along the way, we hope that it'll help explain OpenSRS API and the general business of provisioning and managing domains as well.

Downloading and Uncompressing OpenSRS-PHP

You can download the OpenSRS-PHP library from its SourceForge download page. Note that it's compressed as a .tar.gz file; if you're on Windows, make sure that you've got a utility that can uncompress it.

The current version of the file — openSRS-php_2.8.0.tar.gz — is 29K is size and is dated December 15, 2004. Don't worry about the date: it may be a couple of years old, but it works like a charm.

When you uncompress the file, you should get a directory called opensrs-php containing the following:

• CHANGELOG: The library's version history.
• LICENSE: A copy of the LGPL.
• OPS.php: The OPS message protocol class.
• README: The “Read Me” file.
• TODO: Things to do in future implementations.
• country_codes.php: A list of 2- and 3-letter ISO country codes.
• openSRS.php.default: A sample extended class. We never call the base class directly; we call a subclass instead.
• openSRS_base.php: The base class file. This is where the “meat” of the OpenSRS library is.
• ops.dtd: The OPS DTD file (not really needed).
• test.php: A test PHP script.
• test.xml: Some test XML data (not really needed).

Building a Child Class

Once you've uncompressed the file, the next thing you should do is build a subclass of the base class, openSRS_base. The easiest way to do this is to make a copy of the openSRS.php.default file and give it the name openSRS.php.

If you open your newly-created openSRS.php file and scroll past the initial comments, you should see something like this:

require_once 'openSRS_base.php';
class openSRS extends openSRS_base {
var $USERNAME         = 'Your OpenSRS username';
var $TEST_PRIVATE_KEY = 'Your private key for the test server';
  var $LIVE_PRIVATE_KEY = 'Your private key for the live server';

The only changes you should have to make to the file are changing the values of $USERNAME, $TEST_PRIVATE_KEY and $LIVE_PRIVATE_KEY so that they contain your username, test server private key and live server private key.

(Note: You generate private keys using the Reseller Web Interface, a.k.a. the RWI.)

Save your changes — it's time to take it for a test spin!

Testing OpenSRS-PHP

If you've been following the instructions so far, taking OpenSRS-PHP for a test spin is easy. Assuming you've saved the openSRS.php file into the opensrs-php directory, move the opensrs-php directory into your web documents directory.

(Yes, I am assuming that you're working on a development machine equipped with a web server, PHP and the necessary PEAR packages.)

Point your browser at the test.php page included in the opensrs-php directory. On my system, the URL would be:

localhost/opensrs-php/test.php

If you entered the correct information into yopur OpenSRS-PHP child class, your network connection is working and the OpenSRS servers are up and running, you should get a page of results with these headings:

• Command
• Result
• Log
• OPS XML Log
• OPS Raw Log

(If you've got error reporting on, you'll probably see a number of notices as well. Don't worry about them.)

If you see the results page, congratulations! You're all set to start developing OpenSRS client applications in PHP!

What's Next

In the next installment in this series, we'll make a bare-bones implementation of a client that suggests domain names given a word or phrase.

Posted on Thursday, November 30th, 2006 at 10:34 pm by Tucows.
Filed under: Domain Names, Programming.
Both comments and pings are currently closed.