Next Previous Contents

1. Quick Start

The Quick Start chapter tries to give you a ten-minute introduction to PHPLIB installation, outlines a few simple testing procedures and closes with an overview of PHPLIB features.

1.1 License

PHPLIB consists of the files in this directory and all its subdirectories. It is made available as free software under the LIBRARY GNU General Public license, as spelled out in the file COPYING in this directory. Also, it is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license for more details.

1.2 Target Group and Prerequisites

PHPLIB targets the PHP application developer. You need to have good knowledge of the PHP language, at least basic SQL database knowhow and at least basic knowledge on how to operate your web server to be able to use the library.

The library will help you to write medium to large sized data-driven web applications. "Medium to large sized applications" are applications that consist of multiple database queries, have to generate tables from database data, need a user interface that generates SQL queries or need a comfortable and user-friendly way to protect pages or functionality on pages. "Data-driven" applications are applications that make use of a supported SQL-database to create HTML content and that use HTML forms to drive database transactions.

To make use of the library you obviously need access to a web server with a working installation of a current PHP interpreter (we recommend 3.0.12 or newer for this release of the library) and access to a supported SQL database (currently, PHPLIB supports MySQL, PostgreSQL, mSQL, Oracle 7 and Oracle 8, Sybase, Microsoft SQL Server and ODBC databases). You need to be able to create and drop database tables in that database and your web server must be able to execute SELECT, INSERT, UPDATE and DELETE statements on these tables.

Throughout this manual, we assume that you are using the MySQL database server. PHPLIB will run with any supported SQL server, but we are using MySQL in the development of PHPLIB.

PHPLIB can be used in conjunction with the CGI version of PHP and with mod_php, integrated into Apache. Usage of the CGI version has an impact on overall speed, because you cannot take advantage of persistent database connection. We recommend the Apache module over the CGI version, although we personally use the CGI version for various reasons (easier to update and can be run with Apache suexec).

PHP 4 is still in beta. We do not support deployment of this library with beta software.

1.3 Quick Guide to Installation

These instructions apply to PHPLIB running with CGI PHP. Most of them are valid for mod_php as well, though. VERY IMPORTANT NOTE: This is a quick installation guide to get you started if you have an installation where you control the web server, PHP interpreter and database server completely. They are not suitable for a web hosting setup where you have only limited to no control over the installation. Refer to Chapter 2 of this documentation for the complete installation instructions and troubleshooting information.

Before installing PHPLIB, get your web server up and running and have it executing files with the extension .php3. Check that with a simple <?php phpinfo() ?> script. Make sure the web server accepts index.php3 as well as index.html as a default file for URLs ending in "/" (Apache: DirectoryIndex index.html index.php3).

Get your MySQL database server up an running. Create an empty database for your application and make sure the owner of your web server processes can access this database with SELECT, INSERT, UPDATE and DELETE access. Don't forget the mysqladmin reload after changing the user and db tables.

Step 1

Create an include directory named php parallel to your web servers document root directory. Do not put the include directory below your web servers document root.

Step 2

Unpack your PHPLIB distribution. Move the contents of the php distribution directory into the php directory you just created.

Step 3

Get to the php3.ini file for your web servers PHP interpreter and update the include_path statement so that it points to that php directory. Update the auto_prepend_file statement so that it points to the prepend.php3 file in that include directory.

If you do not have control over your php3.ini file, you did not read the VERY IMPORTANT NOTE above.

Step 4

Also check that track_vars are enabled and that you have enabled magic_quotes_gpc. While you are at it, you might want to check sendmail_path, if you plan to send mail from your application. It has to be set to /usr/lib/sendmail -t on most UNIX systems to work.

If you do not have control over your php3.ini file, you did not read the VERY IMPORTANT NOTE above.

Step 5

cd into the php include directory. Edit In class DB_Example supply the appropriate parameters for your database connection.

Step 6

For this database, run create_database.mysql from the distribution to create active_sessions and auth_user. auth_user will be populated with a sample user named kris with a password test.

Step 7

Move the contents of the pages directory and all its subdirectories into your document root directory.

Step 8

Access the "/" URL of your web server with cookies enabled. If no index.html is present, index.php3 will be displayed. If you reload that page, the number shown must increment. Access your database with the mysql command client and select * from active_sessions. Check that there is a single session record for your browser and see how the text in val changes when you reload the page and select * from active_sessions again. If this works, the session class is functional with cookie mode.

Step 9

Now access showoff.php3. Try to login as kris, password test. Check active_sessions again. You now should have a Example_Session entry (see the name column) and a Example_User entry in your table. Both should increment on reload.

Step 10

Try again with cookies disabled. You should get a new session (the cookie is lost) and you should be able to see your session id as the get parameter part of your URL.

1.4 Using core features of PHPLIB

Many applications don't use PHPLIB's advanced features, but see PHPLIB as a convenient way to protect pages or functionality with passwords. This section covers such core functionality usage of PHPLIB.

Customizing the login screen

Edit loginform.ihtml in the include directory to suit your needs.

Customizing the permission levels

Edit and change the class Example_Perm to enumerate your permissions. Your users in auth_user must have one or more comma separated permission names from that list. Edit perminvalid.ihtml for a suitable error message.

Creating New Users

Use new_user.php3 from the pages/admin directory of the distribution. If you followed the installation instructions, it should be available under the /admin URL of your web server.

