Domain Driven Design fits this process as it isolates business logic in the Domain layer and separates it from infrastructure and presentation layers. Questions like where or how to store data or what to build (website, mobile app, API) can be addressed separately.

Doctrine 2 provides PHP developers with a powerful tool to create a Domain layer that contains business logic that is easy to unit test and therefore easy to expand upon in iterations.

In this article I will show how to implement a specific case using Doctrine 2. Full code accompanying this article can be found on GitHub.

In this article

• Case outline
• Description of Entities
  • User
  • TimeSheet
  • TimeSheetStatusChange
  • What’s not included
• Implementing requirements using Doctrine 2
  • User should have an e-mail address that is unique
  • A TimeSheet should always belong to a user which, once specified, cannot be changed
  • A new TimeSheet by default should have a status ‘open’
  • Status changes should only be allowed in specific order
  • A new TimeSheetStatusChange should have a dateApplied that is equal or more recent than the most recent TimeSheetStatusChange
  • TimeSheetStatusChanges must have reference to a TimeSheet but at the same time must be valid.
• Where the domain model goes beyond the database model
• Concluding

Case outline

The application developed is a time registration tool that allows users to enter per-day time sheets and submit them for approval. A manager will approve or disapprove the time sheet. The business requirement this iteration focuses on is the tracking of time sheet status history and only allowing specific status changes. In subsequent iterations features like registrations, tasks, projects and permissions will be implemented.

Description of entities

User

A User can login, has attributes and – interesting for this case – can have timesheets. A user’s email address can be changed at any time but should be unique as it serves as the login name.

TimeSheet

A TimeSheet holds registrations of a single user, the registrant. Those registrations will be reviewed by a manager who will approve or disapprove them on a per-timesheet basis. The timesheet therefore can have the following statuses:

• Open – The default status of every new timesheet
• Submitted – The timesheet has been submitted for approval
• Approved – The manager has approved the timesheet
• Disapproved – The manager has disapproved the timesheet
• Final – The timesheet’s registrations have been processed and therefore can never be changed. Examples of processing are periodic business reports or salary payment.

Status changes will be stored to allow a history of status changes to be shown. The most recent status change reflects the timesheet’s ‘current’ status.

Status changes are only allowed to be added in a specific order.

TimeSheetStatusChange

Each subsequent status of a timesheet is represented by a TimeSheetStatusChange. Properties of a status change are the status and the date the new status has been applied. Once stored, the status and date properties of a status change are not allowed to change to prevent ‘breaking’ the history of status changes a timesheet went through.

What is not included

As mentioned in the case outline, some obvious entities or properties are out of scope, such as the registrations themselves and the date the timesheet applies to. For the business requirements described previously they are not relevant so, in true Agile fashion, they will be implemented in subsequent iterations.

Implementing requirements using Doctrine 2

User should have an e-mail address that is unique

This is achieved by requiring an e-mail address in the constructor and by setting the column definition of the property to be unique.

Domain/Entity/User.php

class User
{
    // ...
 
    /**
     * @Column(type="string", length=128, unique=true)
     * @var string
     */
    private $email;
 
    // ...

A TimeSheet should always belong to a user which, once specified, cannot be changed

This is enforced by requiring a User entity to be supplied in the constructor. As there’s no point in changing the registrant of an existing TimeSheet, the registrant can only be specified on creation. Therefore there is no setter for the registrant property.

(See next code example)

A new TimeSheet by default should have a status ‘open’

In the TimeSheet constructor, a new TimeSheetStatusChange is created and added to the status changes.

Domain/Entity/TimeSheet.php

class TimeSheet
{
    // ...
 
    /**
     * Constructor requiring a registrant user instance
     * 
     * @param User $registrant
     */
    public function __construct(User $registrant)
    {
    	$this->registrant = $registrant;
 
    	$this->statusChanges = new ArrayCollection();
    	$this->addStatusChange(new TimeSheetStatusChange('open'));
    }
 
    // no setRegistrant()
 
    // ...

Status changes should only be allowed in specific order

This is achieved by validating each TimeSheetStatusChange that is added via the addStatusChange method. Only specific transitions are allowed.

Domain/Entity/TimeSheet.php

class TimeSheet
{
    // ...
 
    /**
     * Performs status change validation logic
     * 
     * @param string $statusChange
     * @return boolean
     */
    protected function _validateNextStatus($nextStatus)
    {
    	// make exception for initial adding of open status
    	if ($nextStatus === 'open' && count($this->statusChanges) === 0) {
    		return true;
    	}
 
    	// validate status changes map
    	$allowedChangeMap = array(
    		'open' => array('submitted'),
    		'submitted' => array('approved', 'disapproved'),
    		'approved' => array('final', 'disapproved'),
    		'disapproved' => array('submitted', 'approved'),
    		'final' => array(),
    	);
 
    	$currentStatus = $this->getStatus();
    	if (in_array($nextStatus, $allowedChangeMap[$currentStatus], true)) {
    		return true;
    	}
 
    	return false;
    }
 
    // ...
}

A new TimeSheetStatusChange should have a dateApplied that is equal or more recent than the most recent TimeSheetStatusChange

The dateApplied property is settable because it can’t be assumed that the time at which the change is entered into the application reflects the actual time of the change (An example would be paper forms that are collected and entered once a week). Therefore the dateApplied property is validated at the same time the status is validated. Furthermore, once added, the dateApplied property cannot be changed so there is no setter. When loading a TimeSheet, the TimeSheetStatusChanges are fetched in order by specifying the orderBy attribute in the association.

Domain/Entity/TimeSheet.php

class TimeSheet
{
    // ...
 
    /**
     * @OneToMany(targetEntity="Domain\Entity\TimeSheetStatusChange", mappedBy="timeSheet", cascade={"persist"}, orphanRemoval=true)
     * @OrderBy({"dateApplied" = "ASC", "id" = "ASC"})
     */
    private $statusChanges;
 
    // ...
 
    /**
     * Validates if the date of the statusChange given is later than the date
     * of the last statusChange present
     */
    protected function _validateNextStatusChangeDate(TimeSheetStatusChange $statusChange)
    {
    	// if no statusChanges present yet any date is valid
    	if (count($this->statusChanges) === 0) {
    		return true;
    	}
 
    	$currentDate = $this->getLastStatusChange()->getDateApplied();
    	$nextDate = $statusChange->getDateApplied();
 
    	// enable once tests finish
		return ($nextDate >= $currentDate);
    }
 
    // ...
}

TimeSheetStatusChanges must have reference to a TimeSheet but at the same time must be valid.

It can be prevented to store a TimeSheetStatusChange without reference to a TimeSheet by explictly specifying the joinColumn and setting the nullable attribute to false.

Domain/Entity/TimeSheetStatusChange.php

class TimeSheetStatusChange
{
    // ...
 
