Description
===========
MPS stands for MySQL+PHP Phone Search, just about the worst name I could think
of. It's is meant to be a library to query a MySQL address database
compatible with the one generated by FoonRIP. This library consists of 2 classes
defined in clientlib.php. Apart from querying a MySQL database it's also
possible to query a remote XML-RPC server (server included as xmlserver.php).
Also included in this distribution is a sample html interface
(search.(php|html)+extrecord.php) which must be configured through config.php.
Everthing was created with the idea of creating fast SQL queries, either
by making really slow queries impossible or altering the db in such a way to
take maximum advantage of indices.
The database is compatible with the FoonRIP 0.74bX database. For support of 
earlier foonrip versions try earlier MPS versions (if you ask nicely I'll probably 
fix bugs in old versions). 
MPS is not affiliated with FoonRIP, nor does it in any way encourage
anything not legal. It's just a way to search in an address database compatible
with FoonRIP's.


Requirements
============
* MySQL 3.23 or higher
* Webserver with PHP 4.0.4 or higher
* Filled database (see doc/import-fr.txt for an explanation about importing 
  FoonRip txt files)
* PHPlib library (or at least "template.inc" from that library) 
  (http://phplib.sf.net)
* XML-RPC library: http://phpxmlrpc.sourceforge.net/ (only if you intend to use
  XML-RPC)
  

Install
=======
First the preparation of the MySQL database. new-db-def.sql contains the db
definition. 

If you want to import FoonRip's txt files read doc/import-fr.txt. 

In case you want to use FoonRIP's database (based on FoonRip's mysqlddl.txt) 
you should consider 2 changes. Neither of the 2 changes are necessary, 
everything should work with an unaltered FoonRIP db, but the proposed db changes
 improve query speed significantly. Neither change depends on the other.
alter-table.sql makes some alterations to 2 tables. This means MySQL creates
a temporary table with the new table definition and copies the data from the
old to it. So you need at least as much temporary disk space as the subscriber
table uses (in my case about 450meg). Of course it also takes quite some time
to do this.
add-idx.sql adds some indices. These extra indices take up permanent extra disk
space, it also takes quite some time to create the indices.

If you want to use one of the sample interfaces (html or XML-RPC server) just 
copy doc/config.php.sample to the main MPS dir as config.php and edit it as the
inline comments suggest. 
For the sample html interface you need PHPlib's template system installed. You can 
get PHPlib at phplib.sf.net. Either install it completely like indicated in the
PHPlib archive or just copy PHPlib's "template.inc" to the main MPS directory 
or to PHP's global include directory.
To use the sample interface just load search.html and take it from there.

If you want to use the XML-RPC server or client you also need to install the 
following XML-RPC library for PHP: http://phpxmlrpc.sourceforge.net/. Make sure 
you copy xmlrpc.inc and xmlrpcs.inc either to the main MPS dir or to PHP's 
global include dir.

If you want to develop your own interface you can include the appropriate 
classes from the "classes" dir. Take a look at search.php, extrecord.php and 
xmlserver.php for examples.


MySQL
=====
The classes in clientlib.php expect that a connection to the MySQL server has
already been made.
If you decide to use the sample html interface you also need search.html,
search.php and config.php in the same directory as clientlib.php. An example of
config.php has been included in /doc/config.php.example. search.html contains
the html form to start a search with.
If you also want to offer a XML-RPC interface you also need xmlserver.php
which also needs config.php


XML-RPC
=======
As a result of discussions on the FoonRIP forums about querying remote servers
both an XML-RPC server and client has been included. XML-RPC was chosen as the
protocol because there are libraries available for just about every programming
language you can think of.
The included server and client both depend on the XML-RPC library for PHP which
can be found at http://phpxmlrpc.sourceforge.net/. You need to put xmlrpc.inc
and xmlrpcs.inc in PHP's include path or in the same directory as clientlib.php
and xmlserver.php. The speed is a bit dissappointing (1.5sec per query
using XML-RPC (xmlserver on localhost), 0.3sec in case of direct MySQL). I'm
planning to implement a version wich takes advantage of PHP's built in XML-RPC
functions. Those should be faster but are only availble in 4.1.0 and higher and
aren't considered stable yet.
If you want to use xmlserver.php be sure you edit config.php to contain the
correct MySQL connection details.


XML-RPC info for developers
===========================
xmlserver.php understands 2 methods: "mps.search" and "mps.extrec". Both expect
the request as a HTTP_POST action. 

"mps.search" uses clientlib's mp_search class to search the database for the 
given parameters. It expects the request to be a struct containing the following
 entries:

Name       Type
phone   => string
srname  => string
strt    => string
town    => string
pc      => string
limit   => int
offset  => int
order   => string

The server replies with an array of structs. With each struct containing:

Name       Type
id      => int
phone   => string
aclen   => int
inis    => string
srname  => string
strt    => string
hno     => int
hnpf    => string
company => string
pc      => string
town    => string

"mps.extrec" uses clientlib's mp_extrecord class to retrieve extended data from
the datbase for a single SubscriberId. It expects the request to be the 
SubscriberId as an int.
The server replies with the following struct:

Name       Type
id      => int
phone   => string
aclen   => int
inis    => string
srname  => string
strt    => string
hno     => int
hnpf    => string
company => string
pc      => string
town    => string
info    => array

The info array is an array of the following struct type:

Name       Type
id      => int
phone   => string
aclen   => int
remarks => string


Contact Information
===================
Email: xim@xs4all.nl
IRC: XiM on irc.icerealm.net (you can usually find me in #icerealm or #xim)
Website: http://xim.d2g.com

$Id: README,v 1.14 2002/07/25 19:49:28 Martijn Exp $