To manually create a user, run print md5(uniqid("some magic string") to get a user id. insert into auth_user values ( "that userid", "username", "password", "permissions");.

Creating an unprotected session page

Begin that page with

<?php page_open(array("sess" => "Example_Session")); ?>

End that page with

<?php page_close(); ?>

Creating a protected session page

Begin that page with

    array("sess" => "Example_Session",
          "auth" => "Example_Auth",
          "perm" => "Example_Perm"));
  $perm->check("desired protection");

and end that page with

<?php page_close(); ?>

Creating protected functionality

Begin that page with

    array("sess" => "Example_Session",
          "auth" => "Example_Auth",
          "perm" => "Example_Perm"));

and end that page with

<?php page_close(); ?>

Enclose the protected functionality in

  if ($perm->have_perm("desired protection")):
Put protected HTML or PHP here

Note: desired protection is any combination of permissions from Example_Perm. Using the default values from Example_Perm, "user", "user,author" or "admin" are all valid sample values. A user can access a page, if that user has all permissions that are being requested in a $perm->check() or $perm->have_perm() call.

Note: Users can have multiple permission in their perms column of auth_user. A user with perms "user,author,editor" can access all pages requesting any combination of these permissions.

Note: Don't use spaces. "user,author,editor" works. "user, author, editor" does not.

Note: If $auth->auth["uid"] is set on a protected page and if (time < auth->auth["exp"]), then and only then the authentication is valid. You may then use $auth->auth["uname"] as the user name, $auth->auth["uid"] as a unique user id and $auth->auth["perm"] for the current permissions of that user. Actually, you never want to touch $auth->auth["perm"] manually, but use $perm->have_perm("...") for that.

Getting a grip on PHPLIB

Read on. Then read the source. Read it again - Session->serialize() and Auth->start() are ugly. Get a CVS account. Contribute. Become famous. Buy a ferrari.

Note: You want to understand what registered variables are. You want to understand in what order form variables and session variables are imported into your page. You want to understand how to copy values from form values into session values without killing yourself. You do not want to make form variables persistent, ever. Then you will live happily thereafter...

1.5 Testing

These instructions apply to PHPLIB running with CGI PHP. Most of them is valid for mod_php as well, though. This section offers an incremental approach to find installation problems, should the above installation process fail.

We do have a support mailing list available under the address To subscribe to the list, send the command subscribe to the address

Checking that the web server is up and running

Make sure your web server 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 web server.

Checking that the web server is executing CGI programs

Make sure your web server is up and does run CGI. Check the current directory, the UID/GID it is running programs under and have 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 executable. 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.

Checking that the PHP interpreter is running (Assuming CGI PHP)

Copy your PHP binary into the cgi binary directory (which should NOT be below DocumentRoot!) and make it executable. 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 (preferable 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.

Check the output of phpinfo() carefully! Is your PHP version current (We have tested and developed this release with PHP 3.0.12)? Are your database interfaces present in the output of phpinfo()? If not, recompile again.

Can you access /test2.php3 under the URL /cgi/php/test2.php3 as well? If so, you did not compile your PHP interpreter with --enable-force-cgi-redirect. PHPLIB will not work with this interpreter. Recompile with the switch being set.

PHP interpreter (Assuming mod_php)

Assuming your server is already correctly setup (don't forget to activate the PHP lines in srm.conf!), enter the following file and save it as test2.php3 under your DocumentRoot.

<? phpinfo() ?>

If you access this using a web browser now, it should spit out much info about PHP, Apache and its environment.

Checking PHPLIB inclusion

Does you PHP include PHPLIB properly? Check your php3.ini file. It must include the following settings:

include_path = pathname to directory with all the .inc files
auto_prepend_file = path to prepend.php3
track_vars = On

It should contain the following settings, too:

magic_quotes_gpc = On

If PHPLIB is included properly by your setup, the following page will execute without errors:

$db = new DB_Example;
print "It works without error messages.<br>\n";

Checking database connectivity

PHPLIB installation requires that you adapt properly. Particularly, the provided class DB_Example must be customized for your database connection. Test that your web server can access the database with the following page:

  include(""); // requires include_path to be functioning

  $db = new DB_Example;
  $db->query("select * from auth_user");

  $t = new Table;
  $t->heading = "on";

When executing properly, this page will show you the user entry for kris, password test, permissions admin from the auth_user table. If this does not happen, your DB_Example definition in is broken.

Checking that sessions work

Access the page /index.php3 that has been provided with the distribution. This page will try to set a cookie in your browser. Allow that cookie to be set.

The page will display a headline with a counter. Reload that page. The counter must increment. If not, either your browser cannot deal properly with cookies or PHPLIB cannot properly read or write the table active_sessions in your database. Check that the cookie is being set by viewing the output of phpinfo() (the fourth table will report the cookie and other per-call data). Check your database permissions with your database command line interface.

Checking that Authentication works

Try loading /showoff.php3 that has been provided with the distribution. This page will require a login. Login as kris, using a password of test. If the login is successful, you will see the per-session counter and a per-user counter again. Reload that page: The counters must increment.

If you can't login, you probably have a problem with cookies. Check again that your browser accepts and sends session cookies. Another problem may be access to the auth_user table. You must be able to SELECT on that table and there must be at an entry for the user you are trying to login.

Next Previous Contents