    /**
     * @ManyToOne(targetEntity="Domain\Entity\TimeSheet", inversedBy="statusChanges")
     * @JoinColumn(name="timesheet_id", referencedColumnName="id", nullable=false)
     */
    private $timeSheet;
 
    // ...
}

This still leaves the possibility to set ‘any’ TimeSheet and thereby skipping validation that would normally be done in TimeSheet::addStatusChange(). To prevent this, TimeSheetStatusChange::setTimeSheet() verifies if the TimeSheet’s last status is the current TimeSheetStatusChange instance.

Domain/Entity/TimeSheet.php

class TimeSheetStatusChange
{
    // ...
 
    /**
     * Sets the timeSheet.
     * 
     * Purpose is to have the reference to the timeSheet set when adding a 
     * new TimeSheetStatusChange to a TimeSheet. Therefore this method validates
     * if the timeSheet has the this instance as the last statusChange.
     * 
     * @param TimeSheet $timeSheet
     */
    public function setTimeSheet(TimeSheet $timeSheet)
    {
    	if ($timeSheet->getLastStatusChange() !== $this) {
    		throw new \InvalidArgumentException('Cannot set TimeSheet if not having current instance as lastStatusChange');
    	}
    	$this->timeSheet = $timeSheet;
    }
    // ...
}

The result is that the only way to create a persistable TimeSheetStatusChange is by adding it to the TimeSheet which will:

1. Validate if the status change is allowed
2. Adds it to the list of status changes, making it the ‘last’ status change
3. In turn set the timeSheet reference on the TimeSheetStatusChange

Persisting a TimeSheet is propagated to the status changes by setting the cascade attribute in the association definition

Domain/Entity/TimeSheet.php

class TimeSheetStatusChange
{
    // ...
 
    /**
     * @OneToMany(targetEntity="Domain\Entity\TimeSheetStatusChange", mappedBy="timeSheet", cascade={"persist"}, orphanRemoval=true)
     * @OrderBy({"dateApplied" = "ASC", "id" = "ASC"})
     */
    private $statusChanges;
 
