Next Previous Contents

4. Extended functionality

The section on extended functionality covers non-GUI classes that provide often needed application functions without a user interface. Some extended classes depend on core functionality, some contain independent classes.

Extended classes are treated differently from core classes in that their code is not automatically included by prepend.php3. You have to include the class definition manually where needed or you modify prepend.php3.

4.1 Cart

The Cart class is programmatically independent, but makes sense only if its instances are made persistent in some way. The Cart class automatically registers itself as a session variable in its start() function.

Cart implements a shopping cart. At the moment, items within the shopping cart are independent of each other; the cart can only hold simple things. Support for compound articles that require other articles to function and provide a base for dependent articles is to be added at a future time.

An example of a simple article is any article with no options, for example an apple or a book. Common examples for compound articles are a pizza (which requires a foundation in either American or Italian style, a selection of toppings, and cheese, to function correctly) and a computer system (which requires a housing, a motherboard, RAM, a video card, etc to function correctly).

Note: Cart was a core class up to release-5. If your applications uses the Cart class, you must manually add the statement include("") to your prepend.php3 file where indicated in that file.

Note: The page management functions do no longer support the feature cart to set up and start the cart class. It is recommended that you use Session's auto_init feature instead to start your cart automatically or that you manually set up your cart.

Instance variables

Serialization helper: The name of this class.
persistent_slotsSerialization helper: The names of all persistent slots.
itemMultidimensional array of items in the cart.
currentItemA counter for item positions.
Accessible instance variables.

Instance methods

Accessible instance methods


Checks that an item with the given article number $art is in the cart. Returns an array of a boolean value and an integer number. If the boolean is true, there are number many articles of that article number in the cart.


Deletes all items in current cart, resetting $this->currentItem to 1. Always returns true.


Returns the number of articles in the current shopping cart, or false if cart is empty. For compatibility reasons, this function is available as tot_arts as well (but will print a warning if used by this name).

add_item($art, $num)

Add $num many articles of article number $art to the current shopping cart. Returns the position number of $art in the shopping cart.


Remove $num many articles of article number $art from the shopping cart, if there are at least that many articles in the cart. Returns the position number of $art in the shopping cart or false, if there weren't enough $art to remove them from the cart. If the function does return false, the cart has not been modified.


Set the quantity of article number $art in the shopping cart to exactly $num. If $num is set to zero, article is removed from cart. Returns the position number of $art in the shopping cart.


If the shopping cart is empty, it will call show_empty_cart() once and then return.

Calls show_item_open() once at the beginning of a shopping cart listing. Then calls show_item() once for each item in the shopping cart. Calls show_item_close() once at the end of a shopping cart listing.

show_item($art, $num)

This function should be provided by the user. It renders the HTML to display a single item from the cart. $art is the article number of the item and there are $num of these in the cart.


This function should be provided by the user. It renders the prologue HTML to display a shopping cart listing.


This function should be provided by the user. It renders the epilogue HTML to display a shopping cart listing.


This function should be provided by the user. It should render an appropriate message to symolize an empty cart.


Use a subclass of Cart to provide an implementation of show_item().

class My_Cart extends Cart {
  var $classname = "My_Cart";

  // Look up article numbers...
  var $database_class = "DB_Article";
  var $database_table = "articles";
  var $db;
  var $sum = 0;

