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 foondump (http://www.foondump.nl). It used to 
work with FoonRIP, but FoonRIP development has stopped. If you're still using 
a FoonRIP database, you'll want MPS-0.4, the last version supporting FoonRIP. 
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 foondump 4.01 database.  
MPS is not affiliated with foondump, 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 4.0.0 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
=======
MPS assumes you've already made a foondump rip of the cdfoongids directly to 
mysql. Don't try to use an intermediate csv file, only the direct mysql rip
actually rips all needed information. Unless you have already used the webinterface
supplied by foondump (fs2004.php), you also need to run the sql commands from 
db/alter-db-req.sql.

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 or psearch.html (for pink search)
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 mp_search.php, mp_extrecord.php and 
xmlserver.php for examples.


MySQL
=====
MPS expects 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. 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 old 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.
At the moment both the server and client-side implementation of XML-RPC is 
broken. 


XML-RPC info for developers
===========================
With the complete XML-RPC implementation broken, please don't use the following
information for your own project. I expect to unbreak it I will need to 
completely overhaul the code and the interface.
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

Attribution
===========
The idea to check the town and streetname prior to searching and let the user 
choose the right one if multiple matched came from foondump (GPL licensed, 
http://www.foondump.nl).

Contact Information
===================
Email: martijn@boerwinkel.nl 
IRC: XiM on irc.blackcobalt.net (you can usually find me in #blackcobalt or #xim)
Website: http://www.boerwinkel.nl/mps

$Id: README 407 2004-06-08 22:30:14Z martijn $