    // ...
}

Where the domain model goes beyond the database model

One might be tempted to see an ORM as merely a convenient way to access and manipulate data contained in a database. While Doctrine 2 fits such a scenario (Entities can be modeled to reflect an already existing database) the real power shines when entities are modeled with business logic in mind instead of just being a collection of setters and getters matching the database fields.

Features displayed in these examples that can not be expressed in a database model include:

• Forcing each timesheet to start with a status ‘open’
• Only allowing specific timesheet status changes:
  • By preventing ‘floating’ timesheetsStatusChanges to be created.
  • By preventing change of dateApplied and status properties, once created
• Make values, once persisted immutable. (the registrant property of a timesheet, the status and dateApplied properties of a timesheetStatusChange)

Concluding

As the previous example shows, a Domain model is more than a database model: It should be modeled to comply with business logic required. As a result, for the code in this article I have used Doctrine tools only for creating entity proxies, not the entities themselves

Furthermore, the fact that business logic is only contained in the Domain layer is illustrated by the facts that in this setup:

• There is no front-end
• There is no framework (Zend Framework, Symfony, Cake, Yii, Solar, all possibilities are open)
• There is no specific database. For the tests an in-memory SQLite database is used. In production this will obviously not be the case.

Because of this isolation from other layers, domain logic is easily testable as can be seen from the test cases.

Credits for the test setup used here go to the example found on Giorgio Sironi’s ddd-talk GitHub page.

In future articles I intend to expand on this case, showing how Domain Driven Design can be used in an Agile development process.

Day 1

• TDD and Getting Paid – Because indeed TDD is good and can be hard to keep doing thoroughly
• Pursuing practices of Domain-Driven Design in PHP – Fits both the ‘interesting’ and ‘directly usable’ categories. Based on the numerous articles by Giorgio I have high expectations
• Cooking up your development environment – Tools I don’t know, yet a subject that’s very real
• Simplify your external dependency management – Or the Uncon, depending on the schedule
• Implementing Comet using PHP – Interesting new stuff (for me that is)
• Zend Framework 2.0: what’s new and what’s changed? – However, Advanced OO Patterns looks interesting too
• Conference social – yup

Day 2

• Pofiling, OAuth, new era of PHP Frameworks – All interesting, to be decided
• Managing a shared MySQL farm – Because I expect to hear more new things than at the Zend Framework optimization talk
• Agility and Quality, Modular application architecture and Character sets that suck (they do!) – Tough one once again. I think Agility and Quality
• Practical Git – I think, because there’s a lot to learn there, although Zend Framework i18n looks interesting too
• Keynote: Open Teams – Will probably be insightful as well as enjoyable

Now I only need to print the ticket, bookmark this page on my iPhone and I’m off to go. Till friday!

Usability considerations

There are some things to consider to determine if such automatic focusing of a search field is actually helpful to the user navigating to the page. Who is the user?

As I was discussing this case with an interaction designer friend (dutch) of mine, he brought up the idea of mimicking the browser’s backspace behaviour, and discussing it further we concluded that this might be useful in some cases but is definitely not a ‘one size fits all’ solution.

Different goals

Different users will probably have different goals when navigating to a page. On the google page or a login screen the majority of the users’ goal is to type something in the first input field. On a lot of other pages this won’t be so obvious. Question then is: Will focusing a search field, if not help, instead hinder the user? For example: A user might have navigated to a page by accident. In that case not being able to go to the previous page by pressing ‘backspace’ might indeed hinder the user.

Different expectations

Not every user navigates to the previous page by using ‘backspace’, some might not even be aware of that possibility. Not every user expects text entered to automatically appear in an input field. Some users might have enabled the option to directly find text in a page when typing text and find this functionality suddenly broken.

Dive into HTML5 has some other nice examples of how autofocus might not be helpful.

What size fits all?

As mentioned before, there is no ‘one size fits all’ solution. Questions that need to be asked include:

• How many users might be helped by adding autofocus to a common search field?
• How many users might instead be hindered by autofocus?
• Are there pages where autofocus on more specific fields (like the main form) is needed which will break consistency throughout the site?

This means studying your site, the target audience, their goals and expectations and based on that finding a balance.

Restoring the backspace: jQuery autofocusBackspace plugin

If the conclusion of aforementioned considerations is that autofocus indeed is helpful, there is more than one way to achieve this: The first is using the HTML5 autofocus attribute. Another is using javascript to focus the field.

As not all browsers support the autofocus attribute yet, and we wanted to preserve the browser’s backspace functionality, I created a jQuery plugin that does just that:

• It focuses the first matching element
• It responds to ‘backspace’ by navigating to the previous page.
  • Only until a user has entered text
  • Only until the element loses focus

Refer to GitHub for the jQuery plugin autospaceBackspace.

Feel free to report problems or ideas for improvement.

Although it is possible to specify the socket by using mysqldump’s --socket switch, that doesn’t really seem a ‘solution’.

Apparently mysqldump, as opposed to the mysql client does not use the server-specific settings contained in /usr/local/zend/mysql/data/my.cnf. The comments in my.cnf state:

# You can copy this file to
# /etc/my.cnf to set global options,
# mysql-data-dir/my.cnf to set server-specific options (in this
# installation this directory is /usr/local/zend/mysql/data) or
# ~/.my.cnf to set user-specific options.

After copying /usr/local/zend/mysql/data/my.cnf to /etc/my.cnf mysqldump worked as expected.

In /etc/my.cnf I have included only the setting needed to get mysqldump running:

# Specifying socket to use for mysql/mysqldump
# For other settings refer to /usr/local/zend/mysql/data/my.cnf
[client]
socket      = /usr/local/zend/mysql/tmp/mysql.sock

Hope this saves anyone running into the same issue some time.

Update (alternative solutions):
As Joel Clermont pointed out it is also possible to create a symlink on the socket location expected by mysqldump to the real socket location. This can be done by executing:

ln -s /usr/local/zend/mysql/tmp/mysql.sock /tmp/mysql.sock


Another possible approach is to create a symlink at /etc/my.cnf to /usr/local/zend/mysql/data/my.cnf. This has the downside that it requires loosening the default permissions (drwxr-x---) on the data folder by allowing ‘others’ to enter it. Commands to execute:

sudo chmod o+x /usr/local/zend/mysql/data
sudo ln -s /usr/local/zend/mysql/data/my.cnf my.cnf

Granting more permissions can be a security consideration but on most development setups this probably won’t be an issue.

Additional info about Zend Server CE on OS X:

• Zend Server CE Documentation
• Rob Allen: Some notes on Zend Server CE for Mac OS X

Among the presentations I attended on the first day were:

Kevlin Henney’s keynote presentation, titled 97 Things every programmer should know. I suppose every attendant will have recognised some of the things he addressed, like “Do lots of deliberate practice” or “Hard work does not pay off”.

Design for Reusability. In this presentation Derick Rethans showed a number of concepts that can help in making code more reusable. Topics included Dependency Injection Containers, the fact that private methods can never be tested and Tie-Ins. Interesting was that Derick stated that reflection is slow whereas on day 2, in the Doctrine 2 uncon talk reflection was said to be be reasonably fast (in php 5.3 that is).

Database version control by Harrie Verveer was a very interesting talk, if only for the fact that it is a topic I’m confronted with at my day job. He showed tools like DbDeploy (and Phing), Liquibase, Doctrine Migrations and Akrabat DB Schema Manager. Especially ineresting was how branching can trouble database versioning.

Stephan Hockdoerfer’s presentation Testing untestable code showed some very unorthodox examples of how to test code that seems untestable, like replacing function names, manipulating the include path or mocking the filesystem. Interesting and besides that it’s great stuff to scare co-workers with (“look what trick I’ve learned!”).

Due to an unlucky combination of a tiresome week, a busy schedule ahead, a lot of time to kill until 20:30, and possibly age, I missed the social, so I was not devastated when day 2 started.

First presentation of day 2 was titled Security Centered Design: Exploring the Impact of Human Behaviour by Chris Shiflet. Emphasis was not on the technical aspects but on the people using an application. The presentation contained a very effective demonstration of ‘change blindness’. Quote of the presentation, and as far as I’m concerned whole DPC10: ” If you focus on the technical problem you’re missing the actual problem”

Following the keynote talk, Rob Allen covered the topic of Stress-free deployment. There was some overlap with the database versioning talk of the previous day but still a lot to learn. Especial interesting I found the part about branching, where Rob showed how branching features as well as releases can be a good solution for some pitfals concerned with release management. Not entirely in line with the branching ‘problems’ mentioned in the database versioning talk so it’s definitely a subject I’ll look into further.

After the lunch I visited the Unconference room which I didn’t regret. Jeroen Keppens opened with a short presentation on a topic we need to look into at my job in the near future: Integrating Zend_Acl and the domain layer. Short but very insightful. After two presentations about development for mobile devices (PhoneGap looks very interesting) and Cairo I decided to stay in the uncon room some more (thereby skipping the Domain NoSQL talk) as next on were two ORM-centered presentations: First Juozas Kaziukenas explained the principles of an ORM, followed by Benjamin Eberlei giving insight on Doctrine2. That looked promising yet also, after viewing the generated SQL of some of the more complex examples, spawned a very interesting discussion I had with my co-worker who visited Sebastian Bergmann’s presentation The Cake is A Lie: What problems can arise from generated code that isn’t tested and nobody is responsible for?

Concluding: Similar to past years this was a refreshing event that fuels the urge to improve by adopting new techniques and better methodologies. Besides that I really liked the Unconference initiative. Till next year!

• DPC 2010 slides (joind.in)
• Twitter: #dpc10 and #dpc_uncon

• dynamically construct a form based on the data being edited
• use subforms to reuse common parts and group related values
• create composite ‘elements’ by using the default Zend_Form_Element in combination with a custom decorator
• create additional elements with Javascript and have them processed by the form when submitted

Like previous article the case examined assumes a situation where Zend_Form is used in an existing project that doesn’t use the Zend Framework MVC stack. The Form can be viewed online and all of the sample code can be found on GitHub.

Case outline

In this example I construct a form where a user can view and edit a task list for a week’s working days. Every task can be edited in one single form and new tasks can be added at will. When viewing the page the application fetches the tasks already entered for that week. The assumed codebase is able to generate and consume an array as shown below:

// array format used to supply data of multiple tasks to form
$tasks[$timestampDay1]['current'][$taskId1]['desc'] = 'Gotta do this';
$tasks[$timestampDay1]['current'][$taskId1]['completed'] = true;
$tasks[$timestampDay2]['current'][$taskId2]['desc'] = 'Gotta do that';
$tasks[$timestampDay2]['current'][$taskId2]['completed'] = false;

The ‘current’ part will later help to distinguish between new and allready stored tasks.

Dynamically building a Zend_Form

Using Zend_Form typically follows these steps:

$Form = new My_Form(); // My_Form::init() will define elements
$Form->setDefaults($myData);
if ($Form->isValid($_POST)) {
    $submittedValues = $Form->getValues();
    // process values and redirect to same or other page
}
echo $Form->render();

When a form’s elements need to be defined based on the data being edited, Zend_Form::init() is not suitable as at that point the data is not known yet. Providing data through the constructor to have it available in the init() method ‘could’ work but is not a really nice solution as it means changing the parameter scheme of the constructor. Furthermore, it would ignore the method that exists specifically for adding initial data: setDefaults(). As that will be the first point at which the form ‘knows’ what data needs to be edited, that will be the point to add elements. Or, as in this case, subforms.

My_Form_TaskWeek

The setDefaults() method of the week-form is changed as displayed below:

class My_Form_TaskWeek extends Zend_Form
{
    // ...
    public function setDefaults($defaults)
    {
        // first add the subforms
        $this->clearSubForms();
        $dates = array_keys($defaults);
        foreach ($dates as $day) {
            $dayForm = new My_SubForm_TaskDay();
            $this->addSubForm($dayForm, (string) $day);
        }
        // set defaults, which will propagate to newly created subforms
        parent::setDefaults($defaults);
    }
    // ...
}

For every day in $defaults (in this example the key is a timestamp, but it could be anything) a subform is added. This is done before calling parent::setDefaults(). With the subforms in place the call to the parent method will propagate to the subforms we’ve just created.

My_Form_TaskDay

In the form that shows one single day, some actions are performed in the init() method: A subform for both ‘current’ and ‘new’ elements is added. Also a ‘template’ element is added. The subforms have just one decorator: FormElements. The template element will be used as source for new elements that are added by javascript. When setDefaults() is called, elements are added to the current subform.

