Make your own free website on
Previous Next Table of Contents

2. Setting things up

The base library is supplied at the PHP Base Library download location. Two different formats are provided: A .tar.gz version and a .shar version.

If you are on a windows system, you can use phplib.tar.gz, if you have WinZIP installed. Current version of WinZIP know how to handle compressed tar archives. The uncompressed files may be installed on your windows system or transferred to your Unix system.

If you can't handle binary files, you may download phplib.shar. This is a pure ASCII file containing a self extracting shell script. Just save the file, make it executeable and feed it to your Unix shell (for example, by typing sh phplib.shar.

2.1 Requirements and things to check for

The PHP base library requires a working web server with CGI capability and the CGI version of PHP 3.03 or higher installed. Lower versions of PHP may work (at least PHP 3.0 is required), but have not been tested and are not supported. mod_php is supposed to work and has been tested.

NOTE: As of PHPLIB release-5, PHPLIBs Auth class uses the internal variable $PHP_SELF to reference the page it was called from. This variable is produced incorrectly in older versions of CGI PHP. It is correct in mod_php and in version 3.04 or newer of CGI PHP. If you are using CGI PHP, it must have been compiled with the --enable-force-cgi-redirect switch for $PHP_SELF to have the correct value.

Basically, if PHP_SELF is the exact local part of your $URL, all is well. If it instead contains the modified URL with /your cgi-bin/php prefixed, you have a buggy version of CGI PHP. Either upgrade your version of PHP or replace all occurences of $PHP_SELF with $PATH_INFO in PHPLIB.

The PHP base library requires a database connection. Currently MySQL is fully supported and Postgres and ODBC have limited support (the limitation is only relevant if you intend to access metadata information, i.e. table definitions and the like). Database interfaces are not difficult to write and Adabas-D and Oracle are likely to be supported in the future; someone is also working on a Sybase database module.

You need a database server connection with select, insert, update and delete privileges from your CGI environment. You need create and drop privileges from an administrative account outside your CGI environment as well.

2.2 Installation procedure

Web Server

Make sure your webserver is up and serving the virtual host you just set up. To do this, construct a small file test1.html in your DocumentRoot and access test1.html through your webserver.

CGI availability

Make sure your webserver is up and does run CGI. Check the current directory, the UID/GID it is running programs under and habe a look at the environment variables. Install the shell script

#! /bin/sh --
echo "Content-Type: text/plain"
env | sort

in your cgi directory under the name of cgi-test and in your document root under the name of cgi-test.cgi. Make it executeable. Try to access /cgi/cgi-test?par1=one&par2=two and /cgi-test.cgi?par1=one&par2=two and check the output. What UID/GID are you running under, what is the output of pwd and what environment variables are set? What does QUERY_STRING look like? What does the PATH variable look like, what does the LD_LIBRARY_PATH variable look like and are all libraries needed by PHP accessible to PHP running in the CGI environment (Check by running the Unix ldd command on PHP).

In particular, if you built Oracle support into PHP and linked libclntsh dynamically: Can it be loaded from the CGI environment? If not, PHP will not come up later in the next step.

PHP interpreter

Copy your PHP binary into the cgi binary directory (which should NOT be below DocumentRoot!) and make it executeable. Copy php3.ini into the same directory. In DocumentRoot, create a test2.php3 and put <?php phpinfo() ?> into it.

Are you running Apache? Add

Action       php3-script /cgi/php
AddHandler   php3-script .php3
DirectoryIndex index.php3 index.html index.htm
FancyIndexing on

to your config. This will map all requests to files ending in .php3 to the php3-script handler and define /cgi/php as the URL handling php3-script requests internally.

Request /test2.php3 and see that it is being executed. Make changes to your php3.ini (prefereable some color definitions) and reload. Are they reflected in the output of phpinfo()? If not, your php3.ini is not being found and your are having a problem. Recompile with proper settings.

Are your database interfaces present in the output of phpinfo()? If not, recompile again.

Library Setup

Create a directory php next to your cgi:

/home/www/servers/   <- document root
                                  cgi     <- php binary
                                  php     <- includes and prepends

Make this php directory your php include directory: Put include_path = /home/www/servers/ into cgi/php3.ini.

Into the php directory go all .inc files, all .ihtml files and prepend.php3. Into documentroot, put index.php3, showoff.php3 and test.php3 (and md5.js if you are going to use Poe_Challenge_Auth, with is an advanced feature).

Have documentation.txt handy and read it.

Database access with MySQL

The following information applies to MySQL only. No information is provided for other database servers as of now. You are encouraged to copy this section and adapt it for your database server and submit it to the authors. It will be included in further releases of PHPLIB.

Edit prepend.php3. Change the first require() statement to require("");. This will include the MySQL database interface (Interfaces for other databases are provided in db_<databasename>.inc. The require() statement has to be adapted to reflect this).

Assuming your database server is named and your CGI user is webuser and you are accessing the database poe_sessions, do

mysql -h database -u webuser poe_sessions

If it does not work, connect your database as administrator and create the proper mysql access permissions. Adapt and run create_database.sql to create the databases active_sessions and auth_user as well as the sample user kris with password test. Try again to connect like shown above. Can you do select * from active_sessions? and insert into active_sessions values ("1", "2", "3", "") as well as delete from active_sessions? Can you select * from auth_user?

Merging the library with your PHP files

Decide if you want to use include or auto_prepend. We do use auto_prepend here and we add the statement auto_prepend_file = /home/www/servers/ to our php3.ini.

Not all classes are included/required by prepend.php3, only those necessary for Session pages are:,,,,,, and The library provides other, less essential classes that can be included manually on a page-by-page basis.

Having done this, I access /index.php3. The counter should increment when I reload that page. Also, checking active_sessions in the database should reflect that session.

Subscribe for support

Subscribe to the mailing list Do so by sending a mail body of subscribe to and follow instructions. Share your experiences.

2.3 Using include() instead of auto_prepend=

Support for the library is provided in the form of include files. You will have to define a valid include_path=-statement in your php3.ini file to reflect the location of the *.inc files.

We prefer to have the session based classes always present in all php3 files, so we also define a file prepend.php3, which includes all *.inc files. You can simply include this file with include("prepend.php3").

### I am prepend.php3
require(""); // change this to match your db.
require(""); // required for everything below.
require("");    // disable this, if you never authenticate.
require("");    // disable this, if you don't need permissions.
require("");    // disable this, if you don't need user variables.
require("");    // disable this, if you don't need shopping carts.

require("");   // edit this to reflect your local config.

require("");    // required to bind everything together.


Previous Next Table of Contents