PHPlib is a set of PHP classes created primarily by Kristian Koehntopp (and added to by many others) to implement visitor sessions, and to present a consistent and easy way to handle forms, tables and data base connectiions. You must have PHP (or the midgard-enabled PHP) installed and configured into your apache to use it. A database is not required. You may use shared memory or ldap for many of its functions instead. However, you will already have mySQL installed for use with Midgard.
Pick up the lastest stable version at
cd into the temporary directory and execute
$> tar zxvf phplib-x.x.tar.gz
This will create several directories, including a php/ directory and a doc/ directory. Copy the contents of the php directory into a directory cgi-bin/php where cgi-bin is your script directory set up by your apache installation. If you want to try the installation tests, follow the directions given in files in the doc directory.
Assuming that you have created a cgi-bin/php directory to hold the phplib class definitions, add the following lines to your httpd.conf:
ScriptAlias /php/ "<path-to>/cgi-bin/php/" <Location /php> ... options you would like to enable/disable </Location> php3_include_path <path-to>/cgi-bin/php:<other-php-files>:.: php3_doc_root <path-to>/cgi-bin/php php3_track_vars On php3_upload_tmp_dir /tmp-or-whatever-you-want AddType applicatoin/x-httpd-php3 .php3 AddType applicatoin/x-httpd-php3 .php
The above assumes a combined configuration file, which you should be using for a midgard-enabled release of apache.
In the main part of the configuration file, put the following:
ScriptAlias /php/ "<path-to>/cgi-bin/php/" <Location /php> ... options you would like to enable/disable </Location> php3_track_vars On
Within each virtual host container, include some version of the following:
php3_include_path <path-to>/cgi-bin/php:<other-php-files>:.: php3_doc_root <path-to>/cgi-bin/php php3_upload_tmp_dir /tmp-or-whatever-you-want
When you read the documentation for PHPLib, it will instruct you to turn on different implementations of magic quotes. Midgard wants to have magic quotes turned off. I have had success with simply processing any input which may contain quotes explicitly.
The Midgard element, code-compat, is processed before the ROOT page element and its children. Within the code-compat element, include() the PHPLib classes you wish to use. Rather than change the PHPLib classes, you will want to create derived classes to suit your particular usage, and the manual gives you good working examples of how to do so.
The following pertains to the stable (current) release of PHPLib, 7.2. There are newer releases with more functionality which you may want to examine when you are comfortable with using it. This will not be a complete tutorial on how to use PHPlib, but rather an overview of how I used it within Midgard, and why I made the choices I did.
The objective was to add shopping cart functionality to my Midgard-based site. The choices are cookie-based cart (sending cookies back and forth listing the items) or implementing the "session" concept where there is a "session id" that is propagated among the different pages the visitor -- well, visits. The session id could be carried via cookies, but our target market includes many corporate buyers who may have cookies disallowed by company policy. PHPLib handles this well.
I have followed the layout of the PHPLib manual in this overview, and I am only giving details on the functions which I use. The manual is an excellent resource, and don't forget the PHPLib mailing list archives.
Core functionality is pretty much the "built-in" set of classes.
The Session class is the basis for all other classes. The derived session class allows you to select the type of DataBase you will be using (if any) from among pretty much all the Databases with which PHP communicates. You will also select the method used for storing information between page calls. The choices include DataBase, shared memory and ldap. I started with shared memory, but soon realized that a server reboot caused the data to be lost, so I changed to data base storage.
Session and your derived session class must be included on every page.
PHPLib has an Authorization class, but I chose not to use it. In some cases I will use the Midgard authorization mechanism, and in others, I will create my own since the one in PHPLib is limited. Also, the mailing lists seem to indicate difficulties with the class. This is my opinion only, and many people have apparently used it with no or few problems.
I don't use the PHPLib User class for the same reasons I chose not to use Auth.
The Db class provides a db-engine-independent interface to many different data bases. Create a derived class selecting which DB you want to use. Most of the DBs supported by PHPLib are also supported here. My DB of preference is PostgreSQL, and I use this for products, orders, users, in parallel to the mySQL db which contains Midgard.
Cart implements the item saving and display functions. If you have a shopping cart, you MUST include Cart on every page or the contents will be lost.
A class for people who aren't lucky enough to be using Midgard.
This is a standardized query class which I tried using but seemed to have some problems with PostgreSQL idiosyncrasies. My understanding is that it works well with MySQL, but I just abandoned it.
Table works well with Forms (below) to display a product catalog. The 7.2 version I am using only offers an optional checkbox, but it is very easy to change to add a text input box for quantity. Create a derived table class which associates your chosen data base. You may also have the capability of mapping field names to header labels.
You have complete control over your layout by creating a <classname>.ihtml file describing the layout. <classname> is the name of your personal class which you derived from Oohforms. It is considered to be an include within a PHP function, so you must explicitly define globals, but you have the complete power of PHP and Midgard for the layout. This layout can be considered to be within the <(content)> element of your Midgard page.
Oohforms has changed considerably since the release I am using, so I will forego details.
I have not used this class.