 class My_SubForm_TaskDay extends Zend_Form_SubForm
{
    // ...
   public function init() {
        // create subforms having nothing but element decorator
        $this->addSubForm(new Zend_Form_SubForm, 'current');
        $this->addSubForm(new Zend_Form_SubForm, 'new');
        $this->getSubForm('current')->setDecorators(array('FormElements'));
        $this->getSubForm('new')->setDecorators(array('FormElements'));
 
        // add template element
        $templateElement = $this->createTaskElement('__template__', array(), true);
        $this->getSubForm('new')->addElement($templateElement);
    }
 
    public function setDefaults($defaults)
    {
        $subform = $this->getSubForm('current');
        foreach ($defaults['current'] as $id => $values) {
            $subform->addElement($this->createTaskElement($id, $values));
        }
        // set defaults, which will propagate to newly created subforms & elements
        parent::setDefaults($defaults);
    }

The method that creates an element:

    protected function createTaskElement($id, $values, $isNew = false)
    {
        $elm = new Zend_Form_Element((string) $id);
        $elm->clearDecorators();
        $elm->addDecorator(new My_Decorator_TaskElement());
        $elm->addDecorator('Errors', array('placement'=>'prepend'));
 
        // add configured validator
        $validator = new My_Validator_TaskElement();
        $validator->setIsNew($isNew);
        $elm->addValidator($validator);
 
        return $elm;
    }

Creating composite elements by using custom decorator

As the code above shows, creating a task element consists of three steps:

Zend_Form_Element

A basic Zend_Form_Element is created. This is the ‘root’ class of which specific element-types (like Zend_Form_Element_Text) are descendants. The Form will supply each element with the element’s value which in this case will be an associative array with the keys ‘desc’ and ‘completed’.

My_Decorator_TaskElement

A custom decorator is added: My_Decorator_TaskElement. This decorator replaces what would normally be the ViewRenderer decorator. It is responsible for rendering both the text and checkbox input elements and wraps them in a div. For the template element (based on the element name) the containing div will be given a classname ‘template’ which will be of use when creating the javascript behaviour.

