I agree with a ton of it — heck, I've contributed to it a fair bit via conversations with Paul. But there's been one thing nagging at me for a bit now, and I was finally able to put it into words recently.

Controllers — Actions in ADR — can be explained as facades.

Definitions

The design pattern Facade originates in the book "Design Patterns: Elements of Reusable Object Oriented Software," written by Erich Gamma, Ralph Johnson, Richard Helm, and John Vlissides. Over the years, that book has come to be referred to as the "Gang of Four", referring to the four authors, and often abbreviated as "GoF".

The Facade pattern itself is one of the seven structural design patterns defined in the GoF. Structural design patterns are those that provide a mechanism for defining the relationships between classes or objects in a system. Specifically:

Facade defines a simplifed interface to a complex system.

Wikipedia has a general entry on the pattern as well, and provides some other general characteristics of a Facade:

• A Facade creates a convenience method around a set of operations, thus reducing the complexity of operations.
• A Facade reduces the immediate dependencies of the calling code (they call the Facade, not the underlying code).

Facade Example

As an example, let's consider the following workflow:

• Marshal some objects
• Munge some incoming data
• Call a validator
• If the data does not validate, raise an error
• Start a transaction
• Pass data to several different tables
• Commit the transaction
• Log the changes
• Email notifications

Now, we could just write the code:

$db     = new Db($connectionConfig);
$log    = new Logger($loggerConfig);
$mailer = new Mailer($mailerConfig);
$data   = array_merge_recursive($_POST, $_FILES);

$inputFilter = new InputFilter();
$inputFilter->setData($data);
if (! $inputFilter->isValid()) {
    throw new DomainException();
}

$db->transactionStart();
$db->insertInto(/* ... */);
$db->insertInto(/* ... */);
$db->insertInto(/* ... */);
$db->transactionStop();

$log->info('Finished a transaction');
$mailer->send('New transaction')

Straight-forward. But imagine if you needed to do this more than once. Or if you wanted to re-use this logic in multiple places in your application. This is a situation just waiting to go out-of-sync — and one where developers will come to rely on cut-and-paste for doing it correctly.

A facade would wrap this logic:

class DataTransaction
{
    protected $db;
    protected $logger;
    protected $mailer;

    public function __construct(Db $db, Logger $logger, Mailer $mailer)
    {
        $this->db     = $db;
        $this->logger = $logger;
        $this->mailer = $mailer;
    }

    public function execute($data)
    {
        $inputFilter = new InputFilter();
        $inputFilter->setData($data);
        if (! $inputFilter->isValid()) {
            throw new DomainException();
        }

        $this->db->transactionStart();
        $this->db->insertInto(/* ... */);
        $this->db->insertInto(/* ... */);
        $this->db->insertInto(/* ... */);
        $this->db->transactionStop();

        $this->logger->info('Finished a transaction');
        $this->mailer->send('New transaction')
    }
}

You would then instantiate the facade — likely using an Inversion of Control container to inject the dependencies — and then invoke it:

$dataTransaction->execute(array_merge_recursive($_POST, $_FILES));

This code fulfills the Facade pattern: we're no longer directly manipulating dependencies, and we've simplified a complex set of operations to a single, unified API.

Controllers and Actions

Hopefully you can see where I'm going with this.

Controllers in MVC, and Actions in ADR, are best characterized as Facades.

You can define Controllers or Actions as Facades for the following operations:

• Marshaling arguments from the request.
• Invoking any domain/model logic, using arguments marshaled from the request.
• Marshaling and returning a response/responder.

I think characterizing Controllers and Actions as Facades has some huge benefits. In both PHP and Rails, we've witnessed the problems that arise from so-called "Fat Controllers" — controllers that do a ton of work, making them untestable, unreadable, non-reusable nightmares. If we think of them as Facades, specifically for the three items noted above, we focus on the specific purpose they fulfill within the system, giving us:

• Adherence to the Single Responsibility Principle
• Adherence to the Dependency Inversion Priniciple
• Adherence to the Law of Demeter
• Ability to unit test our Controllers and Actions (instead of requiring integration tests with complex configuration and setup)
• The possibility of hierarchical MVC (usually tacked on, or poorly implemented)
• Clarity of purpose when creating Controllers and Actions (do only those three things)

Defining them as Facades for these three specific operations means we push logic into specific domains, achieving a proper separation of concerns. Anything that falls outside those three operations gets pushed elsewhere:

• Models/Domains are invoked with the arguments marshaled from the request. If you find yourself calling many models, or manipulating the results returned by models, you need to create Facades in your model/domain layer.
• If you find yourself doing lots of work in creating your response, you need to create a Facade for marshaling the response (in ADR, that would mean encapsulating more logic in your Responder).

For me, thinking of Controllers and Actions as Facades has an additional benefit: it describes rather complex architectural patterns in terms of basic design patterns. I find the more I can reduce the complexity of a definition, the more likely I will understand and use it correctly.

Epilogue

Consider this post a refinement of the MVC and ADR architectural patterns — a way of describing them in terms of more fundamental design patterns.

Also, this article is littered with links. Click them. Read them. Digest them. Read the books they reference. Design and architectural patterns exist because developers observed the patterns and gave them names; learn to recognize them and apply them, at all levels of your application.

Better Understanding Controllers Through Basic Patterns was originally published 9 June 2014 on https://mwop.net by Matthew Weier O'Phinney.

The Model is a complex subject. However, it is often boiled down to either a single model class or a full object relational mapping (ORM). I personally have never been much of a fan of ORMs as they tie models to the underlying database structure; I don't always use a database, nor do I want to rely on an ORM solution too heavily on the off-chance that I later need to refactor to use services or another type of persistence store. On the other hand, the model as a single class is typically too simplistic.

I am, however, a fan of the Domain Model. To quote wikipedia,