  function show_cart_open() {
    printf("<table class=cart_table>\n");
    $this->sum = 0;
  function show_cart_close() {
    printf("That's a total of %s.\n", $this->sum);

  function show_item($art, $num) {
    if (!is_object($this->db)) {
      $class    = $this->database_class;
      $this->db = new $class;
    $query = sprintf("select * from %s where artid = '%s'",

    while($this->db->next_record()) {
      printf(" <tr class=cart_row>\n  <td class=cart_cell>%s</td>\n",
      printf("  <td class=cart_cell>%s</td>\n", 
      printf("  <td class=cart_cell>%s</td>\n",
      $rowsum = $num * $this->db->Record["price"];
      $this->sum += $rowsum;
      printf("  <td class=cart_cell>%s</td>\n",
      printf(" </tr>\n");

To use a cart, create an instance of your Cart subclass and call start(). This will automatically register cart.

It is recommended that you set in your Session subclass in the slot $auto_init to the value and create an include file of that name which contains the following code:

  global $cart;               ## $cart is a global variable.
  $cart = new My_Cart; ## Make a My_Cart instance named $cart
  $cart->start();          ## and have it register itself.

Use add_item() and remove_item to work with your Cart:

  $cart->add_item("101", 2);    ## Add two pieces of "101"
  $cart->remove_item("101", 1); ## Drop one piece of "101"

Use show_all() to display the contents of your cart.

  $cart->show_all();    ## What's in a cart, anyway?

On using Cart

To make use of the Cart class, you need to define a new table in your database that lists all articles you shop should sell. With PHPLIB and MySQL we recommend that you create a new instance of PHPLIB for each virtual web server and a new database for each customer. This database should hold the active_sessions and auth_user tables as well as all application specific tables like for example the article list. In other words, with MySQL we strongly discourage that you use PHPLIB and the MySQL directive use database_name together. There is no support if you do (there is no support if you do as we say, too, because PHPLIB is an open source product you are using on your own risk, but ...).

So let us assume you define a very simple new table articles with a structure like this:

# Table structure for table 'articles'
CREATE TABLE articles (
  name text,
  price float(8,2),
  artid int(11) DEFAULT '0' NOT NULL auto_increment,
  PRIMARY KEY (artid)

This table has an article number called artid, and for each artid there is an article description name and a price. You may extend this minimal definition for your purposes by adding article groups, BLOBs with article images and more, but this will suffice for our example purposes.

Populate this table with some products that suit your taste.

The next step is to teach PHPLIB about the cart class. Three steps are necessary to do so:

Now you have a $cart object available by default on every page that uses PHPLIB. That object is created automatically at session startup, is carried from page to page by PHPLIBs session management and is destroyed by the garbage collection that reaps session records. You do not have to worry anymore about that cart, but simply use it anytime between page_open() and page_close(). PHPLIB does the rest for you.

The Cart class is actually dead stupid. It maintains an array $cart->item[] that holds records about what the user bought. Each $cart->item[$x] consists of a $cart->item[$x]["art"], which is the article number of an item the user wants to buy and of a $cart->item[$x]["num"], which is the # of items with that article number that are wanted. $cart->currentItem is the next $x to use for articles added to $cart->item[].

You add articles to the shopping cart with

$x = $cart->add_item($art, $num)

This will add $num items with the article number $art to your cart contents. If you already have an item with that article number in your cart, the count for that article is increased by $num. Otherwise a new article entry is being created and set to $num. The function does return the $x index into the $cart->item[] array for that article.

To remove an item from the shopping cart, code

$x = $cart->remove_item($art, $num)

This will remove $num items with the article number $art from your cart, if there are that many items in your shopping cart. If you do not have the $art in your cart or there are not $num many $art in your cart, the function will return false and not remove anything from the cart. Otherwise, $num articles with article number $art are taken out of the cart and if the count for that article drops to zero while doing this, we even unset the array element.

You may check how many articles with a given article number are in the cart:

list($have, $num) = $cart->check($art)

The check function does return a two-element array. The first element $have is true, if we have the wanted article in the cart. If $have is true, $num holds the number of articles with that number in the cart, otherwise $num is undefined (actually, it is 0, but you must not rely on that).

Finally, we have a function


which you may call to walk your shopping cart and have Example_Cart to generate a list of articles in your cart. That function will first call $cart->show_cart_open(), for which you may provide code in your subclass. It will then call $cart->show_item($art, $num) for each item in the cart. We have a stupid default implementation for that function in Cart, but you may provide more sophisticated code in Example_Cart for that, too. Finally, at the end of your cart listing, $cart->show_cart_close() is being called, which again may be code of yours.

The example in the previous section shows a more sophisticated implementation of a Cart subclass. That implementation uses show_cart_open() to create an opening table tag (formatted with a CSS class) and sets a counter $cart->sum to zero.

In show_cart_close(), the table is being closed and the $cart->sum counter is printed.

As you might have guessed, show_item($art, $num) queries the database for each article number, retrieves the article description and prices and finally sums up all prices, taking the number of articles per article into consideration. It also generates table rows, printing a nice receipt for the customer.

4.2 Template

Note: If you think that this is like FastTemplates, read carefully. It isn't.

The template class allows you to keep your HTML code in some external files which are completely free of PHP code, but contain replacement fields. The class provides you with functions which can fill in the replacement fields with arbitrary strings. These strings can become very large, e.g. entire tables.

Instance variables

String. Serialization helper: The name of this class.
debugBoolean: if set to true, the class will emitdebugging output.
unknownsOne of "keep", "comment", "remove" (Default).Determines how to handle unresolved variable names intemplates upon output. If set to "keep", those are leftuntouched. If set to "comment", unresolved variable names aretransformed into HTML comments reporting the error. If set to"remove", unresolved variable names are silently removed (thedefault).
halt_on_error = "yes"One of "yes"(Default), "report", "no". Determines how Template handleserror conditions. If set to "yes" (the Default), the error isreported, then execution is halted. If set to "report", theerror is reported, then execution continues by returning"false". If set to "no", errors are silently ignored, andexecution resumes reporting "false".
last_error = ""The last error message iskept in this variable.
Accessible instance variables.

Hash of strings. A translation table whichtranslates variable names into filenames.
rootString (Pathname). The base directory from whichtemplate files are being loaded.
varkeysHash of strings. A translation table whichtranslates variable names into regular expressions forthemselves.
varvalsHash of strings. A translation table whichtranslates variable names into replacement values for theirrespective varkeys.
Internal instance variables.

Instance methods

Accessible instance methods

Template($root = ".", $unknowns = "remove")

Constructor. May be called with two optional parameters. The first parameter sets the template directory (see set_root(), the second parameter sets the policy regarding handling of unknown variables.


The function checks that $root is a valid directory and sets this directory as the base directory where templates are being stored.

set_unknowns($unknowns = "keep")

The function sets the policy for dealing with unresolved variable names. Must be either "remove", "comment" or "keep". If set to "keep", those are left untouched. If set to "comment", unresolved variable names are transformed into HTML comments reporting the error. If set to "remove", unresolved variable names are silently removed (the default).

set_file($handle, $filename = "")

The function defines a filename for the initial value of a variable. It may be called with either a $handle/$filename pair or with a hash of $handle/$filename pairs. The files are not referenced yet, but only when needed.

set_block($parent, $handle, $name = "")

A variable $parent may contain a variable block named by $handle. The function removes that block from $parent and replaces it with a variable reference named $name. If $name is omitted, it is assumed to be the same as $handle.

set_var($varname, $value = "")

The functions sets the inital value of a variable. It may be called with either a $varname/$value pair or with a hash of $varname/$value pairs.


The function returns the value of the variable named $handle, with all defined variable values filled in. The resulting string is not "finished", that is, the unresolved variable name policy has not been applied yet.


This is a shorthand for print $this->subst($handle).

parse($target, $handle, $append = false)

The function substitutes the values of all defined variables in the variable named $handle and stores or appends the result in the variable named $target.

If $handle is an array of variable names, $append is ignored. The variables named by $handle are being sequentially substituted and the result of each substitution step is stored in $target. The resulting substitution is available in the variable named by $target, as is each intermediate step for the next $handle in sequence.

pparse($target, $handle, $append = false)

A shorthand for print $this->parse(...).


Returns a hash of all defined values, keyed by their names.


Returns the value of the variable named by $varname. If $varname references a file and that file has not been loaded, yet, the variable will be reported as empty.

When called with an array of variable names, an hash of values, keyed by their names, will be returned.


The function will return a hash of unresolved variable names in $handle, keyed by their names (that is, the hash has the form $a[$name] = $name).


The function will returned the finished version of $str, that is, the policy regarding unresolved variable names will be applied to $str.


The function will print the finished version of the value of the variable named by $varname.


The function will return the finished version of the value of the variable named by $varname.


This function can be overridden by your subclass of Template. It will be called with an error message to print.

Internal instance methods


When called with a relative pathname, this function will return the pathname with $this->root prepended. Absolute pathnames are taken unchanged.

The resulting filename must exist, or an error is generated.


The function will construct a variable name regexp for a given variable name.


If a variable is undefined or empty and is backed by a filename, the backing file will be loaded and the files contents will be assigned as the variables value.


This function is called whenever an error occurs and will handle the error according to the policy defined in $this->halt_on_error.


The class manages a set of variables which are text strings. These strings may contain references to other variables in the form of "{variable}". When parsed or substituted, a variable reference is being replaced by the value of that variable.

A variable value may be defined manually by calling set_var("name", "value"); or it may be defined from a file by calling set_file("name", "filename.ihtml");. In the latter case, the contents of the file are being loaded when needed (as late as possible) and set as the value of that variable.

A third way to define a variable value is to call set_block("parent", "block", "name");. In this case, the variable named parent is being searched for a block that starts with <!-- BEGIN block --> and ends with <!-- END block -->. This string is removed from the variable parent and assigned to the variable named block. In parent, a variable reference to name is placed instead. If the optional parameter "name" is left out, "block" is being used instead.

Use Template direcly or define a subclass of Template as needed.

Define a template file named page.ihtml as follows:

 <body bgcolor="#ffffff">
 <table border=1 cellpadding=4 cellspacing=0 bgcolor="#eeeeee">
   <td colspan=2><h1>{PAGETITLE}</h1></td>

This file contains a reference to the variable pagetitle and a reference to the variable named out. Another template file, named box.ihtml, contains a block named row with three variable references {TITLE}, {NUM} and {BIGNUM}:

<!-- start box.ihtml -->
<table border=1 bgcolor="#cccccc" cellpadding=4 cellspacing=0>
  <td colspan=2><b>{TITLE}</b></td>
  <!-- BEGIN row -->
  <!-- END row -->
<!-- end box.ihtml -->

The following php3 file demonstrates how to use these templates:


  # create Template instance called $t  
  $t = new Template("/page/to/webserver/template", "keep");

  # define variables named page and box, referencing files
     "page" => "page.ihtml",
     "box"  => "box.ihtml"));

  # extract the block named "row" from "box", creating a
  # reference to {rows} in "box".
  $t->set_block("box", "row", "rows");

  # define the variables TITLE and PAGETITLE
  $t->set_var(array("TITLE"     => "Testpage",
                    "PAGETITLE" => "hugo"));

  # define NUM and BIGNUM, then append "row" to "rows"...
  for ($i=1; $i<=3; $i++) {
    $n  = $i;
    $nn = $i*10;
    $t->set_var(array("NUM" => $n, "BIGNUM" => $nn));
    $t->parse("rows", "row", true);

  # build out from box, then build out from page...
  $t->parse("out", array("box", "page"));

  # finish out and print it.
  # report leftover variables, if any.
  print implode(", ", $t->get_undefined("rows"));

Next Previous Contents