THE WEBBOX ARCHITECTURE (a PHP implementation of ColdFusion's "Fusebox" architecture).
picture of Bill Holloway
Almost any interactive website breaks down into logical divisions. For example, there is sometimes a "People" section of the site where you can create an "account" for yourself, log in to your account, edit your account, etc; on e-commerce sites there's always an "Order" section where you create order, check an order's status, cancel an order, update an order, etc. In the webbox architecture each of these functional areas is made into a PHP object with a thin wrapper around it to allow each of the object's functions to be called and receive arguments via URL, form action or via PHP script. The object plus its thin wrapper layer and other supporting files, I call a "webbox". The functions that can be called on the webbox, I call "boxactions". I use the term "webbox" for the wrapped object because this entity isn't really a pure PHP object anymore (it can't be subclassed) and because of the one feature that distinguishes its "boxactions" from regular PHP class functions -- that they can be called directly from URLs or form actions. The implementation of this feature is the whole purpose of the webbox architecture. Without it, "webboxes" are nothing more than regular PHP objects, and I should not use any new terminology.
The boxactions of each webbox should be able to do anything PHP can do -- write HTML out to the browser, perform queries on relational databases, send e-mails, look in LDAP directories, launch programs on the host system, create GIF images, encrypt data, create PDF files, parse XML documents, open network sockets, etc.
Each webbox is composed of several files and is stored in a single directory with an index.php3 file. To call a boxaction, the desired webbox's index.php3 URL is called and also passed the name of the boxaction to call along with any arguments to it. A typical URL style call would look like:
<a href="/people/index.php3?boxaction=viewcustomer&custid=12345">View Customer</a>
A typical form-based call to the same boxaction can be written:
<form action="/people/index.php3" method=post>
<index type=hidden name="boxaction" value="viewcustomer">
Enter the customer's ID number:  <input type=text name="custid">
<input type=submit value="View Customer Record">
</form>
A given webbox's boxactions are implemented in a single class called a "gateway". The index.php3 script instantiates the "gateway" class for its box. A long switch statement on the $boxaction parameter chooses the boxaction to call. Continuing our "add a customer" example, the relevant snippet of code from the index.php3 file might look like this:

<?php

$homedir 
"/www/htdocs/people/";

include 
$homedir "gateway.php3";
$g = new Gateway_People($homedir);

switch (
$boxaction) {

    case 
"viewcustomer":
        
$g->viewCustomer($custid);
        break;

    case 
"checkauthentication":
        
$g->checkAuthentication($username$password);
        break;

    
//
    // Other boxactions
    //

    
default:
        
$g->showDefaultPage();
        break;
}

?>
As is clear from this example, the gateway class is stored in a file named gateway.php3, and the class is named "Gateway_<name>", where <name> is the "name" you've given to the box (in our example the name is "People"). The gateway class is stored in a .php3 file to avoid exposing secrets like passwords or other sensitive information you don't want the public to see. It should only contain the class definition, no active script or HTML. Having the gateway class is necessary for calls to a webbox from script outside its directory [For you fusebox aficionados out there, the gateway is necessary because there is no <CFMODULE> tag in PHP which allows you to pass arbitrary arguments.]
The boxactions implement their functionality by calling other objects, INCLUDing .php3 file, etc. The gateway class instantiation passes the box's directory to the constructor because INCLUDE statements in the gatway class need the full path to the .php3 file. This is necessary for boxaction calls that originate in directories outside the box's directory.
Some gateway functions are fully private to the gateway class, being called only internally. These should be prefixed with an underscore or some other identifying prefix or suffix to denote that they are "private" functions. Boxactions or private functions which produce no output should be prefixed with some abbreviation of the action the function does, like "qry_".
Obviously, the gateway class is the repository for all the implementation of the boxactions. Thus the gateway class can have MANY lines. To reduce the size of the gateway class file, remember to delegate tasks to other classes, static HTML files, and .php3 files.

CALLING BOXACTIONS FROM PHP SCRIPT

To call a boxaction from PHP script, simply instatiate the appropriate gateway class and call the function on it. Here's an example calling our "View Customer" boxaction from PHP script:

<?php

include $web_root_directory "people/gateway.php3";
$people_g = new Gateway_People($web_root_directory "people/");
$people_g->viewCustomer($custid);

?>
The real beauty of this is the reusability of the code. Because we are wrapping basic functions in classes, they can be included for use throughout a site.
It's also a win for any future programmers that have to look at the code. A quick glance at the index file will show you the case statement and the corresponding classes. That's quite a bit cleaner than searching through dozens of separate php files and includes to get an idea of what's happening.
I hope this helps you get started. For more information, you can visit www.fusebox.org..
--Bill