    public function render($content)
    {
        // get element details
        $elm = $this->getElement();
        $value = $elm->getValue();
        $elmName = $elm->getFullyQualifiedName();
 
        // construct inputs
        $isCompleted = isset($value['completed']) && $value['completed'];
        $descValue = (isset($value['desc'])) ? htmlspecialchars($value['desc']) : '';
 
        $inputDesc = sprintf(
            '<input type="text" name="%s" value="%s" />',
            $elmName . '[desc]',
            $descValue
        );
        $inputCompleted = sprintf(
            '<input type="checkbox" name="%s" value="1" %s />',
            $elmName . '[completed]',
            ($isCompleted) ? 'checked="checked"' : ''
        );
 
        // wrap in div, optionally adding attribute class
        $elmHtml = sprintf(
            '<div class="task %s">%s%s</div>',
            ($elm->getName() == '__template__') ? 'template' : '',
            $inputDesc,
            $inputCompleted
        );
 
        // this should be the first decorator but add the content for
        // consistency's sake
        return $content . $elmHtml;
    }

My_Validator_TaskElement

A custom validator is added: My_Validator_TaskElement (see code on GitHub). This validator will check if the description is empty but treats new elements differently from existing ones: For existing elements it is not allowed to have an empty description. For new elements this is only allowed if the ‘completed’ checkbox isn’t checked. (This way a user can still submit the form if he’d accidentally added a new field).

Using jQuery to let the user add new elements

The javascript that lets a user add a new element is implemented as a jQuery plugin. The code having the javascript initiate looks as follows:

$(document).ready(function() {
    $('form .taskDay').dynamicForm();
});

As can be seen each of the ‘day’ subforms outer elements is selected and applied upon a jQuery plugin. This plugin (on GitHub)performs the following tasks:

• Within the element it operates on it searches for an element with classname ‘add’ and attaches a ‘click’ event handler to it.
• It searches for an element ‘template’ and stores a reference to it.
• Whenever the user clicks the ‘add’ button, the template element is cloned
• Within the template element the ‘name’ attribute of any input element is altered: The string ‘__template__’ is replaced by a timestamp. This makes sure that multiple new tasks can be added within a day without them interfering with each other.
• The new element is placed after the last found element with classname ‘task’

By referring to classnames, the javascript’s dependencies on the exact HTML are kept to a minimum. This way, if needed, the HTML structure of the form elements can be changed without the need to update the javascript.

Having the form process the new elements

When the task form is submitted, newly added tasks will be in the $_POST array as shown below:

// is assoc. array having 'desc' and 'completed' keys
$_POST[$dayTimestamp]['new'][$uniqueJSCreatedValue];

The form object needs to be able to validate the input for both the existing and the new tasks, so the $_POST array is passed to the isValid() method. At this point the form doesn’t yet contain the ‘new’ elements. Adding those is done in a similar fashion to how the existing elements are added in setDefaults(), only this time it is done in isValid(). That is the first point where the form is able to determine what the new elements are. Dynamically adding the new elements happens in the ‘day’ subform:

class My_SubForm_TaskDay extends Zend_Form_SubForm
{
    // ...
    public function isValid($data) {
        $subform = $this->getSubForm('new');
        // make sure new is array (won't be in $data if nothing submitted)
        if (!isset($data['new'])) {
            $data['new'] = array();
        }
        foreach ($data['new'] as $idx => $values) {
            // Don't add element with idx = __template__. SetIgnore works on
            // getValues. Template elements are submitted so this would otherwise
            // override the previously added template element, thereby losing the
            // setIgnore setting...
            if ($idx !== '__template__') {
                $subform->addElement($this->createTaskElement($idx, $data, true));
            }
        }
        // call parent, which will populate newly created elements.
        return parent::isValid($data);
    }
    //...
}

Here the aforementioned createTaskElement() method pops up again. Notice the third parameter (true) that will make the validator treat the element as a ‘new’ one.

All done, except for …

In theory now everything works. But practice tends to have those little things that go wrong which you hardly ever read about in code examples. When working on this example I noticed that getValues() doesn’t preserve the per-day timestamp keys in the array returned. Instead, it returns an indexed array like this:

$getValues = array(
    // this '0' should have been a timestamp, like: 1261350000
    '0' => array(
        'current' => array(), // etc. etc.
        'new' => array() // etc. etc.
    ),
    // ...
);

Bummer. As it appears, Zend_Form ‘requires’ elements, subforms and display groups to have valid variable names (See ZF-4204). One of the reasons is problably that the names also end up in HTML id attributes which are not allowed to start with a number. The name attribute is though (you can run the demo form through the W3C validator). Remarkably, the task elements, having a name consisting of the database id, are processed just fine.

Two possible solutions for this:

• Avoid numeric names. Downside is that this also involves changing the existing code generating and processing the array. The day-form header decorator which uses the form’s name to display the date needs to be changed as well.
• Add an implementation of getValues() in My_Form_TaskWeek that checks for numeric keys and changes them back to their original timestamp

I choose the latter (for now) because it allows to leave almost all existing code unaltered and the resulting behaviour is unit testable (supply defaults, test what is rendered, test what is returned, etc.).

Conclusion

The above shows that:

• Subforms are very useful to repeat similar blocks within a form and to group related values in the returned value array.
• Dynamically adding initial and newly submitted elements follows a similar pattern: Add elements based on the passed in array and then call the parent’s method. This is done in setDefaults() and isValid() respectively.

The question might arise ‘is Zend_Form the best solution for this type of customized form?’. The default ViewHelper decorator is ignored, no default validator is used. I can’t tell if Zend_Form is the best solution but fact is that it provides a lot of functionallity and flexibility: The Form, Errors and HtmlTag decorators are used ‘as is’. Furthermore, the option to reuse parts comes almost naturally because of Zend_Form’s design.

Regarding the last point I’ll conclude with following example: What if, some time after having created this form, the idea is born to have some sort of per-day dashboard page where a user can view and edit things like calendar, messages and tasks? (This is the kind of stuff that happens in agile projects). Reusing My_SubForm_TaskDay would be very useful. And luckily that is easily accomplished. All that is needed is wrapping the subform in a class that will additionally:

• Set a view object
• Add a submit button
• Add a Form decorator

See the code of My_Form_TaskDay on GitHub or see it in action online.

Forms in general are elements where a lot of parts of an application ‘meet’: Frontend code (HTML/CSS), behavior (JS) and backend processing (validation, filtering and storage). In this post I’ll show how one can:

• Use Zend_Form outside the Zend Framework MVC (most likely an existing project)
• Separate Form rendering from it’s structure
• Use custom validators and decorators

The Form used in this tutorial can be viewed here. The code can be browsed or downloaded on GitHub.

Zend_Form components at a glance

Let’s start with a quick look at how Zend_Form’s different components are tied together:

• A Zend_Form consists of elements, descendants of Zend_Form_Element
• Elements can be supplied with Validators and Filters
• Both the form and it’s elements depend on Decorators to generate HTML. Decorators form a ‘chain’ where each decorator adds HTML to the result of the previous decorators.
• The standard decorators provided by Zend_Form delegate the rendering of the actual HTML to View Helpers

Using Zend_Form without the MVC

As the last point above shows, Zend_Form, through Decorators, makes extensive use of Zend_View helpers. In a Zend_Framework project Zend_Form is able to retrieve the View itself. In other projects (if one wants to use any of Zend_Form’s default decorators) a View instance has to be supplied to Zend_Form:

$view = new Zend_View();
$view->doctype('XHTML1_TRANSITIONAL');
 
$form = new Zend_Form();
$form->setView(new Zend_View());

In this example the doctype is specified in the view. This controls if input elements are rendered with XHTML self-closing tags.

Separate structure and rendering

In this tutorial I create a form for an admin interface where basic user-details can be edited. Let’s assume an ACL implementation dictates that some people can actually edit the details while others are only allowed to view them. I’ve decided to keep the form definition (the ‘model’ side of a form) to a bare minimum and let different renderers (the ‘view’ side) control the output.

For re-usability and keeping controller code clean one can best create form objects by creating an instance of a subclass of Zend_Form:

class My_Form_User extends Zend_Form
{
    public function init() {
        // username
        $this->addElement('text','username', array(
            'required' => true,
            'validators' => array(
                // arguments: type, breakchain, validator constructor options
                array('Alnum', false, false),
                array('StringLength', false, array(6, 16)),
            ),
        ));
 
        // email
        $EmailValidate = new My_Validator_Email();
        $this->addElement('text','email', array(
            'required' => true,
            'validators' => array(
                array('EmailAddress', false),
                array($EmailValidate, false)
            )
        ));
 
        // ...
    }
}

(As can be seen I create an instance of My_Validate_Email and add that to the email element. We’ll look into that later. First, let’s continue with the form definition.)

The init() method is designed for this type of form definition, thereby avoiding the need to duplicate the constructor and it’s parameter scheme. As can be seen, I only define the form elements and validators. Labels and such I defer to the renderer (more on that later). As this is about integrating Zend_Form into existing projects that are not based on Zend Framework, I assume there is some sort of language-aware component. In this example I use a language pack that returns language-specific results based on tags. Adding a set of checkboxes then looks like this:

class My_Form_User extends Zend_Form
{
    public function init() {
 
        // ...
 
        $lang = new My_LanguagePack();
 
        $groupIds = array(1,2,3,4);
        $groupOptions = array();
        foreach ($groupIds as $id) {
            $groupOptions[$id] = $lang->get('group.label.' . $id);
        }
 
        $elmGroup = new Zend_Form_Element_MultiCheckbox('group');
        $elmGroup->setMultiOptions( $groupOptions );
        $elmGroup->setRequired(true);
        $this->addElement($elmGroup);
    }
}

Now I create two renderer classes for both the ‘edit’ and ‘view’ display mode. Both accepting a Zend_Form instance in the constructor. Code below shows how the form is displayed using either rendering class:

$Form = new My_Form_User();
 
$RendererEdit = new My_Form_Renderer_Edit($Form, 'user_edit');
echo $RendererEdit->render();
 
$RendererView = new My_Form_Renderer_View($Form, 'user_view');
echo $RendererView->render();

But before moving onto the renderers, let’s look into the aforementioned My_Email_Validator class.

Adding a custom validator

When specifying validators by string, as is done with ‘EmailAddress’, Zend_Form adds one of the types of Zend_Validate. For validation not covered by the standard validators one can create a custom validator by extending Zend_Validate_Abstract or implementing Zend_Validator_Interface. For email addresses, a typical scenario would be a custom validator that connects to a database and checks if the given email address is allready used by another user. For this demo I skip the database part, resulting in:

class My_Validator_Email extends Zend_Validate_Abstract
{
    protected $isValid = null;
 