[The] domain model can be thought of as a conceptual model of a system which describes the various entities involved in that system and their relationships.

When you think in these terms, you start breaking your system into discrete pieces that you need to manipulate, as well as consider how each piece relates to the others. This type of exercise also helps you stop thinking of your model in terms of database tables; instead, your database becomes the container in which data is persisted from one use of your model to the next. Your model instead is an object that can do things with either incoming or stored data — or even completely autonomously.

As an example, when starting with Zend Framework, it's tempting to use Zend_Db_Table and Zend_Db_Table_Row as models. However, there's one big argument against doing so: when using a Table Data Gateway (TDG) or a Row Data Gateway (RDG), you're returning an object that is tied to the data storage implementation. You're basically putting on blinders and thinking of your model as simply the database table or an individual row, and the returned objects reflect this narrow view point. Furthermore, if you want to re-use your models with service layers, many web services do not work with objects, and of those that do, you likely do not want to expose all the properties and methods of the objects returned by your data provider. A row object in ZF, for instance, actually stores the data in protected members, effectively hiding it from services, and also includes methods for deleting the row, ArrayAccess methods, and access to the table object — which gives you full control over the table! The security implications of exposing this directly over a service should be obvious.

Additionally, if in the future you wish to refactor your application to utilize memcached or a web service, you now not only need to completely rewrite your models, but also all consumer code, because the return values from your model have changed.

So, if you're not going to use an ORM or a Table Data Gateway directly, how should you architect your model infrastructure?

What are you modelling?

The principal question to ask is, "What am I modelling?"

Let's look at a rather standard website issue: user management. Typically, you'll get a requirement such as, "Users should be able to register for an account on the site. Once registered, they should be able to login with the credentials they provided. Administrators should be able to ban accounts or grant users higher levels of privileges." That's assuming you actually get good requirement documents, of course.

Most developers will immediately setup a database with a few fields that represent a user — full name, username, email, password, etc — create a form for registration and another for login, write a routine to validate each, create a page to list users for the administration screen… you know the drill. But what are you modelling?

The answer is: users. So, now it's time to define what a user is, and what a user can do. We have to decide what constitutes a new user, and what constitutes an authenticated user. We have an additional modelling consideration that's often overlooked: user roles. There's also the matter of what a group of users might look like (since the administrator needs to be able to list users), and how we might want to work with groups.

Let's start with narrowing down the definition of a user:

• A user consists of the following metadata:
  • Unique username
  • Full name
  • Email address
  • Hashed password
  • A role within the site
• A new user must provide a unique username, their full name, a valid email address, and a password and password verification.
• An authenticated user is one who has provided a matching combination of username and password.
• A user may logout of the site.
• A user may be granted a new role.
• A user may be marked as banned.

Notice the fifth piece of metadata? It mentions a "role"? That's something to do with our ACLs — which means that ACLs are part of our user domain. I'll touch on this later.

If you look at the remaining points carefully, you'll note that there's talk of validation, authentication, and user and session persistence. Validation rules are part of our model — and we'll use Zend_Form to fulfill that role. Authentication on the web usually consists of both validating submitted credentials against stored credentials, as well as persisting a verified identity in the session. This means that other parts of our model include data persistence and session management. We'll use Zend_Db_Table for data persistence, and Zend_Auth/Zend_Session for identity persistence.

Now, let's turn to defining lists of users:

• Administrators should be able to pull lists of users. These lists should allow for:
  • Sorting by username, full name, email address, or role
  • Pagination (i.e., pulling a set number of users from a given offset)
  • Iteration
• Administrators should be able to specify criteria for selecting users to list.

These criteria indicate that a list of users should be an object. This list will likely implement the SPL class Traversable in some fashion. Looking at this criteria, another aspect of our model becomes clear: we are modelling user selection — which includes the ability to specify sorting and selection criteria. The user selection object would return a user list object, which would consist of user objects. User objects define ACL roles and can authenticate users.

We started this article by discussing the Domain Model, and defined it as a system, its entities, and the relations between those entities. We've now identified our domain: user management. The various entities include users, lists of users, ACL roles, a user persistence layer (database), and session persistence layer (web server sessions).

Now that we know what we're modelling, let's look at some of the objects in our model.

Gateway to the Domain

We've identified "user management" as the purpose of our model. This will include retrieving and saving individual users, as well as selecting groups of users.

It's clear that we'll need an object to represent a user, as well as another to represent a selection or group of users. But what may not be entirely clear is that we should likely have an object that is used to create new user objects, create selections of users, and basically coordinate several of the related objects — the root ACL and data access, in particular.

This object will be what I'll term our domain gateway. It will be used to fetch other objects in our model, and will inject various dependencies into them when doing so, such as the data access and ACLs. The various dependencies may themselves be injected into the gateway — or it can lazy-load them.

The API of this gateway might look something like the following.

// Instantiate the gateway
$userGateway = new Spindle_Model_UserGateway();

// configure the gateway:
$userGateway->setAcl(new Spindle_Acl_Spindle())
            ->setDbAdapter(Zend_Registry::get('db'));

// Alternately, do it all at instantiation:
$userGateway = new Spindle_Model_UserGateway(array(
    'acl'       => new Spindle_Acl_Spindle(),
    'dbAdapter' => Zend_Registry::get('db'),
));

// Grab a single user
$user = $userGateway->retrieve('matthew');

// Grab many users
$users = $userGateway->sort('email', 'ASC')
                     ->criteria(array('banned' => true))
                     ->fetch(array('offset' => 20, 'limit' => 20));

// Better yet, add some transaction script methods with preset criteria:
$users = $userGateway->fetchBannedUsers(array(
    'offset' => 20, 
    'limit'  => 20,
    'sort'   = array('email', 'ASC'),
));

