phpWhois.org/Handlers.md

Introduction
------------

Handlers are pieces of code that parse the raw whois output and try
to add some keys to the result returned by phpWhois. In previous
versions there was no standard about how these keys should be named
and organized, which make them registry specific. Now all handlers
have been standarized so they return a known set of keys. This is what
we call 'Common Object Model'.


Common Object Model
-------------------

The keys that you could find in the result array returned by phpWhois
are 'rawdata' , 'regyinfo' and 'regrinfo'. 

rawdata is always returned as it's filled by phpWhois itself. It
contains the raw text output returned by the whois server.

regyinfo contains information about the registry who returned that
information. It has three subkeys: 'whois' (the whois server who
returned the data), 'referrer' (the web address of the registry)
and 'registar' (the company name of the registry).

regrinfo holds the information about the domain itself. It could have
the following subkeys:

	disclaimer
	----------
	Contains the disclaimer returned by the registry.

	registered
	----------
	Contains Yes or No and indicates if the domain or ip
	address has been found (it exists).

	domain
	------
	Only when dealing with domains. Could contain the
	following subkeys:

		name	-> domain name
		desc	-> description of the domain
		nserver	-> array containing canonical names
			   of all nameservers for that domain
			   listed i n order. Optionally it can
			   also include the name server ip address
			   following the canonical name.
		status  -> status of the domain (registry dependant)
		changed -> date of last change
		created	-> creation date
		expires -> expire date
		sponsor	-> registry partner where the domain was
			   registered
		handle  -> domain handle
		source  -> who gives this information

	network
	-------
	Only when dealing with ip addresses. Could contain the
	following subkeys:

		name	-> network name
		inetnum	-> network ip address range
		desc	-> network description
		host_ip	-> ip address that was tested
		host_name> host name obtained doing reverse dns
			   lookup on host_ip
		mnt-by	-> who provided that network
		mnt-lower> who provided that network 
		nserver -> name servers in listed order that
			   provide inverse resolution for that net
		status	-> status of the network (registry dependant)
		remarks -> remarks provided by the registry
                changed -> date of last change
                created -> creation date
                handle  -> domain handle
                source  -> who gives this information

	owner,admin,tech,zone,billing,abuse
	-----------------------------------

	All of these possible keys hold information about the different
	contacts of the domain or ip address. They all could have the
	same subkeys, that are:

		organization	-> organization name
		name		-> organization responsible
		type		-> type of contact
		address		-> array containing the address, the
				   keys of that array could be just
				   numbers, could have predefined
				   subkeys or could be amix of numbers
				   and predefined subkeys. Predefined
				   subkeys are street, street2, city,
				   state, pcode and country
		phone		-> phone, could also be an array of
				   phone numers
		fax		-> fax, same behaviour as phone
		email		-> email, same behaviour as phone
		handle		-> contact handle
		mnt-by		-> who provided that contact
		created		-> creation date
		changed		-> last change date
		source		-> who provided that information
		remarks		-> remarks

Not all handlers fill values in each of the keys defined by the
Common Object Model as not all registries return the same amount
of data about a domain or ip address. Also there are some differences
on the format returned for some keys (mainly the keys that reflect
dates). 


Writing handlers
----------------

Writing handlers is easy, just look at how some of them are coded.
If you write a new handler, please try to map as many as possible
returned data to keys defined by the 'Common Object Model'. You can
create new keys if need, but please do not do create new keys where
existing predefined keys exists. Nevertheless all handlers submited
will be checked before they are added to phpWhois distribution. 

Some useful utility functions have been written to aid in developing
handlers. They are contained in generic.whois, generic2.whois and
generic3.whois. Almost all handlers use functions provided by those
files. You can see how they work by looking into the code.

Please try to mimic the coding style of the other handlers, as this
will make it easier for other people to understand and maintain.


Credits
-------

Mark Jeftovic <markjr@easydns.com>
David Saez Padros <david@ols.es>
Ross Golder <ross@golder.org>