Horde-specific Notes for PHPLIB                                phplib/README
=--------------------------------------------------------------------------=

$Author: bjn $
$Revision: 1.2.2.9 $
$Date: 2000/09/19 14:53:12 $

Obtaining PHPLIB
~~~~~~~~~~~~~~~~
phplib can officially be obtained from http://phplib.netuse.de/download/.
You do not need the official release of phplib to use Horde.  Read on.

Supported Versions
~~~~~~~~~~~~~~~~~~
We now distribute our own version of phplib with Horde 1.2.  This version
includes several fixes that are not part of the main phplib distribution and
are known to work correctly with Horde.  If you have an existing phplib
installation, it must be either version 7.0 (which has problems with
characters such as '$' in usernames and passwords, but otherwise works), or
version 7.3-dev (and possibly 7.2b).

Installing PHPLIB
~~~~~~~~~~~~~~~~~
This document assumes that you are installing phplib with Horde, and that
you are using the version of phplib included with Horde.  If you already
have phplib installed, the information here should enable you to get it
running with Horde fairly easily.

However, note that the following still applies:

    The phplib documentation is very concise.  Please read it before
    asking any phplib-related questions on the Horde mailing lists.
    Support for phplib itself should be obtained from the phplib mailing
    lists outlined at:

        http://phplib.netuse.de/support/

With that said, installing phplib for use with Horde and its associated
modules is rather straightforward.

1)  Copy the entire phplib/ subdirectory from the Horde distribution to a
    permanent location (eg. /usr/local/apache/php).  This directory does not
    need to live under your web server's document root, so it's probably
    safer to put it somewhere outside the reaches of lurking web clients.

2)  (Note:  step 2 can also be done by adding directives to Apache's
    httpd.conf file; for details, see the horde/docs/INSTALL section
    "Using Apache's config files to handle phplib prepends".)
    
    Edit your php3.ini file.  If you don't have one, a sample is included in
    the php distribution.  The default location for this file is in /usr/lib,
    but that may have been overridden at compile time.  Check with whomever
    installed php to verify the correct location.
    
    Note: Under php version 4, this file has been renamed php.ini.
    
    Make the following changes:
    
        include_path '/usr/local/apache/php:.'
        auto_prepend_file /usr/local/apache/php/prepend.php3
        track_vars on
        magic_quotes_gpc off
    
    The first directive (include_path) tells php to look in the following
    list of paths when including files that don't have absolute paths. The
    list is colon-delimited.
    
    The second directive (auto_prepend_file) tells php to automatically
    prepend the contents of phplib's prepend.php3 to each file.  phplib
    requires certain classes included by the file to be available on every
    page.
    
    The third directive (magic_quotes_gpc) turns off magic quotes.  See
    http://www.php.net/manual/html/configuration.html#INI.MAGIC-QUOTES-GPC
    for more information on magic quotes and php.
    
    If you're running php as a module (as opposed to a cgi binary), you'll
    need to restart your web server for these changes to take effect.
    
3)  Edit the local.inc file.  It contains your local phplib settings that
    will define the behavior of phplib.  Think of it as your phplib
    configuration file.

    The file should have a bunch of classes defined (and most of them will
    be commented out).  You'll need to select the type of storage container
    to use to hold session information.  Follow the comments in the file to
    determine which section you'll want to uncomment.

4)  Edit the prepend.php3 file.  You need to specify the proper db_*.inc
    and ct_*.inc files that match the storage container you chose in
    step 3.  For example, for PostgreSQL, set these to "db_pgsql.inc"
    and "ct_sql.inc".

5)  Once you've chosen your phplib storage container, you'll need to set it
    up to handle phplib sessions.  For example, if you chose to use an sql
    database, you'll need to add the appropriate tables as well as create a
    database user account (not a system account) with which to access the
    database.  There are scripts to add the necessary tables (as well as the
    database tables for IMP) in horde/scripts/database/.  Also in this
    directory are database-specific readme files.
    
    Unfortunately, there are too many details to outline here (such as how
    to configure your chosen database server or how to set up shared
    memory).  The phplib documentation covers this rather thoroughly, so
    please consult that before asking questions.

Once the phplib session storage is configured, you should be in good shape
to proceed with the Horde installation.

Using Multiple Databases
~~~~~~~~~~~~~~~~~~~~~~~~
There are some known issues when using multiple databases with
phplib.  These stem from the logic behind PHP's pconnect database
connection method.  Persistant connections are generally a valuable
performance improvement over settings up and tearing down a new
connection on every page load, but the implementation can be
somewhat deceiving.

PHP's pconnect methods first attempt to establish whether a
database handle already exists for a given host, username, and
password combination.  If it does, that connection handle will be
re-used, saving the effort of establishing a new connection.

If you have multiple databases and use the same username and
password combination to connect to them, PHP just returns the same
physicial connection to each.

The real problem is introduced when phplib goes to query or update
the auth_sessions table in which it caches the current session
data.  If, somewhere in the course of the page load, the database
connection handle is redirected to another database (to retrieve
user preferences, for example), phplib will _not_ automatically
switch the current database back to the one containing the sessions
table.  The query will thus fail.

To illustrate the problem more visually:

a)	Connect to database 'horde' with username 'horde' and password 'pass'.
b)	phplib updates session information in table 'auth_sessions'.
c)	Connect to database 'imp' with username 'horde' and password 'pass'.
	PHP returns the same persistant handle established in a).
d)	User preferences are retrieved from table 'imp_prefs' in database 'imp'.
e)	A new page is loaded.
f)	The same connection handle is re-used, except it's pointing to
	database 'imp' now.
g)	phplib attempts to update the session information in 'auth_sessions',
	but fails because no 'auth_sessions' table exists in database 'imp'.

There are two possible solutions should you still want to use
multiple databases:

1)	Store session information elsewhere other than the SQL database used
	by the application.
2)	Use a different username and password for each database.

The easiest solution of all is to simple keep all of the tables in
the same database, but we realize there may be cases where you'd
like to do otherwise.  You should thus be aware of the problems
that may arise, hence the reason for this section of documentation.