// Create a new user:
$user = $userGateway->createUser(array(
    'username' => 'matthew',
    'fullname' => "Matthew Weier O'Phinney",
    'password' => 'secret',
    'email'    => 'matthew@local',
));

The basic idea is to provide a scaffold for lazyloading necessary objects, methods for specifying options (such as sort order, criteria, limits, etc), and transaction methods for retrieving individual users and groups of users.

Of Value Objects and Record Sets

To other objects we've identified in our model are users and user lists. How should we define these?

The traditional answer is as value or data transfer objects and record sets. The Value Object is a standard design pattern used to aggregate all metadata that defines a single value. The Record Set is an aggregation of Value Objects.

Value Objects

Martin Fowler makes a differentiation between value objects and data transfer objects in his book "Patterns of Enterprise Application Architecture" (PoEAA). In it, he associates value objects with language variable types (i.e., Value Objects act as custom variable types), while defining data transfer objects as aggregating related values for the purpose of serialization and data transfer between objects.

In Java, however, value objects are arbitrary objects used to store a specific set of attributes — very similar to the data transfer object. For the purposes of this discussion, I'll use the term "value object," as it will be familiar to those with a Java background, and to indicate that we are aggregating a unique value that is the sum of a number of attributes.

Basically, all of this verbiage describes something incredibly simple in implementation: an object with a specific set of attributes or properties. If you've been doing any OOP programming in PHP, this is the most natural and fundamental thing you can do.

class Spindle_Model_User
{
    protected $_data = array(
        'username' => null,
        'email'    => null,
        'fullname' => '',
        'role'     => 'guest',
    );

    public function __construct($data)
    {
        $this->populate($data);

        if (!isset($this->username)) {
            throw new Exception('Initial data must contain an id');
        }
    }

    public function populate($data)
    {
        if (is_object($data)) {
            $data = (array) $data;
        }
        if (!is_array($data)) {
            throw new Exception('Initial data must be an array or object');
        }

        foreach ($data as $key => $value) {
            $this->$key = $value;
        }
        return $this;
    }

    public function __set($name, $value)
    {
        if (!array_key_exists($name, $this->_data)) {
            throw new Exception('Invalid property "' . $name . '"');
        }
        $this->_data[$name] = $value;
    }

    public function __get($name)
    {
        if (array_key_exists($name, $this->_data)) {
            return $this->_data[$name];
        }
        return null;
    }

    public function __isset($name)
    {
        return isset($this->_data[$name]);
    }

    public function __unset($name)
    {
        if (isset($this->$name)) {
            $this->_data[$name] = null;
        }
    }
}

