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),
'registar' (the company name of the registry), 'rwhois' is extra
rwhois informatio has been found and 'type' which can be 'domain',
'ip' or 'AS'.

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 where the key is the canonical name
			   of each nameserver and the value is the
			   ip adresss (if none) of the server.
		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
		referer -> sponsor's URL
		handle  -> domain handle
		source  -> who gives this information

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

		name	-> network/AS name		
		inetnum	-> network ip address range
		desc	-> network description
		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  -> network/AS handle
                source  -> who gives this information

	AS
	--

	Only when dealing with Autonomus systems, could contain
	the same subkeys as network.

	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, 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

	customer
	--------

	when extra rwhois information about ip address space
	delegation is available this subkey could contain the
	following subkeys: owner, network, admin, tech, ...
	which in turn could have the same subkeys as the same
	keys in the previous level.

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.

Dates (created/changed/expires) are always returned in the format
yyyy-mm-dd.


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. 

If some tld needs special parameters or can be queried in
another whois servers or web base whois servers you can setup
rules in whois.servers.php so phpWhois can do the right thing.

There is also a naming schema that must be followed, country
handlers are named whois.XX.php, where XX is the iso country
code. The handler must also define __XX_HANDLER__ and implement
a class named xx_handler with a function named parse that takes
two arguments: $data_str and $query. $data_str['rawdata']
contains the raw output of the query and is what need to be parsed
in order to generate the Common Object Model. $query contains
the domain, ip adrress or AS that it's being queried. That function
must return an array with any available result in the format defined
by this document. Country handlers must be defined in the file
whois.servers.php on the array DATA where the key is the iso
country code and the value the handler name (xx).

Handlers for .com/.net/.tv domains are defined in whois.gtld.php
and are named whois.gtld.xxx.php where xxx is the name of the
handler defined as the value in the array REGISTRARS in the
file whois.gtld.php. It must be implemented the same way as
country handlers.

Some useful utility functions have been written to aid in developing
handlers. They are contained in whois.parser.php. Almost all handlers
use functions provided by that file. You can see how they work by
looking into the code. You also have a handler.template.php file
with the squeleton of a handler.

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

Some support functions have been developed to help you write new
handlers, those functions are stored on the following files:

- generic_parser_a:

  contains code to parse whois outputs in RPSL format, like this one.
  You could take a look at whois.at.php to see how you could use it:

  domain:         nic.at
  registrant:     NAIV1117337-NICAT
  admin-c:        NAR567002-NICAT
  tech-c:         GW502425-NICAT
  zone-c:         GW502425-NICAT
  nserver:        ns3ext.univie.ac.at
  nserver:        ns4ext.univie.ac.at
  nserver:        ns5.univie.ac.at
  nserver:        ns9.univie.ac.at
  changed:        20030616 12:54:18
  source:         AT-DOM
 
  personname:     
  organization:   NIC.AT Internet Verwaltungs- und Betriebsges.m.b.H.
  street address: Jakob-Haringerstrasse 8
  postal code:    A-5020
  city:           Salzburg
  country:        Austria
  phone:          +43662466920
  fax-no:         +43662466929
  e-mail:         office@nic.at
  nic-hdl:        NAIV1117337-NICAT
  changed:        20020614 17:29:04
  source:         AT-DOM
 
  personname:     NIC.AT Role
  organization:   
  street address: NIC.AT Internet Verwaltungs- und Betriebsgesellschaft m.b.H.
  street address: Jakob-Haringerstrasse 8
  street address: A-5020 Salzburg
  street address: Austria
  postal code:    
  city:           
  country:        
  phone:          +43 662 4669 0
  fax-no:         +43 662 4669 19
  e-mail:         nic-at@nic.at
  nic-hdl:        NAR567002-NICAT
  changed:        20010223 12:52:13
  source:         AT-DOM
 
  personname:     Gerhard Winkler
  organization:   
  street address: Vienna University
  street address: Computer Center - ACOnet
  street address: Universitaetsstrasse 7
  street address: A-1010 Vienna
  street address: Austria
  postal code:    
  city:           
  country:        
  phone:          +43 1 4277 140 35
  fax-no:         +43 1 4277 9140
  e-mail:         gerhard.winkler@univie.ac.at
  nic-hdl:        GW502425-NICAT
  changed:        20001205 14:06:15
  source:         AT-DOM

