head	1.4;
access;
symbols
	HORDE_1_3_2:1.3
	HORDE_1_3_1:1.3
	horde-dev-20000104:1.3;
locks; strict;
comment	@# @;


1.4
date	2000.05.02.15.17.15;	author chuck;	state dead;
branches;
next	1.3;

1.3
date	99.12.28.01.13.58;	author jon;	state Exp;
branches;
next	1.2;

1.2
date	99.09.23.04.20.28;	author jon;	state Exp;
branches;
next	1.1;

1.1
date	99.09.10.09.52.52;	author rkrusty;	state Exp;
branches;
next	;


desc
@@


1.4
log
@PHPLIB is no longer needed.
DATABASE was specific to phplib; I think we should just re-write it from
         scratch once we have a concrete idea of db use in the post-phplib
	 world.
INSTALL is updated to reflect that php4 is required, and you don't need
        phplib anymore.
@
text
@Horde-specific Notes for PHPLIB                                  docs/PHPLIB
=--------------------------------------------------------------------------=

$Author: jon $
$Revision: 1.3 $
$Date: 1999/12/28 01:13:58 $

Obtaining PHPLIB
~~~~~~~~~~~~~~~~
phplib can be obtained from http://phplib.netuse.de/


Installing PHPLIB
~~~~~~~~~~~~~~~~~
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 directed at 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)  Obtain the phplib archive.  Information on the latest Horde-supported
    version of phplib can be found at http://horde.org/phplib/.  Uncompress
    the phplib distribution archive in some temporary location.

2)  Copy the entire php/ subdirectory from the phplib 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.

3)  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
        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 comma-deliminated.

    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.

4)  Copy horde/phplib/*.ihtml to /usr/local/apache/php/.

5)  Copy horde/phplib/horde_phplib.inc to /usr/local/apache/php/local.inc.

6)  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.

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

    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.
@


1.3
log
@Revising the phplib installation instructions.
@
text
@d5 2
a6 2
$Revision: 1.2.2.1 $
$Date: 1999/12/28 01:07:26 $
@


1.2
log
@
jon: updating the PHPLIB docs a little bit
@
text
@d1 1
a1 1
Horde-specific Notes for PHPLIB                                   doc/PHPLIB
d4 4
d10 1
a10 2
phplib can be obtained from http://phplib.de/
The main phplib site in located at http://phplib.netuse.de/
d15 34
a48 1
Install it as per the phplib documentation.
d50 38
a138 2

$Id: PHPLIB,v 1.1 1999/09/10 09:52:52 rkrusty Exp $
@


1.1
log
@[IEM] adding in PHPLIB document (from phplib/README) (more deb updates)
@
text
@d1 1
a1 1
Horde-specific Notes for PHPLIB                                phplib/README
d7 1
d66 1
a66 1
$Id: README,v 1.2 1999/07/21 07:34:01 jon Exp $
@

