Zend_Whois - Ben Scholzen

{zone-template-instance:ZFDEV:Zend Proposal Zone Template}
{composition-setup}
{zone-data:component-name}
Zend_Whois
{zone-data}

{zone-data:proposer-list}
[Ben Scholzen|mailto:mail@dasprids.de] (lead)
[~weppos] (contributor)
{zone-data}

{zone-data:revision}
1.0 - 6 September 2007: Initial proposal
1.1 - 29 December 2007: Proposal rewrite
1.2 - 30 December 2007: Zend_Whois_Result added
1.3 - 13 January 2008: Finalized proposal (added support for Zend_Uri and last improvements)
{zone-data}

{zone-data:overview}
Zend_Whois is a component to simply check the availability of domain names and ip addresses and fetch whois server responses about them.
{zone-data}

{zone-data:references}
* [RFC 3912|http://tools.ietf.org/html/rfc3912]
{zone-data}

{zone-data:requirements}
* This component *will* check for registration availability of domain names.
* This component *will* allow fetching of server responses.
* This component *will not* return specific data about domain owners (as a first version), as the output varies from most of the whois servers.
* This component *will* allow caching results via Zend_Cache.
* This component *will* be customizable. It will shipped with a default list of whois server that can be completely overwritten or customized.
* This component *will* allow querying multiple domains simultaneously through a non-blocking socket.
{zone-data}

{zone-data:dependencies}
* Zend_Exception
* Zend_Cache
* Zend_Uri
* Zend_Config (as soon as this component will correctly support XML attributes)
{zone-data}

{zone-data:operation}
Zend_Whois will take a Zend_Whois_Config as constructor arguments.
If empty, default configuration set will be loaded from XML.

Once you have a valid instance, it can then be used to either get a whois response from a whois server or to check whether given domain is available.
The former returns a full whois response, the latter only true/false according to whois response.

Domain name can be one of the following formats:
* string, just the domain name (zend.com)
* string, full host name (framework.zend.com, zend.com, http://framework.zend.com)
* string, full path (framework.zend.com/path, zend.com/path, http://framework.zend.com/path)
* Zend_Uri instance

Regardless the format, internally Zend_Whois will handle all host names as an instance of Zend_Uri.
Depending on [Zend_Uri Improvements - Shahar Evron] proposal implementation, Zend_Uri instance will use http schema or a custom one.
{zone-data}

{zone-data:milestones}
* Milestone 1: [DONE] Creating base class
* Milestone 2: [DONE] Supporting all major Top-Level-Domains
* Milestone 3: [DONE] Checking current state into http://zend_whois.svn.dasprids.de/
* Milestone 4: [DONE] Finalizing the proposal and making it ready for review
* Milestone 5: Proposal acceptance and import of current prototype to incubator SVN
* Milestone 6: Unit tests exist and development.
* Milestone 7: Documentation
{zone-data}

{zone-data:class-list}
* Zend_Whois
* Zend_Whois_Exception
* Zend_Whois_Config
* Zend_Whois_Result
{zone-data}

{zone-data:use-cases}
{deck:id=Use Cases}
{card:label=UC-01}

*Creating a new instance (simplest case)*

{code}
$whois = new Zend_Whois();
{code}

{card}
{card:label=UC-02}

*Creating an instance with custom configuration*

{code}
$config = new Zend_Whois_Config('foo.xml');
$whois = new Zend_Whois($config);
{code}

{card}
{card:label=UC-03}

*Checking domain availability*

{code}
$whois = new Zend_Whois();
$isAvailable = $whois->isAvailable('zend.com'); // true

// alternative

$whois = new Zend_Whois();
$result = $whois->query('zend.com');
$result->isAvailable();
{code}

{card}
{card:label=UC-04}

*Querying whois server*

{code}
$whois = new Zend_Whois();
$result = $whois->query('zend.com'); // Zend_Whois_Result
{code}

{card}
{card:label=UC-05}

*Querying whois server with uncommon domain values*

{code}
$whois = new Zend_Whois();

// from domain
$whois->query('zend.com');

// from subdomain
$whois->query('framework.zend.com');

// from URL
$whois->query('http://framework.zend.com/path');

// from Zend_Uri
$uri = Zend_Uri::factory('http://foo.com');
$whois->query($uri);
{code}

{zone-data}

{zone-data:skeletons}
{deck:id=Use Cases}
{card:label=Zend_Whois_Exception}
{code}
class Zend_Whois_Exception extends Zend_Exception
{}
{code}
{card}
{card:label=Zend_Whois}
{code}
class Zend_Whois
{
/**
* Zend_Whois provides a simple interface for querying a whois server.
* If $config is null, Zend_Whois will use the built-in config file
* for finding the correct whois server.
*
* Zend_Whois follows the specification of the RFC 3912:
* http://tools.ietf.org/html/rfc3912
*
* @param Zend_Whois_Config $config
*/
public function __construct(Zend_Whois_Config $config = null)
{}

/**
* Set the cache for the whois server results.
*
* @param Zend_Cache_Core $cache
*/
public function setCache(Zend_Cache_Core $cache)
{}

/**
* Disable the cache. This has the same effect like calling setCache(null).
*/
public function disableCache()
{}

/**
* Allow or disallow redirection from whois servers.
*
* @param bool $allow
*/
public function allowRedirection($allow)
{}

/**
* Gets the raw response from the whois server
*
* @return Zend_Whois_Result
*/
public function query($domain)
{}

/**
* Get the response of a whois server
*
* @param array $data
* @param string $server
* @return array
*/
protected function _getResponse($data, $server = null)
{}

/**
* Returns the whois server for the given hostname.
*
* @param string $hostname
* @return string
* @throws Zend_Whois_Exception
*/
protected function _getWhoisServer($hostname)
{}
}
{code}
{card}
{card:label=Zend_Whois_Config}
{code}
class Zend_Whois_Config
{
/**
* Read the given config file and parse it
*
* @param string $filename
* @throws Zend_Whois_Exception
*/
public function __construct($filename)
{}

/**
* Get a possible content response from the config to parse the response
*
* @param string $server
* @return string
*/
public function getContentResponse($server)
{}

/**
* Check, if the response contains a redirect directive.
*
* @param string $server
* @param string $response
* @return string
*/
public function checkForRedirect($server, $response)
{}

/**
* Get the whois server for a specific hostname
*
* @param string $hostname
* @return string
*/
public function getWhoisServer($hostname)
{}

/**
* Parse a struct to find a corespondending whois server. If
* no whois server is found after all, return null.
*
* @param string $hostname
* @param string $structName
* @return string
*/
protected function _parseStruct($hostname, $structName = null)
{}

/**
* Check an IP adress against a CIDR
*
* @param string $cidr
* @param string $ip
* @return boolean
*/
protected function _cidr_match($cidr, $ip)
{}
}
{code}
{card}
{card:label=Zend_Whois_Result}
{code}
class Zend_Whois_Result
{
/**
* Create a new result object
*
* @param string $hostname
* @param string $server
* @param string $response
* @param Zend_Whois_Config $config
*/
public function __construct($hostname, $server, $response, $config)
{}

/**
* Get the raw response of the whois server
*
* @return string
*/
public function getResponse()
{}

/**
* Get the name of the whois server which supplied the response
*
* @return string
*/
public function getWhoisServer()
{}

/**
* Check if the hostname is registered.
*
* @return bool
*/
public function isAvailable()
{}

/**
* Magic string conversion, will return the raw response.
*
* @return string
*/
public function __toString()
{}
}
{code}
{card}
{deck}
{zone-data}

{zone-template-instance}