The above example is fairly simplistic, but it gets the idea across: the object defines a limited range of valid values, and enforces that only these values may be set — as well as which values are required. You could certainly add accessor and mutator methods to enforce consistent access to member data, but the above will certainly suffice for many use cases. (I'll look at data integrity momentarily.)

One addition you might make to the class definition is to add some conversions from different types of objects. For instance, if you know that you'll be using Zend_Db_Table within your model, you might want to add the ability for your value object to accept a Zend_Db_Table_Row object, and pull its values from there:

class Spindle_Model_User
{
    /* ... */

    public function populate($data)
    {
        if ($data instanceof Zend_Db_Table_Row_Abstract) {
            $data = $data->toArray();
        } elseif (is_object($data)) {
            $data = (array) $data;
        }

        if (!is_array($data)) {
            throw new Exception('Initial data must be an array or object');
        }

        foreach ($data as $key => $value) {
            $this->$key = $value;
        }
        return $this;
    }

    /* ... */
}

This will help keep your model code clean, as you can potentially take the results of data storage operations and push them directly into your value object — resulting in less re-working of code.

Now, what about data integrity? This is where Zend_Form comes into play. Don't think of Zend_Form as a web form; think of it as an input filter that has the ability to render itself as a form if so desired. If we think of it as an input filter, we can use it for data integrity:

class Spindle_Model_User
{
    /* ... */

    public function __set($name, $value)
    {
        if (!array_key_exists($name, $this->_data)) {
            throw new Exception('Invalid property "' . $name . '"');
        }

        $inputFilter = $this->getForm();
        if ($element = $inputFilter->getElement($name)) {
            if (!$element->isValid($value)) {
                throw new Exception(sprintf(
                    'Invalid value provided for "%s": %s', 
                    $name, 
                    implode(', ', $element->getMessages())
                );
            }
        }

        $this->_data[$name] = $value;
    }

    /* ... */

    protected $_form;

    public function getForm()
    {
        if (null === $this->_form) {
            $this->_form = new Spindle_Form_User();
        }
        return $this->_form;
    }

    /* ... */
}

One note: if your model contains metadata that will never be represented as part of a form, you shoould look into using Zend_Filter_Input or custom validation chains instead of Zend_Form. That's outside the scope of this article, however.

Now that we have input filtering out of the way, how shall we address saving a user? Recall in our discussion of the domain gateway that one of its responsibilities is injecting other dependencies into our objects. I find it's often easier to inject the gateway into objects, and then pull what I need from it. Let's look at how that might work for saving the user.

class Spindle_Model_User
{
    /* ... */

    protected $_gateway;

    public function __construct($data, $gateway)
    {
        $this->setGateway($gateway);

        /* ... */
    }

    public function setGateway(Spindle_Model_UserGateway $gateway)
    {
        $this->_gateway = $gateway;
        return $this;
    }

    public function getGateway()
    {
        return $this->_gateway;
    }

    public function save()
    {
        $gateway = $this->getGateway();
        $dbTable = $gateway->getDbTable('user');

        if ($row = $dbTable->find($this->username)) {
            foreach ($this->_data as $key => $value) {
                $row->$key = $value;
            }
            $row->save();
        } else {
            $dbTable->insert($this->_data);
        }
    }

    /* ... */
}

Note that the constructor now has a second argument — the gateway. This ensures that the user always has a gateway instance, which further ensures that operations like the one listed — retrieving the Zend_Db_Table instance from the gateway — will always work. In this example, we simply check to see if a row already exists, and then save the record accordingly.

Another requirement we identified was that a user be able to authenticate itself. This can be done trivially by implementing Zend_Auth_Adapter_Interface:

class Spindle_Model_User implements Zend_Auth_Adapter_Interface
{
    /* ... */

    public function authenticate()
    {
        $gateway = $this->getGateway();
        $table   = $manager->getDbTable('user');
        $select  = $table->select();
        $select->where('username = ?', $this->username)
               ->where('password = ?', $this->password)
               ->where('date_banned IS NULL');
        $user = $table->fetchRow($select);
        if (null === $user) {
            // failed
            $result = new Zend_Auth_Result(
                Zend_Auth_Result::FAILURE_UNCATEGORIZED,
                null
            );
        } else {
            // passed
            $this->populate($user);
            unset($this->password);
            $result = new Zend_Auth_Result(Zend_Auth_Result::SUCCESS, $this);
        }
        return $result;
    }

    /* ... */
}

To authenticate a user, you would create a new user object with the username and password, and then attempt to authenticate it:

$auth = Zend_Auth::getInstance();
$user = $gateway->createUser(array(
    'username' => $username,
    'password' => $password,
));
if ($auth->authenticate($user)) {
    // AUTHENTICATED!
}

This also has the effect of populating the user from the persistence store, as well as storing the identity in the session.

I covered ACL roles previously, so I won't go into that here. However, you should now be getting a pretty clear understanding of how this object works, and how it coordinates with the user gateway. It should also illustrate that this aspect of our model is much, much more than simply data access: we're coordinating authentication, input filtering, and ACLs — and providing a fairly simple API for manipulating the user itself.

Record Sets

A Record Set is similarly easy to create. Typically, you will merely want the object to be iterable and countable. Like the user object, we'll require a gateway instance in the constructor.

class Spindle_Model_Users implements Iterator,Countable
{
    protected $_count;
    protected $_gateway;
    protected $_resultSet;

    public function __construct($results, $gateway)
    {
        $this->setGateway($gateway);
        $this->_resultSet = $results;
    }

    public function setGateway(Spindle_Model_UserGateway $gateway)
    {
        $this->_gateway = $gateway;
        return $this;
    }

    public function getGateway()
    {
        return $this->_gateway;
    }

    public function count()
    {
        if (null === $this->_count) {
            $this->_count = count($this->_resultSet);
        }
        return $this->_count;
    }

    public function current()
    {
        if ($this->_resultSet instanceof Iterator) {
            $key = $this->_resultSet->key();
        } else {
            $key = key($this->_resultSet);
        }
        $result  = $this->_resultSet[$key];
        if (!$result instanceof Spindle_Model_User) {
            $gateway = $this->getGateway();
            $result  = $gateway->createUser($result);
            $this->_resultSet[$key] = $result;
        }
        return $result;
    }

    public function key()
    {
        return key($this-_resultSet);
    }

    public function next()
    {
        return next($this->_resultSet);
    }

    public function rewind()
    {
        return reset($this->_resultSet);
    }

    public function valid()
    {
        return (bool) $this->current();
    }
}

The logic here is incredibly simple. The main benefit from using a Record Set over an array is that it allows you to ensure the types of each item in the set, as well as allow your consuming code to perform type hinting on the Record Set class.

Using Value Objects and Record Sets in Your Gateway

Within your gateway class, it is then your responsibility to ensure that instances of your new classes are returned. As an example, let's look at some easy fetch() and fetchAll() methods:

class Spindle_Model_UserGateway
{
    /* ... */

    public function fetch($id)
    {
        $dbTable = $this->getDbTable();
        $select  = $dbTable->select();
        $select->where('id = ?', $id);
        $result = $dbTable->fetchRow($select);
        if (null !== $result) {
            $result = $this->createUser($result);
        }
        return $result;
    }

    public function fetchAll()
    {
        $result = $this->getDbTable()->fetchAll();
        return new Spindle_Model_Users($result, $this);
    }

    /* ... */
}

You'll notice the downside immediately: you have to introduce new objects, and that means re-casting of data. But let's look at it from a consumer viewpoint: the consuming code is looking for return types of Spindle_Model_User and Spindle_Model_Users.

But what's the point of the gateway, really? Couldn't both the value object and result set object simply inherit from a common base? Certainly they could. However, one common use case I have for gateways is providing pre-defined methods encapsulating common selection criteria. For instance, let's say you wanted to retrieve all banned users, and that this will be a common task. Define a method for it:

class Spindle_Model_UserGateway
{
    /* ... */

    public function fetchBannedUsers()
    {
        $dbTable = $this->getDbTable();
        $select  = $dbTable->select()->where('date_banned IS NOT NULL');
        $result  = $dbTable->fetchAll($select);
        return new Spindle_Model_Users($result, $this);
    }

    /* ... */
}

This is admittedly a trivial example, but it clearly illustrates the benefits: we now have an API method that tells us, in plain English, what operation we are performing, and provides a repeatable way to do it. The user consuming the model needs not know anything about how it works under the hood, only that they can expect to get a list of banned users when they call it.

Another key benefit to creating a gateway is for those times when we need to replace our data access layer with something else. Let's refactor our code to use a service instead:

class Spindle_Model_UserGateway
{
    /* ... */

    public function fetch($id)
    {
        $result  = $this->getService()->fetchUser($id);
        return $this->createUser($result);
    }

    public function fetchAll()
    {
        $result = $this->getService()->fetchAll();
        return new Spindle_Model_Users($result, $this);
    }

    /* ... */
}

From a consumer standpoint, nothing has changed; they are still calling the same methods, and receiving the same responses. This is absolutely key in creating maintainable, future proof code.

Summary

The solutions presented here are by no means canonical. You may find that your own models do not need a gateway class, or that you never work with lists of objects. Hopefully, however, I've illustrated that a model should cleanly provide a separation of concerns and consist of discrete objects — whether they are directly related to your model, or related to aspects of how your model does stuff, like validation and data persistence. You should strive to make your models as simple as possible, while still meeting each of your requirements. The end result should be a re-usable, testable suite of functionality, and careful architecture of your solution should make it robust and easy to refactor in the future.

Updates:

• 2009-01-04: Updated __unset() per Gabriel's feedback (comment #14)
• 2009-01-05: Updated current() implementation per Falk's feedback (comment #15)
• 2009-01-05: Updated current() implementation per Martin's feedback (comment #15.1.1)

Model Infrastructure was originally published 30 December 2008 on https://mwop.net by Matthew Weier O'Phinney.

PHPUnit offers a variety of methods for setting up test suites, some trivial and some complex. The Zend Framework test suite, for instance, goes for a more complex route, adding component-level suites that require a fair amount of initial setup, but which allow us fairly fine-grained control.

However, testing and test automation should be easy and the complex approach is overkill for most of our applications. Fortunately, PHPUnit offers some other methods that make doing so relatively simple. The easiest method is to use an XML configuration file.

As an example, consider the following:

<phpunit>
    <testsuite name="My Test Suite">
        <directory>./</directory>
    </testsuite>

    <filter>
        <whitelist>
            <directory suffix=".php">../library/</directory>
            <directory suffix=".php">../application/</directory>
            <exclude>
                <directory suffix=".phtml">../application/</directory>
            </exclude>
        </whitelist>
    </filter>

    <logging>
        <log type="coverage-html" target="./log/report" charset="UTF-8"
            yui="true" highlight="true"
            lowUpperBound="50" highLowerBound="80"/>
        <log type="testdox-html" target="./log/testdox.html" />
    </logging>
</phpunit>

First thing to note, relative paths are relative to the configuration file. This allows you to run your tests from anywhere in your tests tree. Second, providing a directory directive to the testsuite directive scans for all files ending in Test.php in that directory, meaning you don't have to keep a list of your test cases manually. It's a great way to automate the suite. Third, the filter directive allows us to determine what classes to include and/or exclude from coverage reports. Finally, the logging directive lets us specify what kinds of logs to create and where.

Drop the above into tests/phpunit.xml in your application, and you can start writing test cases and running the suite immediately, using the following command:

$ phpunit --configuration phpunit.xml

I like to group my test cases by type. I have controllers, models, and often library code, and need to keep the tests organized both on the filesystem as well as for running the actual tests. There are two things I do to facilitate this.

First, I create directories. For instance, I have the following hierarchy in my test suite:

tests/
    phpunit.xml
    TestHelper.php
    controllers/
        IndexControllerTest.php (contains IndexControllerTest)
        ErrorControllerTest.php (contains ErrorControllerTest)
        ...
    models/
        PasteTest.php           (contains PasteTest)
        DbTable/
            PasteTest.php       (contains DbTable_PasteTest)
        ...
    My/
        Form/
            Element/
                SimpleTextareaTest.php

controllers/ contains my controllers, models/ contains my models. If I were developing a modular application, I'd have something like blog/controllers/ instead. Library code is given the same hierarchy as is found in my library/ directory.

Second, I use docblock annotations to group my tests. I add the following to my class-level docblock in my controller test cases:

/**
 * @group Controllers
 */

Models get the annotation @group Models, etc. This allows me to run individual sets of tests on demand:

$ phpunit --configuration phpunit.xml --group=Controllers

You can specify multiple @group annotations, which means you can separate tests into modules, issue report identifiers, etc; additionally, you can add the annotations to individual test methods themselves to have really fine-grained test running capabilities.

Astute readers will have noticed the TestHelper.php file in that directory listing earlier, and will be wondering what that's all about.

A test suite needs some environmental information, just like your application does. It may need a default database adapter, altered include_paths, autoloading set up, and more. Here's what my TestHelper.php looks like:

<?php
/*
 * Start output buffering
 */
ob_start();

/*
 * Set error reporting to the level to which code must comply.
 */
error_reporting( E_ALL | E_STRICT );

/*
 * Set default timezone
 */
date_default_timezone_set('GMT');

/*
 * Testing environment
 */
define('APPLICATION_ENV', 'testing');

/*
 * Determine the root, library, tests, and models directories
 */
$root        = realpath(dirname(__FILE__) . '/../');
$library     = $root . '/library';
$tests       = $root . '/tests';
$models      = $root . '/application/models';
$controllers = $root . '/application/controllers';

/*
 * Prepend the library/, tests/, and models/ directories to the
 * include_path. This allows the tests to run out of the box.
 */
$path = array(
    $models,
    $library,
    $tests,
    get_include_path()
);
set_include_path(implode(PATH_SEPARATOR, $path));

/**
 * Register autoloader
 */
require_once 'Zend/Loader.php';
Zend_Loader::registerAutoload();

/**
 * Store application root in registry
 */
Zend_Registry::set('testRoot', $root);
Zend_Registry::set('testBootstrap', $root . '/application/bootstrap.php');

/*
 * Unset global variables that are no longer needed.
 */
unset($root, $library, $models, $controllers, $tests, $path);

The above ensures that my APPLICATION_ENV constant is set appropriately, that error reporting is appropriate for tests (i.e., I want to see all errors), and that autoloading is enabled. Additionally, I place a couple items in my registry — the bootstrap and test root directory.

In each test case file, I then do a require_once on this file. In future versions of PHPUnit, you'll be able to specify a bootstrap file in your configuration XML that gets pulled in for each test case, and you'll be able to even further automate your testing environment setup.

Hopefully this will get you started with your application testing; what are you waiting for?

Setting up your Zend_Test test suites was originally published 11 September 2008 on https://mwop.net by Matthew Weier O'Phinney.

So, one of my ongoing projects the past few months has been to create an infrastructure for functional testing of ZF projects using PHPUnit. This past weekend, I made the final commits that make this functionality feature complete.

The new functionality provides several facets:

• Stub test case classes for the HTTP versions of our Request and Response objects, containing methods for setting up the request environment (including setting GET, POST, and COOKIE parameters, HTTP request headers, etc).
• Zend_Dom_Query, a class for using CSS selectors (and XPath) to query (X)HTML and XML documents.
• PHPUnit constraints that consume Zend_Dom_Query and the Response object to make their comparisons.
• A specialized PHPUnit test case that contains functionality for bootstrapping an MVC application, dispatching requests, and a variety of assertions that utilize the above constraints and objects.

What might you want to test?

• HTTP response codes
• Whether or not the action resulted in a redirect, and where it redirected to
• Whether or not certain DOM artifacts are present (particularly helpful for ensuring that the DOM structure is correct for JS actions)
• Presence of specific HTTP response headers and/or their content
• What module, controller, and/or action was used in the last iteration of the dispatch loop
• What route was selected

The aim is to make testing your controllers trivial and fun. Let's look at an example:

class UserControllerTest extends Zend_Test_PHPUnit_ControllerTestCase
{
    public function setUp()
    {
        $this->bootstrap = array($this, 'appBootstrap');
        parent::setUp();
    }

    public function appBootstrap()
    {
        $this->frontController->registerPlugin(
            new Bugapp_Plugin_Initialize('test')
        );
    }

    public function testCallingControllerWithoutActionShouldPullFromIndexAction()
    {
        $this->dispatch('/user');
        $this->assertResponseCode(200);
        $this->assertController('user');
        $this->assertAction('index');
    }

    public function testIndexActionShouldContainLoginForm()
    {
        $this->dispatch('/user');
        $this->assertResponseCode(200);
        $this->assertSelect('form#login');
    }

    public function testValidLoginShouldInitializeAuthSessionAndRedirectToProfilePage()
    {
        $this->request
             ->setMethod('POST')
             ->setPost(array(
                 'username' => 'foobar',
                 'password' => 'foobar'
             ));
        $this->dispatch('/user/login');
        $this->assertTrue(Zend_Auth::getInstance()->hasIdentity());
        $this->assertRedirectTo('/user/view');
    }
}

You'll note that the setUp() method assigns a callback to the $bootstrap property. This allows the test case to call that callback to bootstrap the application; alternately, you can specify the path to a file to include that would do your bootstrapping. In the example above, I actually simply add a single "initialization" plugin to the front controller that takes care of bootstrapping my application (via the routeStartup() hook).

I then have a few test cases. The first checks to ensure that the default action is called when no action is provided. The second checks to ensure that the login form is present on that page (by using a CSS selector to find a form with the id of 'login'). The third checks to see if I get a valid authentication session when logging in with good credentials, and that I get redirected to the appropriate location.

This is, of course, just the tip of the iceberg; I've created a couple dozen other assertions as well.

You can preview the functionality in the Zend Framework standard incubator; look for Zend_Test_PHPUnit_ControllerTestCase in there, as well as the Zend_Test documentation in the documentation tree (in human-readable DocBook XML).

For those of you who decide to start playing with this, I'd love any feedback I can get. The best place to do so, however, is on the fw-mvc mailing list; instructions are on the ZF wiki.

Testing Zend Framework MVC Applications was originally published 30 June 2008 on https://mwop.net by Matthew Weier O'Phinney.

First off, for those ZF users who are using other Javascript toolkits: Zend Framework will continue to be basically JS toolkit agnostic. You will still be able to use whatever toolkit you want with ZF applications. ZF will simply be shipping Dojo so that users have a toolkit by default. Several points of integration have been defined, and my hope is that these can be used as a blueprint for community contributions relating to other javascript frameworks. In the meantime, developers choosing to use Dojo will have a rich set of components and integration points to work with.

The integration points we have defined for our initial release are as follows:

• JSON-RPC Server: We are re-working the Zend_Json_Server that has been in our incubator since, oh, what? 0.2.0? and never released to actually follow a specification: JSON-RPC. This will allow it to work seamlessly with Dojo, as well as other toolkits that have JSON-RPC client implementations. I have actually completed work on this, though the proposal is waiting to be approved; if you want to check it out, you can find it in the ZF svn.

  The original Zend_Json_Server implementation will be abandoned. It was never fully tested nor fully documented, which has prevented its release. Additionally, since it implemented its own ad-hoc standard, it did not provide the type of interoperability that a true JSON-RPC server implementation will provide. I am excited that we will finally be able to provide a standards-compliant solution for general availability.

  One final note: there are currently two different JSON-RPC specifications, 1.0 and 2.0. Currently, the implementation I've been working on will switch payload formats based on the request, and can deliver different SMD formats appropriately as well.

• dojo() View Helper: Enabling Dojo for a page is not typically as trivial as just loading the dojo.js script — you have a choice of loading it from the AOL CDN or a local path, and also may want or need to load additional dojo, dijit, or dojox modules, specify custom modules and paths, specify code to run at onLoad(), and specify stylesheets for decorating dijits. On top of this, this information may change from page to page, and may only be needed for a subset of pages. The dojo() view helper will act as a placeholder implementation, and facilitate all of the above tasks, as well as take care of rendering the necessary style and script elements in your page.

• Form Element implementations: One area that developers really leverage javascript and ajax toolkits is forms. In particular, many types of form input can benefit from advanced and rich user interfaces that only javascript can provide: calendar choosers, time selectors, etc. Additionally, many like to use client-side validation in order to provide instantaneous validation feedback to users (instead of requiring a round-trip to the server). We will be identifying a small group of form elements that we feel solve the most relevant use cases, and write Dojo-specific versions that can be utilized with Zend_Form. (One thing to note: Zend_Form's design already works very well with Dojo, allowing many widgets and client-side validations to be created by simply setting the appropriate element attributes.)

• dojo.data Compatibility: dojo.data defines a standard storage interface; services providing data in this format can then be consumed by a variety of Dojo facilities to provide highly flexible and dynamic content for your user interfaces. We will be building a component that will create dojo.data compatible payloads with which to respond to XmlHttpRequests; you will simply need to pass in the data, and provide metadata regarding it.

So, some examples are in order. First off, Zend_Json_Server operates like all of ZF's server components: if follows the SoapServer API. This allows you to attach arbitrary classes and functions to the server component. Additionally, it can build a Service Mapping Description (SMD) that Dojo can consume in order to discover valid methods and signatures. As an example, on the server side you could have the following:

// /json-rpc.php
// Assumes you have a class 'Foo' with methods 'bar' and 'baz':
$server = new Zend_Json_Server();
$server->setClass('Foo')
       ->setTarget('/json-rpc.php')
       ->setEnvelope('JSON-RPC-1.0')
       ->setDojoCompatible(true);

// For GET requests, simply return the service map
if ('GET' == $_SERVER['REQUEST_METHOD']) {
    $smd = $server->getServiceMap();
    header('Content-Type: application/json');
    echo $smd;
    exit;
}

$server->handle();

On your view script side, you might then do the following:

<h2>Dojo JSON-RPC Demo</h2>
<input name=\"foo\" type=\"button\" value=\"Demo\" onClick=\"demoRpc()\"/>
<? 
$this->dojo()->setLocalPath('/js/dojo/dojo.js')
             ->addStyleSheetModule('dijit.themes.tundra')
             ->requireModule('dojo.rpc.JsonService');
$this->headScript()->captureStart(); ?>
function demoRpc()
{
    var myObject = new dojo.rpc.JsonService('/json-rpc.php');
    console.log(myObject.bar());
}
<? $this->headScript()->captureEnd() ?>

And, finally, in your layout script, you might have the following:

<?= $this->doctype() ?>
<html>
    <head>
        <title>...</title>
        <?= $this->dojo() ?>
        <?= $this->headScript() ?>
    </head>
    <body class=\"tundra\">
        <?= $this->layout()->content ?>
    </body>
</html>

The example doesn't do much — it simply logs the results of the JSON-RPC call to the console — but it demonstrates a number of things:

• dojo() View Helper: The example shows using dojo from a local path relative to the server's document root; using the 'Tundra' stylesheet shipped with Dojo and attaching it to the layout; capturing a required module (dojo.rpc.JsonService); and rendering the necessary Dojo stylsheet and script includes in the layout.
• JSON-RPC client: Dojo requires that you point the JsonService to an endpoint that delivers a Service Mapping Description; in this example, I use any GET request to return the SMD. Once the SMD is retrieved, any methods exposed are available to the Javascript object as if they were internal methods — hence myObject.bar(). Dojo's current implementation performs all other requests as POST requests, passing the data via the raw POST body.

There will be more to come in the future, and I will be blogging about developments as I get more proposals up and code into the repository. All in all, this is a very exciting collaboration, and should help provide ZF developers the ability to rapidly create web applications with rich, dynamic user interfaces.

Update: Andi has posted an FAQ on our integration.

Zend Framework Dojo Integration was originally published 21 May 2008 on https://mwop.net by Matthew Weier O'Phinney.

Here's the short version:

• One trip to Belgium and The Netherlands.
• Two trips to Israel.
• Two trips to Atlanta, GA (not counting the return trip from Europe, when I was stranded for a day due to storms in the Northeast).
• Three different user groups attended, with three presentations.
• One major Zend Framework release
• One PEAR release.
• One podcast.
• One webinar.
• One book published.
• One conference attended.

What follows is my month-by-month breakdown:

January

I finished up the last of my three chapters for The PHP Anthology, 2nd Edition, and promptly used my advance to buy the family a Wii.

I was also introduced to Ivo Jansch through work, and had him wow me with one of the ibuildings products.

February

Mid-month, my boss at Zend, Boaz, got the go-ahead to use the ibuildings WDE platform to build our new website CMS; part of the plan would include training at the ibuildings home office in Vlissingen, NL… which meant I had to get my passport pronto.

Towards the end of the month, I was invited to BostonPHP to present building a simple Zend Framework CRUD application, along with Chuck Hagenbuch of the HORDE project. While there, Nate Abele heckled me, and then joined Chuck and myself for an impromptu framework panel; a good time was had by all.

March

I flew to Brussels, Belgium, where I met my supervisor, Boaz, so we could go to Vlissingen. We spent the day in Brussels, walking around and visiting such sites as the Cathedral of St. Michael, La Grand Place, and the Mannekin Pis.

Our visit to ibuildings was very productive, and I was very impressed by the team there; everybody was very knowledgeable and skilled. I presented a Zend Framework overview, as well as an abbreviated version of the Best Practices talk I'd given with Mike Naberezny at the 2006 ZendCon; the latter ignited a ton of questions and enthusiasm.

On returning home, I had a ton of work to do on the zend.com CMS, and this continued in spurts through November. The job was made much easier by the ibuildings WDE product.

I closed out a ton of MVC issues in the Zend Framework, and we released the first beta version late in the month.

April

At the beginning of the month, our landlord threw us for a loop and announced he was going to sell our apartment… meaning that we either had to step up our plans to purchase a home, or start looking for a new rental. Ultimately, we ended up looking for a rental, due to time constraints. The next two months would be highlighted with the look for a new place as well as countless showings of our apartment to potential buyers.

Mid-month, we packed up the family and flew down to Atlanta, GA, to visit my wife's family. While there, we were able to go to the Atlanta Zoo and see Mei Lan, their baby panda — way cute!

May

Mid-month, we found a new place in Richmond, VT — a small village about 10 minutes from Burlington, near where we originally lived when we first moved to Vermont.

During the first RC for Zend Framework, released at the end of the month, I introduced the ViewRenderer, a feature for auto-rendering views based on the current controller and action name — a feature common to many frameworks. However, it ostensibly broke a ton of existing applications by being enabled by default — not one of my more popular decisions. Since the 1.0.0 release, I've heard little grumbling about it, and it's now often cited as an ease-of-use feature — go figure.

June

The first week of June, I flew to Tel Aviv, Israel, to start training people on the new CMS, as well as to work with our entire ebiz team to finalize the work plan for completing the CMS. It was, needless to say, my first time to Israel or the Middle East, and I was constantly confronted with culture shock. Europe was an easy transition to make, but Israel was completely foreign to me — everything from the way people drove, to the architecture, to the food was different. Unfortunately, I arrived a day late due to a flight cancellation, and missed the tour of Jerusalem my supervisor had planned for all of us. However, he took me to the city of Jaffa, an Arabic city where the Israeli's originally tried to settle before building Tel Aviv to the north. The architecture was amazing, as were the winding, narrow streets of the old city.

I was also told during this trip that Andi had requested transferring me full-time to the Zend Framework team. I would spend the next week or two weighing my options, and ultimately decided to do so.

A week after I returned, we moved into our new rental in Richmond. The kids love the new place, which has a bedroom for each of them, a yard, and porches on each entrance.

Somehow, I also found time to record my first (and so far only) PHP Abstract podcast.

July

We released Zend Framework 1.0.0 at the beginning of the month, marking our first stable release. While many still view it as incomplete, the overwhelming feedback has been positive, and we've had over 2 million downloads to date.

I accepted the transfer to the Zend Framework team, but the condition was made that I would stay part-time on the ebiz team until the new site was launched. This meant that the next 5 months were spent splitting my time between the two projects, often working late and on weekends to get work done.

Towards the end of the month, we took a long weekend camping in Vermont's Northeast Kingdom. The weather was unseasonably wet, but we persevered and had a great time. 5 days of offline time was definitely needed!

I also finally released the first stable version of File_Fortune on PEAR, over a year since I'd first proposed it. The package interfaces with mod_fortune files, allowing both the ability to read and write such files, with full binary compatability.

August

Not much to report in August, except work, work, and more work.

September

My ebiz supervisor, Boaz, flew me to Tel Aviv for a second time, this time to perform a "brain dump" for the rest of the team before I transitioned fully out of the team, and also to help setup our new data center and release procedures. This time, Boaz took me to Jerusalem himself during my last full day in the country. If you've never been to the city, you should definitely put it on your list of things to do before you die. With my degree in religion, the place was full of meaning for me, but it would be putting it lightly to say that religion is palpable in the air there. We visited the Wailing Wall, the Via Dolorosa, the Church of the Holy Sepulchre, and listened to the muezzins sing the call to prayer for the muslims. The tour was simply amazing.

A few days after I returned, I flew down to New York City for a special meeting of NYPHP, where Mark de Visser presented on various Zend products and initiatives, and I gave a Zend Framework overview.

A week after the NYPHP presentation, I did a zend.com webinar on the Zend Framework MVC layer.

October

October was the month of ZendCon. I presented a full-day tutorial on best practices and unit testing with Sebastian Bergmann and Mike Naberezny; despite the length and subject matter, we were SRO for most of the day.

I also did a main-stage presentation on Zend Framework's MVC components, directly following Terry Chay — an intimidating situation at best. From the feedback I've seen, the presentation was well-received, and I had somewhere between 120 and 150 attendees — phenomenal! (Even more amazing was how many people were familiar with MVC in general!)

One great thing about the conference was the fact that I got to network with a number of framework developers, both Zend Framework and otherwise, including Nate Abele of CakePHP as well as Paul M. Jones of the Solar framework. Many good conversations were had.

Late in the month, The PHP Anthology, 2nd Edition, my first published book as an author, was finally released!

November

I spent much of the month working on Zend_Layout, a much requested component that simplifies and automates Two Step Views in Zend Framework. I also started work implementing Zend_View Enhanced, a set of view helpers for making complex views with Zend_View possible.

I also started playing with Twitter a bit, and came up with a Zend_Service_Twitter proposal for interacting with the Twitter API via PHP.

And finally, the Sunday before Thanksgiving, we finally launched the new Zend.com site, which was well-received in the blogosphere.

December

A goal I've had for some time has been to form a PHP user group in the Burlington area. A friend of mine pointed out to me sometime this fall that there's actually already a Google Group formed; he and the original founder started planning a meeting for early December. I spoke at this inaugural meeting, presenting Zend Framework's MVC layer yet again; a good time was had by all, and a lot of enthusiasm for future meetings was generated.

I finished up Zend_Layout and Zend_View Enhanced with the help of Ralph Schindler, and got a new proposal up for Zend_Form, just in time for my holidays to begin — 11 days with family and with little to no internet connectivity during a trip to Atlanta, GA for one of only a handful of Christmases I've spent without snow.

Summary

This year was incredibly busy — three cross-seas trips, one cross-continent trip, a move, and several trips along the Eastern Seaboard; three user group presentations, and eight presentations over the course of the year; one conference; one move; one PEAR release; one podcast; one webinar; one book; and countless hours of programming.

My goals for the coming year? I'm too tired to even think about it ;-).

2007 Retrospective was originally published 1 January 2008 on https://mwop.net by Matthew Weier O'Phinney.