    public function isValid($value) {
        $this->isValid = !in_array($value, array(
            'duplicate@test.com',
        ));
        return $this->isValid;
    }
 
    public function getMessages() {
        if ($this->isValid === false) {
            return array(
                'duplicateEmail' => 'This email address is allready used'
            );
        }
        return array();
    }
 
    public function getErrors() {
        return array_keys($this->getMessages());
    }
}

Now let’s continue with the two renderer classes:

Rendering the edit mode

The basics of the My_Form_Renderer_Edit class constructor are shown below:

class My_Form_Renderer_Edit
{
    protected $form;
 
    protected $lang;
 
    public function __construct(Zend_Form $form, $form_id = null)
    {
        $view = new Zend_View();
        $view->doctype('XHTML1_TRANSITIONAL');
 
        $this->form = $form;
        $this->form->setView(new Zend_View());
        $this->form->setAttrib('class', 'form_edit');
        if (!is_null($form_id)) {
            $this->form->setAttrib('id', $form_id);
        }
 
        $this->lang = new My_LanguagePack();
    }
 
    public function render()
    {
        // ...
}

As can be seen this is where I setup the view (as mentioned before) and set id and classname that can be used in CSS. I want the HTML to look like this:

<ul>
    <li class="">
        <div id="username-label"><label for="username" class="required">* Username</label></div>
        <div class="element">
            <input type="text" name="username" id="username" value="" class="text" />
            <span class="description">(Min 6, max 16 char.)</span>
        </div>
    </li>
</ul>

When the render() method is called on the renderer class I do four things:

• Add a submit element
• Setup element properties that are common for all elements
• Setup properties on a per-element basis
• Setup properties of the form element

I’ll briefly run through those steps. Complete code for My_Form_Renderer_Edit can be seen on Github.

Add a submit element

As long as the submit value doesn’t play a role in the processing of entered data I consider this part of the view layer. For example, interaction design might dictate that on long forms submit buttons are placed both above and below the form.

Setup common properties

By using the method setElementDecorators() of Zend_Form, all default decorators are replaced by the ones specified. The decorators that fit my needs are ViewHelper (renders the element itself) and Description, resulting in:

    protected function setupElementsCommon()
    {
         $this->form->setElementDecorators(array(
            'ViewHelper',
            array('Description', array(
                'placement' => 'append',
                'tag' => 'span',
                'class' => 'description'
            )),
         ));
    }

Setup per-element properties

Here I add additional decorators. First I setup the element’s label and description properties by using the language pack, then I add the appropriate decorators. Furthermore I add some additional classnames to elements. If the element has an error I not only want to display the errors (using a custom decorator, more on that later). I also want to give the HTML element wrapped around all of the parts an ‘error’ classname.

        $elmHasError = (count($elm->getMessages()) > 0);
        $liClass = $elmHasError ? 'error' : '';
        $elm->addDecorator(
            array('outerLi' => 'HtmlTag'),
            array('tag' => 'li', 'class' => $liClass)
        );

Setup the form object

Finally the Form is configured. After removing all existing decorators, three decorators are added. The only difference with the default set of decorators is the UL element used in the HtmlTag decorator:

    protected function setupForm()
    {
        $this->form->clearDecorators();
        $this->form->addDecorator('FormElements');
        $this->form->addDecorator('HtmlTag', array('tag' => 'ul'));
        $this->form->addDecorator('Form');
    }

Adding a custom decorator

The complete code shows that instead of the default ‘Errors’ decorator I provide my own. This way I can retrieve the error messages provided by the form element and then replace them with messages retrieved from the languagePack. A custom decorator needs to extend Zend_Form_Decorator_Abstract or implement Zend_Form_Decorator_Interface. Excerpts from My_Decorator_Errors:

    public function render($content)
        $element = $this->getElement();
        $errorMessages = $element->getMessages();
        if (empty($errorMessages)) {
            return $content;
        }
 
        // iterate over errorMessages, replace or use default
        $errorLinesHtml = '';
        foreach ($errorMessages as $errorCode => $errorMsg) {
            // make an exception for isEmpty and array representing elements
            if ($element->isArray() && $errorCode=='isEmpty') {
                $msgLangPack = $this->lang->get('form.error.array.' . $errorCode);
            } else {
                $msgLangPack = $this->lang->get('form.error.' . $errorCode);
            }
            $errorMsg = ($msgLangPack !== false) ? $msgLangPack : $errorMsg;
            $errorLinesHtml .= '<li>' . $errorMsg . '</li>';
        }
        // combine
        $errorHtml = '<ul class="errors">' . $errorLinesHtml .'</ul>';
 
