5.3. PHP Tools

5.3.1. PHPLib

5.3.1.1. What is it

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.

5.3.1.2. How do I install it?

Pick up the lastest stable version at http://phplib.netuse.de/applications/source/index.php3, or load from CVS. (How to do this is discussed elsewhere.) Create a temporary directory in which to unpack the tarred, gzipped archive. The README file will instruct you how to set up the tests. PHPLib assumes that you have a database installed, generally mySQL, to test the installation and ensure that you have configured it correctly.

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.

5.3.1.3. How do I configure httpd to use it?

5.3.1.3.1. For a single-host server:

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.

5.3.1.3.2. For a multi-host server:

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
      

5.3.1.3.3. Gotchas

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.

5.3.1.3.4. So how do I use it with Midgard?

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.

5.3.1.3.5. One person's use of PHPLib

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.

5.3.1.3.5.1. PHPLib Core Functionality

Core functionality is pretty much the "built-in" set of classes.

5.3.1.3.5.2. Session

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.

5.3.1.3.5.3. Auth

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.

5.3.1.3.5.4. User

I don't use the PHPLib User class for the same reasons I chose not to use Auth.

5.3.1.3.5.5. DB_Sql

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.

5.3.1.3.6. Extended functionality:

5.3.1.3.6.1. Cart

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.

5.3.1.3.6.2. Templates

A class for people who aren't lucky enough to be using Midgard.

5.3.1.3.6.4. Sql_Query

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.

5.3.1.3.6.5. Table

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.

5.3.1.3.6.6. Form (oohforms)

Oohforms (Object Oriented and I forget what the 'h' stands for) are made up of a basic form class, a general element class, and specific element subclasses for the type of element. Define your form in an associative array; for each element, give the type, any restrictions such as range or required, and the class will not only allow you to display and process the form, but will also create javascript to check field values.

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.

5.3.1.3.6.7. tpl_form

Oohforms process individual fields. If you have interdependencies among your fields, you will want to use tpl_form. In addition to bringing together the Oohforms and Table functions, it adds the ability to create a form-wide process checking function (javascript) executed at the submit, and a PHP form-wide checking function for those browsers with javascript turned off and for additional checking.

5.3.1.3.6.8. Tree

I have not used this class.

5.3.1.3.6.9. Strings2

(see tree....)