An excellent quick introduction of MVC aka "Model 2" concepts can be found here.

This is a short explanation of how Ambivalence (and your PHP web application) processes requests.

Ambivalence processes commands that are mapped to a dispatcher through extension mapping. For example, all URIs which end with *.m are mapped to Ambivalence. The URI minus the extension is the command. For example, if a request comes in for http://your.site.com/runQuery.m, the command is "runQuery". However, if the request comes in for http://your.site.com/foo/runQuery.m, the command is "foo/runQuery".

What Ambivalence does with a command is determined by the Ambivalence configuration file (ambivalence.xml). Here is a complete (albeit simple) example:

<ambivalence version="1.0">
<command name="results">
        <controller file="controller/Results.class" />
        <view name="success" layout="layout/lookAndFeel.inc">
                <param name="content" value="content/results.inc"/>
                <param name="title" value="Triathlon Results- Results"/>
        </view>
        <view name="error" layout="layout/lookAndFeel.inc">
                <param name="content" value="content/errors/resultsError.inc"/>
                <param name="title" value="Triathlon Results- Results"/>
        </view>
</command>
</ambivalence>

This file defines a single command, results, which has two possible outcomes (views): "success" and "error".

When the results command is requested, the following steps occur:

<?php
// placeholder for balances.m: This page fetches account balances for a user
?>

Ambivalence contains an authentication and authorization service (called PAAS) that enforces access control to resources based on principals and roles. PAAS is loosely based on a Java specification of this service in the J2EE space known as JAAS, and on a concrete implementation of this specification known as JBossSX (part of the JBoss J2EE application server suite).

The purpose of PAAS is to separate the security constraints surrounding resources from the actual resources themselves. Doing this yields several benefits. First, the application doesn't need to know how to secure itself-- this is done for it by PAAS. So changes to the secutity restrictions to a resource do not require any changes to the actual application code. Second, separating out the security piece makes it easy to have different constraints depending on where the application is deployed. For instance, my application deployed in an intranet setting might allow people with the User role to see a directory listing, but in an extranet setting, I might require a Manager role. With PAAS, this is easily done by making a simple change to the XML configuration file.

Currently, PAAS allows for FORM-based login using some principal (e.g. username) and credential (e.g., password).

Controllers are responsible for processing commands and building up the data model for the view to use when rendering results to the client. Ambivalence has a base controller class that populates the derived controller class with any HTTP GET/POST variables before calling the controller's perform() method. Your BaseController subclasses should have setter methods for any parameters you are expecting to get via HTTP GET/POST. For example, if you have an HTML form that contains a text input called "salary" then your controller must have a method called setSalary() that takes the variable as an input and sets a member variable for use later in the perform() method.

Note how the perform() method first calls the perform() method of its parent.

Below is an example of a controller class for a home page that inherits from the ControllerBase class. Note that the ControllerBase.class file doesn't need to be included here because it is already required by Ambivalence.

<?
require_once("model/AdvertDAO.class");
require_once("model/LoggedRequestDAO.class");

class Home extends ControllerBase
{
    var $rsv;
    var $prv;
    var $ad;
    var $salary;
    function getPopularRace() { return $this->rsv; }
    function getAdvert() { return $this->ad; }
    function getPopularResult() { return $this->prv; }
    function getSalary() { return $this->salary; }
    function setSalary($sal) { $this->salary = $sal; }
    function perform()
    {
        parent::perform();

        $advertDAO = new AdvertDAO;
        $loggedRequestDAO = new LoggedRequestDAO;

        $this->ad = $advertDAO->getAdvert("generic");
        $this->rsv = $loggedRequestDAO->getPopularRaceView();
        $this->prv = $loggedRequestDAO->getPopularResultView();
        return "success";
    }
}
?>

PAAS makes use of an object oriented data access layer built on top of the PEAR::DB library. The code is based on the Data Access Object design pattern, as outlined in this J2EE Blueprint. By using DAO's in your application and inheriting from the BaseDAO class, you get several benefits:

1. All the functionality of the PEAR:DB class.
2. Easy separation of datasource names from code, allowing for datasource specification and binding to happen at deployment time, rather than as a static part of the software development process.
3. Application-level error handling mechanism for fatal errors that logs the error and displays your customized error page before halting execution.

Here is an example DAO that a controller might use to log requests to a database:

<?php
require_once("BaseDAO.class");

class LoggedRequestDAO extends BaseDAO
{
    function logRaceRequest($raceId, $remoteAddr)
    {
        $insertStatement =
            "insert into request_log (race_id, ip_address) " .
            "values (".$raceId.",'".$remoteAddr."')";

        $result = $this->db->query($insertStatement);
        if (DB::isError($result)) {
            $this->halt($result->getMessage(),$insertStatement);
        }
    }
}
?>

To enable Ambivalence's data access layer, you need to specify a default datasource to use. If you don't specify the name of your datasource name (DSN) file in the DAO constructor, Ambvivalence will search for the DefaultDSN.inc file in your include path. Here is an example of a DSN file:

<?php
$user = 'mysql';
$pass = 'mysql';
$host = 'localhost';
$db_name = 'dev_db';
?>

Note that you can specify multiple DSN's in your application. In fact, each DAO you create can connect to a different database--- all you have to do is specify which datasource file to use. In addition, you can have the same DSN file defined differently in different environments. For example, the DefaultDSN.inc file may point to a development database, a staging database, or a production database depending on where the code is being deployed.

Layouts allow an easy way for a common look and feel to be applied to many different views. The difference in Ambivalence is that the view doesn't know what layout it is in--- it doesn't reference it anywhere. The look and feel, or layout, for a view is set up in the ambivalence.xml file.

Layouts contain all the content that doesn't change depending on which view gets rendered for a command. Views contain the rest. Here is an example layout file where the title and content are set dynamically (in the ambivalence.xml file) but the rest of the page is static.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title><?=$title?></title>
</head>
<body bgcolor="#eeeeee">
	<? require($content) ?>
</body>
</html>

The paas.xml file is currently used by the authentication and authorization system to specify application-wide login modules along with any security constraints imposed on the application. If your application is not using this (i.e., your auto-prepend file does not include paas.inc), then you do not need this file. Otherwise, Ambivalence will look for this file in your PHP include path.

See the appendix for an explanation of the options available in the paas.xml file.

For small applications, it's easy to stick model, view, and controller code all in one place, but when small applications grow large, it pays to have some structure in place already. Here is a sample directory tree for an Ambivalence application.

|
+->htdocs (The web server document root containing the placeholder *.m files, along with any images, plain HTML files, or even PHP files that aren't processed by Ambivalence)
|
+->php-include (contains all XML config files and DefaultDSN.inc, and prepend file if not set up elsewhere)
|
+->model (The Data Access Objects and data structure files)
|
+->controller (Command processing classes here)
|
+->layout ("Look-and-feel" wrappers)
|
+->content (Specific views to be wrapped by layouts)
    |
    +->errors (Error-related views)