        // ...

Errormessages are fetched by an element’s getMessages() method that returns an associative array. The error-codes (keys) can be used to translate the message. As can be seen I treat elements representing an array differently when fetching the ‘isEmpty’ error message.

Rendering the view mode

The view renderer is a simplified version of the edit renderer. Main differences are:

• The form doesn’t have a Form decorator and thereby no form tag. (I’ll keep calling the no-form a form though ;)).
• All elements have only one decorator common for all elements: My_Decorator_View_Element
• As the only element decorator doesn’t use Zend_View, the form has no need for a View element.

My_Decorator_View_Element

This decorator retrieves value and label from the element and creates. It then creates HTML making exceptions for:

• Submit elements (which are ignored)
• Array representing elements (where more than one value needs to be displayed)

Concluding

Above examples give an impression of how Zend_Form can be suited to virtually anyone’s needs. One can argue that separating the rendering from the basic definition adds unnecessary complexity. It does however pull HTML specifics (which during a project life-cycle often are subject to change) out of the ‘model’ layer. Both the stripped down forms and renderers are easy to reuse: The renderer can be applied to a number of forms and the forms themselves can be used in projects requiring different HTML.

Even without considering the rendering part, Zend_Form is a valuable platform offering a lot of ways to customize it. As the view renderer example shows it can also operate without Zend_View, provided one doesn’t use any of the built in decorators. Being able to provide self-built elements, validators and decorators makes it possible to use Zend_Form in virtually any project.

Further reading:

• Zend Framework API documentation
• Decorators with Zend_Form
• Rendering Zend Form decorators individually
• Advanced Zend_Form usage

Slides of the presentation (if online) are listed at the Fronteers site and at the end of this post (same content, read along). I’ll briefly recap some of the (for me that is) most interesting parts.

Thursday

After a pre-conference meeting tuesday at Mirabeau (Where Chris Heilmann and Peter Paul Koch hinted at what was to come) Thursday started with two talks concentrating on the mobile web. Summarized: Webkit is not webkit (and webkit is just one of the mobile browsers) and mobile devices are more different from each-other than desktop PC’s. So, developing for the mobile web (and not just the iPhone) is challenging.

Next on was the presentation with the most hilarious title of all (and arguably content also) by Chris Heilman: Of Hamsters, Feature Creatures and Missed Opportunities. Some highlights: Be passionate about what you do as a developer or leave that aspect for someone who is. Don’t reinvent the wheel just because you like to apply a (your favorite) technique. The web is information, not sites. The feature creature (just check the slides) and YQL, which basically is querying the web and looks really great (kinda missed out on that one having done a lot of back-end development lately).

After the lunch-break Stephen Hay covered three drafts that exist for CSS layouts that will take away the limitations that exist today: CSS3-Grid (Microsoft), CSS3-Flexbox (Mozilla) and CSS3-Layout (W3C). Very interesting as it makes very clear that, although a vast improvement over tables, today’s CSS capabilities with respect to layout (and thereby the way we work) are far from perfect.
Following Stephen, John Resig went in-depth on javascript testing techniques covering unit testing as well as functional testing. Furthermore an interesting testing concept that can be used for testing JS frameworks was introduced: TestSwarm. Steve Souders, fully aware of being the last barrier between the crowd and the after-party, concluded the day with some interesting techniques that can help speed up websites.

Friday

Douglas Crockford kicked of day 2 with a presentation about javascript security. He explained Object Capapability Design, a security model in which objects can only access objects they have a reference too. I liked the part about using ‘facet objects’ to control whether or not references are maintained or broken. After that Pete LePage showed some HTML5 stuff that’s found it’s way into IE8. The presentation had a (not the only one) funny moment where in Expression Web’s IE6 emulation it showed the fronteers website with the ‘your (IE6) browser is obsolete’ warning. Jonathan Snook then extensively covered the topic of getting fonts on the web. It was very interesting that he addressed the licensing issues involved with using tools like sIFR. Something I think is often overlooked.

After the lunch Robbert Broersma lifted the hood (just slightly) of the engine powering the Xopus editor. He showed some tips with regard to improving and maintaining performance, most notably Google for ‘leak free closures’. Thomas Fuchs took over and explained some of the animation scripting going on in scripty2 and showcased his lightweight animation library emile.js.

Next presentation was by Nicolle Sullivan and the title ‘Object Oriented CSS’ made me quite curious. Rightly so cause I really enjoyed this presentation. OOP concepts like code reuse, encapsulation, singletons and inheritance were put into the perspective of organizing CSS. Quite a different approach really but it addresses problems I think a lot off css-coders can relate to. I found it interesting to realize that OOP thinking, which for me is day-to-day practice when working with PHP, somehow hadn’t made it to my CSS approach. At least not to the extent as shown in this presentation.

The day concluded with Dion Almaer and Ben Galbraith talking about ‘The Future of Web Applications’. Very entertaining presentation covering new technologies like Google Closure Tools (Quoting: ‘If you want to write code that looks like java then it’s a great tool for you’), canvas, web workers and webGL.

Conclusion: Very nice conference with indeed a stellar line-up. As always the hallway sessions are not to be underestimated as I usually (unless I’m tired or need to get things done) find it interesting to talk to other people and pick up some new ideas or approaches. To conclude with the closing presentation’s very fitting last commandments (yes, I wrote those down):

• Thou shalt make thine interfaces responsive
• Thou shalt keep the data of thy users holy

• Twitter: #fronteers09
• Flickr: fronteers09

Presentations

Just to show that YQL literally is ‘querying the web’: The YQL below extracts from the Fronteers 2009 presentations page those elements in the list that have a link. And… it always returns valid xml which makes it ideal for parsing the HTML cruft generated by some applications.

SELECT * FROM html 
WHERE url="http://fronteers.nl/blog/2009/11/presentations-fronteers-2009" 
AND xpath="//ol/li/p/a/ancestor::li"

• What Exceptions can I expect?
• What Exceptions do I plan to catch?

In this post I’ll show some important aspects to consider when planning exceptions.

The Basic Exception

Let’s assume a Soap-based web-service client class used to submit order-data to a supplier’s web-service. The web-service client throws an exception if required configuration parameters are missing. The actual SoapClient object will be initialized when the first webservice method is called.

Web-service client class:

class WsSoapClient
{
    private $config;
    private $soapClient = null;
 
    public function __construct($config) {
        $this->config = $config;
    }
 
    public function submitOrder(Order $order) {
        $this->initSoapClient();
        $this->soapClient->submitOrder($order->toSoapParam());
    }
 
