OpenSRS Protocol Base Client Class
   version 2.4-beta
   17-Dec-2001



Written by Colin Viebrock <colin@easyDNS.com>
   easyDNS Technologies Inc.
   http://www.easyDNS.com


See CHANGELOG for version history



LICENSE
-------

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU Library General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at your
option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
License for more details.

You should have received a copy of the GNU Library General Public
License along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.


REQUIREMENTS
------------

The base class requires:

An account with the OpenSRS Registry (http://www.opensrs.net/)

PHP (http://www.php.net)
    The class is developed using the latest version of PHP, often the
    CVS version current as of the date of this file.  It is almost
    certainly not backwards compatible to 3.x versions, nor is it
    going to be.  PHP 4 offers so much more functionality and stability
    over PHP 3 that I encourage you to upgrade.
    
    It requires that support be compiled in for:
		- PEAR extensions (use "--with-pear")
		- the mcrypt library (use "--with-mcrypt"), as recent a stable
          version as you can get (2.4.15 or higher should be safe)
		- Perl regular expressions ("--with-pcre")

    PEAR is part of current PHP releases, but will eventually be found 
    separately at http://pear.php.net/

    mcrypt libraries can be found at http://mcrypt.hellug.gr/ or Freshmeat.
    
    PCRE libraries are part of James Clark's expat and should be part of the 
    source to PHP 4.x.
    

INSTALLATION
------------

Just gunzip and untar the archive, or do both in one step:

$ untar xvfz opensrs-php-x.x.tar.gz

You will end up with the following files:

    opensrs/CHANGELOG              - version history
    opensrs/LICENSE                - a copy of the GPL
    opensrs/OPS.php                - the OPS message protocol class
    opensrs/README                 - this file
    opensrs/TODO                   - stuff to do
    opensrs/country_codes.php      - list of 2 and 3 letter ISO country codes
    opensrs/openSRS.php.default    - a sample extended class (edit the file 
                                     and remove the ".default" before using!)
    opensrs/openSRS_base.php       - the base class file
    opensrs/ops.dtd                - the OPS DTD file (not really needed)
    opensrs/test.php               - a test PHP script
    opensrs/test.xml               - some test XML data (not really needed)

After configuring the default class (see below), try running the test.php 
script in your browser.  It should connect to OpenSRS, do a lookup, and 
output the session log.


USAGE
-----

Your first step should be to create a child class that extends the base
class, basically setting up your OpenSRS username, private keys, and
whether you want to use the test environment or live one.  Something like:

<?php
require_once 'openSRS_base.php';


class openSRS extends openSRS_base {
	var $USERNAME         = 'foobar';            # your OpenSRS username
    var $TEST_PRIVATE_KEY = '1234567890abcdef';  # your private key on the live server
    var $LIVE_PRIVATE_KEY = 'abcdef1234567890';  # your private key on the test (horizon) server
    var $environment      = 'TEST';              # 'TEST' or 'LIVE'
    var $crypt_type       = 'DES';               # 'DES' or 'BLOWFISH';
    var $ext_version      = 'Foobar';            # anything you want
}

?>


There is a sample file called "openSRS.php.default" in this distribution.  Just
edit the values in it, and rename it "openSRS.php".

With this file, you just need to include() or require() it at the top of every 
file in which you want to talk to the OpenSRS server.

To start up a connection, just instantiate the class:

	$O = new openSRS;

Or, to override the environment, do:

	$O = new openSRS('LIVE');

From there, the important function is:

	$response = $O->send_cmd($command);

This passes the command in $command to the server and returns the response.

	$O->showlog();

This outputs a (very handy, IMHO) log of your session.  The log shows all
data passed to and from the server unencrypted ... so you probably shouldn't
let your end users see its output.

You can also view the raw XML log:

	$O->_OPS->showLog('xml');

Or (for the truly hardcore) the raw binary log:

	$O->_OPS->showLog('raw');

There is also:

	$O->validate($data, [$params] );

This validates the data in $data for new domain registrations.  See the original
OpenSRS code for full details on it's usage.  It may or may not work: I've never
used it, personally.


THANKS
------

- Mike Glover <mpg4@duluoz.net> for providing the CBC emulation functions 
  and general help
- Victor Magdic at Tucows Inc. <vmagdic@tucows.com> who wrote the original
  Perl API
- the rest of the folks at OpenSRS (Ross, Dan, Charles, Erol, et al)
- anyone else I forgot
   


/* $Id: README,v 1.13 2001/12/18 02:16:10 cviebrock Exp $ */