- generic_parser_b:

  contains code to parse whois outputs like this one, you could
  take a look at whois.neulevel.php to see how you could use it:

  Domain Name:                                 NIC.BIZ
  Domain ID:                                   D714-BIZ
  Sponsoring Registrar:                        REGISTRY REGISTRAR
  Domain Status:                               clientDeleteProhibited
  Domain Status:                               clientTransferProhibited
  Domain Status:                               clientUpdateProhibited
  Domain Status:                               serverDeleteProhibited
  Domain Status:                               serverTransferProhibited
  Domain Status:                               serverUpdateProhibited
  Registrant ID:                               NEULEVEL1
  Registrant Name:                             Customer Support
  Registrant Address1:                         Loudoun Tech Center
  Registrant Address2:                         45980 Center Oak Plaza
  Registrant City:                             Sterling
  Registrant State/Province:                   Virginia
  Registrant Postal Code:                      20166
  Registrant Country:                          United States
  Registrant Country Code:                     US
  Registrant Phone Number:                     +1.5714345757
  Registrant Facsimile Number:                 +1.5714345758
  Registrant Email:                            support@neulevel.biz
  Administrative Contact ID:                   NEULEVEL1
  Administrative Contact Name:                 Customer Support
  Administrative Contact Address1:             Loudoun Tech Center
  Administrative Contact Address2:             45980 Center Oak Plaza
  Administrative Contact City:                 Sterling
  Administrative Contact State/Province:       Virginia
  Administrative Contact Postal Code:          20166
  Administrative Contact Country:              United States
  Administrative Contact Country Code:         US
  Administrative Contact Phone Number:         +1.5714345757
  Administrative Contact Facsimile Number:     +1.5714345758
  Administrative Contact Email:                support@neulevel.biz
  Billing Contact ID:                          NEULEVEL1
  Billing Contact Name:                        Customer Support
  Billing Contact Address1:                    Loudoun Tech Center
  Billing Contact Address2:                    45980 Center Oak Plaza
  Billing Contact City:                        Sterling
  Billing Contact State/Province:              Virginia
  Billing Contact Postal Code:                 20166
  Billing Contact Country:                     United States
  Billing Contact Country Code:                US
  Billing Contact Phone Number:                +1.5714345757
  Billing Contact Facsimile Number:            +1.5714345758
  Billing Contact Email:                       support@neulevel.biz
  Technical Contact ID:                        NEULEVEL1
  Technical Contact Name:                      Customer Support
  Technical Contact Address1:                  Loudoun Tech Center
  Technical Contact Address2:                  45980 Center Oak Plaza
  Technical Contact City:                      Sterling
  Technical Contact State/Province:            Virginia
  Technical Contact Postal Code:               20166
  Technical Contact Country:                   United States
  Technical Contact Country Code:              US
  Technical Contact Phone Number:              +1.5714345757
  Technical Contact Facsimile Number:          +1.5714345758
  Technical Contact Email:                     support@neulevel.biz
  Name Server:                                 NS1.NEULEVEL.BIZ
  Name Server:                                 NS2.NEULEVEL.BIZ
  Name Server:                                 NS4.NEULEVEL.BIZ
  Name Server:                                 NS3.NEULEVEL.BIZ
  Created by Registrar:                        REGISTRY REGISTRAR
  Last Updated by Registrar:                   NEULEVELCSR
  Domain Registration Date:                    Wed Nov 07 00:01:00 GMT 2001
  Domain Expiration Date:                      Sat Nov 06 23:59:00 GMT 2004
  Domain Last Updated Date:                    Fri Nov 07 18:59:11 GMT 2003 

- get_blocks/get_contacts:

  contains code to parse whois outputs like this one, you could
  take a look at whois.ch.php to see how you could use it:

  Domain name:
  nic.ch

  Holder of domain name:
  SWITCH Internet Domains
  Dana Djurdjevic
  Neum<75>hlequai 6
  CH-8001 Z<>rich
  Switzerland
  hostmaster@switch.ch
  Contractual Language: English

  Technical contact:
  SWITCH Gesch<63>ftsstelle
  Andrea Tognola
  Network
  Limmatquai 138
  CH-8001 Z<>rich
  Switzerland
  hostmaster@switch.ch

  Name servers:
  merapi.switch.ch	[130.59.211.10]
  scsnms.switch.ch	[130.59.1.30]
  scsnms.switch.ch	[130.59.10.30]

  Date of last registration:
  31.12.1995

  Date of last modification:
  22.12.2003

Credits
-------

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