OpenSRS-PHP
A PHP class to facilitate communicatation with OpenSRS' servers

Copyright 2000, 2001, 2002, 2003 Colin Viebrock and easyDNS Technologies Inc.



HISTORY
-------

See CHANGELOG for version history



LICENSE
-------

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

This library 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
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; 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.18 or higher should be safe)
        - expat XML functions (use "--with-xml" and "--with-expat-dir=DIR"
          if you don't want to use the bundled Expat library)
		- Perl regular expressions (compiled by default, but use 
          "--with-pcre-regex=DIR" if you don't want the bundled PCRE library)

    PEAR is part of current PHP releases, but will eventually be found 
    separately at http://pear.php.net/.  Once PEAR is installed, you will need
    to install the Crypt_CBC package: http://pear.php.net/Crypt_CBC

    mcrypt libraries can be found at http://mcrypt.hellug.gr/lib/ or 
    Freshmeat.
    
    PCRE libraries and James Clark's expat are bundled with PHP 4.x.  If you
    don't want the bundled libraries, you can get them from Sourceforge at
    http://pcre.sourceforge.net/ and http://expat.sourceforge.net/
    


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 LGPL
    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)

You will also need to make sure the Crypt_CBC class is installed using PEAR.
Read the instructions at http://pear.php.net/ for the latest info on how 
to do that.

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.



BASIC 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 test (horizon) server
    var $LIVE_PRIVATE_KEY = 'abcdef1234567890';  # your private key on the live 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.



EMAIL AND WEB CERTS
-------------------

If you are planning on using the class to do email or web certs, which use the 
TPP protocol, then you have three ways to do so:

1) You can call this command right after instantiating the class:

	$O->setProtocol('TPP');

2) If you are always going to use TPP, then just set up your extended class to
use TPP by default:

	var $protocol = 'TPP';

3) You can define the environment when instantiatin the class:

    $O = new openSRS('LIVE','TPP');



OPENHRS
-------

OpenHRS (http://resellers.tucows.com/openhrs/) is basically OpenSRS's let-
us-manage-your-registry product.  It uses the same communication protocols 
as OpenSRS, so there are only a few things you need to do to the OpenSRS-PHP 
class to connect and talk to the OpenHRS system.

First, you need to add a few more parameters to the child class:

<?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 test (horizon) server
    var $LIVE_PRIVATE_KEY = 'abcdef1234567890';   # your private key on the live server

    var $HRS_USERNAME     = 'foobar-hrs';         # your OpenHRS username
    var $HRS_PRIVATE_KEY  = '0987654321abcdef';   # your private key on the HRS server
    var $HRS_host         = 'foobar.opensrs.net'; # your OpenHRS hostname

    var $environment      = 'HRS';                # 'TEST' or 'LIVE' or 'HRS'
    var $crypt_type       = 'DES';                # 'DES' or 'BLOWFISH'
    var $ext_version      = 'Foobar';             # anything you want
}

?>

From there, you proceed as normal, except you will use the HRS environment instead
of TEST or LIVE:

    $O = new openSRS('HRS');

All the OpenHRS commands you send should be identical to OpenSRS commands.



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)
- all the users who've suggested changes or provided bug fixes
- anyone else I forgot
   


CONTACT
-------

Colin Viebrock
easyDNS Technologies Inc.
304A - 219 Dufferin Street
Toronto, ON, CANADA
M6G 3J4

email: colin@easydns.com
web: http://www.easydns.com/



/* $Id: readme,v 1.1 2003/11/09 17:14:41 thomas Exp $ */