    private function initSoapClient() {
        if (!is_null($this->soapClient)) {
            return;
        }
        if (!$this->config->wsdl) {
            throw new Exception('Configuration error');
        }
        $this->soapClient = new SoapClient($this->config->wsdl);
    }
}

Application code:

$config = Registry::get('config');
$client = new WsSoapClient($config);
try {
    $client->submitOrder($order);
} catch (Exception $e) {
    // We need to act on this asap...
    $AppError->register_error($e);
    // Redirect to application error page
    $Redirect->error($e);
}

In case of a configuration error a redirect is performed to an application-error page. And (just an example) some mechanism is triggered that starts to bug a (or all) developers that there’s a problem that needs immediate attention.

Knowing what to catch

There are of course errors that are less disastrous. Web-services can be down so we need to cope with that, resulting in the modifications below:

class WsSoapClientException extends Exception {}
class WsSoapClientConfigurationException extends WsSoapClientException{}
class WsSoapClientConnectionException extends WsSoapClientException{}
 
class WsSoapClient
{
    // ...
    private function initSoapClient() {
        if (!is_null($this->soapClient)) {
            return;
        }
        if (!$this->config->wsdl) {
            throw new WsSoapClientConfigurationException(
                'Configuration error'
            );
        }
        try {
            $this->soapClient = new SoapClient(
                $this->config->wsdl, 
                array('exceptions'=>1)
            );
        } catch (SoapFault $e) {
            throw new WsSoapClientConnectionException(
                'Cannot load WSDL: '.$this->config->wsdl
            );
        }
    }
}

$client = new WsSoapClient($config);
try {
    $client->submitOrder($order);
} catch (WsSoapClientConnectionException $e) {
    // store the order in a queue to be processed later
    $Order->queue();
    $Redirect->Page('OrderQueued', $order);
} catch (Exception $e) {
    // Catch everything, also WsSoapClientConfigurationException
 
    // We need to act on this asap...
    $AppError->register_error($e);
    // Redirect to application error page
    $Redirect->error($e);
}

Two things have changed:

Extending exception types

Exception classes have been defined for specific errors. They both extend an Exception class that is specific for the WsSoapClient class. This allows us to catch specific exceptions, like is done with WsSoapClientConnectionException. We could also catch all exceptions directly thrown by WsSoapClient by catching WsSoapClientException. When defining exception types one might take SPL Exceptions as a starting point.

Rethrowing exceptions

A SoapFault exception is caught and a WsSoapClientConnectionException is thrown instead. Now one might wonder: Why? Couldn’t I just as well catch SoapFault in the application code? That brings us to the next section.

Knowing what to expect

In the previous example we simply used one WsSoapClient class to handle all web-service related communications. Now imagine that we have different suppliers that (inevitably) offer different types of web-services for us to use. Besides a client that handles Soap we now also need a client that handles XML-RPC.

After reading up a bit on Design Patterns we decide to introduce a Factory that returns the proper web-service client for the order, which we supply in the method call.

class WsClientFactory
{
    static public function getWsClient(Order $order)
    {
        switch ($order->supplier) {
            case 'supplierA':
                return new WsSoapClient(
                    Registry::get('config')->soap->supplierA
                );
            case 'supplierB':
                return new WsXmlRpcClient(
                    Registry::get('config')->xmlrpc->supplierB
                );
        }
    }
}

Briefly put: The point of a factory is to avoid the ‘new’ keyword by allowing it to return various class instances. To know what callable methods to expect on the returned object, the possible object types need to implement a common interface or extend a common (abstract) class. We define an interface WsClient and let the two client types implement it:

interface WsClient
{
    public function submitOrder(Order $order);
}
class WsSoapClient implements WsClient
{
    public function submitOrder(Order $order)
    {
        // submitting order to soap webservice
    }
}
class WsXmlRpcClient implements WsClient
{
    public function submitOrder(Order $order)
    {
        // submitting order to xml-rpc webservice
    }
}

Now if we take a look at our original application code it becomes obvious that we are not finished yet.

$client = WsClientFactory($order);
try {
    $client->submitOrder($order);
} catch (WsSoapClientConnectionException $e) {
    // Now what if there's a XML-RPC client throwing other exceptions?
}

We could catch WsXmlRpcClientConnectException as well but that’s not the way to go for two obvious reasons:

1. We would be duplicating the code in the catch blocks
2. If later we need to add a WsEmailClient class, we would need to update both the factory and all the try-catch blocks in the application.

Abstracting exceptions

As the client types implement a common interface we can also define a set of exceptions that are thrown by all classes implementing that interface:

class WsClientException extends Exception {}
class WsClientConfigurationException extends WsClientException{}
class WsClientConnectionException extends WsClientException{}
 
interface WsClient
{
    public function submitOrder(Order $order);
}

The classes implementing WsClient:

class WsSoapClient implements WsClient
{
    public function submitOrder(Order $order) {
        $this->initSoapClient();
        // ...
    }
 
    private function initSoapClient() {
        // Might throw: WsClientConfigurationException
        // Might throw: WsClientConnectionException
    }
}
class WsXmlRpcClient implements WsClient
{
    public function submitOrder(Order $order)
    {
        $this->initXmlRpcClient();
        // ...
    }
 
    private function initXmlRpcClient() {
        // Might throw: WsClientConfigurationException
        // Might throw: WsClientConnectionException
    }
}

The application code retrieving an object from the factory now knows what exception types to expect:

$client = WsClientFactory($order);
try {
    $client->submitOrder($order);
} catch (WsClientConnectionException $e) {
    // Now we know what to expect
} catch (Exception $e) {
}

Wrapping it up

What the above shows is that:

• Throwing a default ‘Exception’ is bad practice if you ever want to act on that specific error scenario. Without extending the Exception class you can only catch all or none.
• New exceptions can be thrown in catch blocks. That way it’s possible to prevent unexpected exception types to cross certain application design boundaries.
• Once class design involves abstract classes or interfaces it is wise to design exception structures as well and organize them in similar layers of abstraction.

Using above ‘rules of thumb’ will hopefully help in using exceptions to maximum effect. The above mainly covers the structure of exceptions and not so much functionally that can be added to an exception subclass. Ideas to consider:

• Adding listeners to an Exception that might write exceptions to a log. Beware though: There’s probably no need to log ‘expected exceptions’ and every disk-write is a small hit on performance.
• Adding the caught exception to the new exception that is being re-thrown.

Do you think I’ve left out important parts or are you using (entirely) different exception strategies? Feel free to comment.

To help during development (or design) it helps to keep in mind that a user using an application is all about interaction and exchanging information. At any given moment while using an application, a user might wonder things like:

• What did that button do?
• What will this button do?
• What does this label mean?
• How can I find the page I’m looking for?

Summarized: action and information, past and future as illustrated below:

Usability: Application State Diagram

Four quadrants

I. Past actions

This translates to ‘feedback’. Is it at any point clear to the user what the application is doing or has done, following the user’s commands? Is the feedback form sent? Are modifications done through the CMS visible online? Is the application really still busy or is something going wrong?

II. Future actions

Feed forward. For a user to ‘trust’ an application he needs to be able to predict what will happen when he performs certain actions. Take for instance a webshop: After clicking ‘place order’, will there be a screen to review and possibly cancel the order process? Or, after saving a page in a CMS, will it be possible to preview a page before it’s visible on the live site?

III. Past information

This focuses mainly on how information is displayed at a given point. Is important information clearly recognizable? Is it clear what is displayed? For example a product page on a webshop: Can editorials and user comments be clearly distinguished?

IV. Future information

This covers navigation and thereby how all the information and possible interaction of an application is structured. To efficiently use an application a user needs to be able to predict where to find information and how to get there. This involves structuring navigation and perhaps also tailoring navigation to accommodate for common usage scenarios.

What this diagram does not

The above diagram focuses on the state of an application at a given point and therefore doesn’t look at the bigger picture. This means it doesn’t:

• Cover consistency throughout the application.
• Prioritize functionality.
• Match functionality with user goals.
• Look into characteristics of the targetted users (like experience with similar applications) or the environment the application is used in.

What this diagram can do

Taking back a step once in a while during development and applying this diagram on the application that is being created, can help to quickly point out certain usability flaws. This is especially true when there is no dedicated usability expert in the team. Having a certain amount of knowledge of the more elaborate checklists mentioned earlier will help. Besides being used as a quick evaluation tool this diagram can also be used to structure usability-related thoughts and ideas and predict their effectiveness. Hopefully that will help creating a better user experience.