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.

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.

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

• 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.

One of the challenges we were facing was that on one hand we wanted to implement business rules in our Domain objects. In plainish english: On setting or changing properties of the object (like changing a status) we want to validate if that action is allowed. On the other hand we want to be able to initialize an object to whatever state corresponds with the data fetched from the persistency layer. Doing so we found that the business rules got in the way during initialization when fetching it from the persistency layer. So what we were looking for was a way to allow the service layer to construct a Domain object using methods that are hidden from the rest of the code. We found two ways:

1. Reflection (as of PHP 5.3)
2. A design pattern where the Domain object initializes itself using the provided Service object.

Das Model: DAO, Domain, Service and Persistency layer

First lets look at how such a Domain object might look like. See simplified example below of an ‘order’:

class Domain_Order
{
    protected $id;
    protected $orderDate;
    protected $articles;
    protected $customer;
    protected $invoices;
    protected $statusHistory;
 
    public function getArticles() {}
 
    public function setStatus(OrderStatus $status) {}
 
    // other getters and setters
}

The order has properties like it’s id, a list of articles, the customer that placed the order and the invoice(s) sent. Besides that it has a status history that actually is a stack of subsequent statuses that correspond to the business processes involved. Possible statuses could be:

• initiated
• confirmed
• payment_confirmed
• articles_deliverable
• shipped
• onhold_system_error
• resolved_system_error
• onhold_helpdesk
• resolved_helpdesk
• cancelled_helpdesk
• completed

Domain objects are fetched, stored and updated by using methods on Service objects. Those service objects implement the aforementioned ‘persistency layer’ (could be PDO, webservices, memory, files, etc.). Services are retrieved from a DAO instance that is fetched from a DAO registry. I’ll cover that more thoroughly in a later post so I’ll keep it brief:

Bootstrap:

// bootstrap. setup DAO registry  with 
// DAO instance that provides service objects
DAO_Factory->setInstance(
	new DAO_PDO($initialisedPdo)
);

Fetching an order by id:

// returns concrete DAO, in this case using PDO for persistency
$order = DAO_Registry->getInstance() 
	// the DAO instance returns an 'order' service instance
	->getServiceOrder()
	// the service instance provides methods for CRUD type operations
	->getById($reqOrderId);

Implementing logic

Now let’s illustrate the concept of putting business rules in the Domain object: If a customer contacts the helpdesk with a difficult question, the helpdesk can put the order on hold to prevent shipping. The status ‘onhold_helpdesk’ is added to the status history. But (in our imaginary shop) this can’t be done if the order is already shipped. So the setStatus() method will validate if the status given is actually allowed and only then perform the action.

The setStatus() method in the order class now looks like this:

class Domain_Order
{
    // ... properties and other methods
    public function setStatus(OrderStatus $status)
    {
		// determine if new status is allowed business-wise
		if ($newStatusAllowed) {
			array_push($this->statusHistory, $status);
		} else {
			throw new Domain_Order_InvalidStatus_Exception();
		}
    }
    // ... other methods
}

Calling the setStatus() method should handle the possible exception:

try {
	$order->setStatus(
		new OrderStatus('onhold_helpdesk');
	);
} catch (Domain_Order_InvalidStatus_Exception $e) {
	//  properly handle exception
}

No public access allowed

To continue the example: If an order is already shipped it can’t be put on hold. But (at least in this imaginary shop) the other way round goes too: If an order is ‘on hold’ the status ‘shipped’ can’t be added. The issue has to be resolved first. From a given state this behaviour is good: invalid actions are prevented. The problem is that the public setters like setStatus() are not suitable for bringing a newly created domain object into it’s ‘persisted’ state. A possible solution might be to add methods that bypass the business logic, but as these methods are used by the service object they need to be public. This is not desired as it allows developers to cut corners that shouldn’t be cut.

So, back to the start of this post: How to set properties bypassing business-logic?

1 . ReflectionProperty (PHP 5.3)

As of PHP 5.3 the ReflectionProperty class of the reflection API has a method setAccessible() that allows access to protected and protected properties. Accessing the protected id property of the Order class would look like this:

class Service
{
    // ...
 
    public function getById($id)
    {
        // based on the id from the persistency layer 
        // data is retreived. In this demo the data is a hash. 
        // Now it needs to be put into the newly created 
        // Order that is returned.
        $order = new Order();
 
        $refId = new  ReflectionProperty('Order');
        $refId->setAccessible(true);
        $refId->setValue($order, $persistedData['id']);
 
        // ... set other properties
 
        return $order;
    }
 
    // ...
}

The major drawback of using this technique is that the Service class needs to be aware of the internals of the Order class. So, updating the Order class involves needing to update the Service class as well. This breaks basic concepts of OOP. (For a more useful example of reflectionProperty see this object freezer example by Sebastian Bergmann.

2. Protected Link Pattern?

Another way to bypass business-logic on creation without exposing that possibility is to create what could be called a ‘protected link’ between the Service and the Order object. See code below:

Service:

class Service_Order
{
    // ...
 
    public function getById($id)
    {
        return Order::_init($this,$id);
    }
 
    public function _getInitData(Domain_Order $order, $id)
    {
        // will return 'raw' data (hash/object) as
        // retrieved from the persistency layer
        return $data;
    }
 
    // ...
}

Domain:

class Domain_Order
{
    // ... 
    private __construct()
    {
        // no, no, go to the Service
    }
 
    public static function _init(Service_Order $service, $id)
    {
        // create brand new instance
        $order = new Domain_Order();
 
        // fetch persisted data
        $initData = $service->_getInitData($order,$id);
 
        // bring order in it's initial state
        $order->id = $initData['id'];
        $order->orderDate = $initData['orderDate'];
 
        // etc...
 
        return $order;
    }
 
 
    // ... 
}

A static _init() method, that has access to the Order’s protected properties, is provided with a Service instance and the id of the Order to be initialized. The static Order method then in turn fetches the data from the Service. The new Order instance is then put into the persisted state by directly setting attributes otherwise not accessible. The initialized instance is then returned to the Service which in turn returns it to the requesting code.

On a first glance this might look more complicated than needed: Instead of using a _getInitData() from the Order class we could also have provided the _init() method with a data object that implements a certain interface. But this leaves open the option to initialize an Order object with manipulated data that is not directly derived from the persistency layer.

What this does achieve is that it is now impossible to manipulate a Domain object bypassing methods that apply business logic. Yet at the same time that business logic doesn’t get in the way when initializing a Domain object from the Service layer. A benefit compared to the reflection solution is that the Service object doesn’t need to be aware of the Order’s internals. The existence of the Domain layer’s _init() and the Service layer’s _getInitData() methods are enforced by their respective interfaces or the abstract classes they extend. The design of the transported data (in these examples a hash) can of course also be limited to a certain object type.

A drawback is that there is now a public method _getInitData on the Service layer. In this example the impact thereof is reduced by requiring an instance of Domain_Order but that’s just sugar (or vinegar so you like): It’s just an indication for developers that they are on the wrong track when they are directly calling _getInitData().

As said, in later posts I plan to elaborate more on the Service and Persistency layers that are briefly shown here. If anyone knows of other ways to address the issue of ‘controlled initialization’ I’m of course very interested.

class User
{
    protected $userId;
    protected $email;
    protected $admin;
 
    public function setUserId(UserId $userId) {}
 
    public function setEmail(Email $email) {}
 
        // this should only accept a boolean
    public function setAdmin($isAdmin) 
    {
        if (!is_bool($isAdmin)) {
            throw new ValueTypeException(
                'Wrong parameter for ' . __METHOD__
            );
        }
        $this->admin = $isAdmin;
    }
}

Here being able to enforce the boolean parameter would be nice and more consequent with the other methods.

The Email value object has it’s own validation and could look like this:

class Email
{
    private $value;
 
    public __construct($value)
    {
        if (!preg_match('/^.+\@.+\..+$/',$value) {
            throw new ScalarValueException(
                'Invalid value for type Email'
            );
        }
        $this->value = $value;
    }
 
    public function __toString()
    {
        return $this->value;
    }
}

Now let’s look at how a PHP6 UserId object might look like:

class UserId
{
    private $value;
 
    public __construct($value)
    {
        $isValid = true;
        if (!is_int($value) ||
            !$this->exists($value) ||
            $value <=0
        ) {
            throw new ScalarValueException(
                'Invalid value for type UserId'
            );
        }
 
        $this->value = (int) $value;
    }
 
    // Warning: uses PHP6 proposed features
    public function __cast($type)
    {
        if ($type == 'int') {
            // return integer value
            return $this->value;
        }
        if ($type == 'boolean') {
            // return true as UserId can only 
            // exist with a valid value
            return true;
        }
        throw new SkalarInvalidCastException(
            'Object of type UserId cannot be cast to '.$type
        );
    }
 
    private function exists($value)
    {
        // method that checks if a user with given id exists
    }
}

As can be seen the __cast() method assumably (it’s just a proposed feature) accepts a $type parameter. That raises the question if it wouldn’t be better to add __toInteger(), __toFloat() and __toBoolean() methods instead. That seems more consequent with the __toString() method that’s allready widely used.

The C#-style properties with getters and setters might be nice too, although imho it doesn’t really add much to the allready existing __set() and __get() methods. I would prefer to see ‘strongly typed’ properties instead:

class User
{
    // PHP6 wishlist: strong typed properties
    protected UserId $userId;
    protected Email $email;
    protected boolean $admin;
 
    // etc...
}

I’m really looking forward to these kind of additions, especially if such type hinting is kept optional. Then the flexibility of PHP is preserved but it allows for a more robust approach in large projects.

Be explicit. Type strong.

Screen resolution

Take the february 2009 stats of thecounter.com. Based on those stats a target resolution of 1024 seems reasonable: At least 78% of the people view websites at that resolution or higher.

Of course the need for the increased width depends on the specific elements that have to be displayed. When left- and right columns are narrow, a width of 1024 might lead to very long lines which are hard to read.

Accessibility guideline: text size

Accessibility guidelines (W3C WCAG 1.0 point 3.4) state that relative units are to be used when specifying text size. That way, users can easily adjust the size of text. For some time, browsers (except *sigh* IE6) allowed users to adjust the displayed text size by using key combinations or ctrl+scrollwheel. This posed a challenge to CSS coding as it wasn’t always easy to keep everything in place when text size was increased. Or, probably worse, text would flow out of the box and become unreadable. See below image of a page on eurogamer.net. In the left-column navigation and bottom parts of the page elements will overlap when text size is increased.

Eurogamer text size example

Nowadays quite some web browsers have replaced text scaling with page zooming. This definitely makes life easier for CSS coders. It will also help user experience when increasing text size because relative placement of elements is preserved, as opposed to situations where some columns are stretched in different amounts. But there is a side-effect.

The misinterpretation of statistics and its disastrous consequences

When a website already fills the entire viewport in it’s original size, as soon as display size is increased, horizontal scroll bars will appear and the rightmost content will move out of view. So now let’s turn the aforementioned stats around. At least 51% of the visitors have a screen resolution of 1024 or less. So basically this means that when a page is designed to have a minimum width of, say, 1000px, half of the visitors will have problems increasing the displayed size.

Although official accessibility standards don’t seem to mention horizontal scrolling, it’s safe to say that having to scroll horizontally doesn’t help accessibility. And from a usability perspective it’s most certainly bad practice.

Regarding accessibility standards not mentioning horizontal scrolling: I searched the standards document of the dutch government which includes all WCAG guidelines (and more). I searched for the words screen (dutch: scherm), horizontal (dutch: horiz) and scroll. Nothing. A downside of these kind of checklists: technology moves on continuously while standards only get update once every x years. But that’s a different subject…

Browser overview: Text scaling or Full page zooming?

Acknowledging this side-effect it’s good to know exactly how today’s browsers perform zooming. See the table below.

Browser zoom characteristics

Conclusion

Although stats suggest 1024 is a solid choice, it’s obvious that there are considerations to be taken into account. If liquid design with a minimum of 800px is not an option and one chooses to design for a (minimum) resolution of 1024px the least one can do is try to avoid putting essential navigation or use cues in the rightmost part of the site.

See image below of Play.com: The top part with the currency selectors and link to the visitor’s account-page do sticks to the right size of the screen.

In this case I think it’s a coincidence as the cart button does extend beyond the visible area. The selectors are positioned absolutely from the right size of a container that doesn’t have it’s css attribute position set to ‘relative’. So positioning is done with respect to the BODY element. Although that has a min-width of 990px it somehow works out this way.

Play.com header example

One last tip: IE7 keeps a centered column centered when zooming in, as opposed to Firefox and Opera. So when in IE7 horizontal scroll bars appear, bits are falling of the left side of the screen as well.

1. There’s the ones that fit well into ‘the CMS mold’: Content is aggregated, put in the right drawer (=stored), perhaps sorted a bit and finally displayed. There are of course requirements but there’s usually a certain flexibility to them. Take for example images: It’s nice if the CMS will resize uploaded images as needed but if not then that is usually not a show-stopper.
2. The one’s where requirements are specific, out of the ordinary, and probably detailed. Some functionality might be provided by a traditional CMS, but there’s a lot more. Future requirements are undetermined but might be very diverse.

Confection clothing vs. tailor made suits really. The project discussed clearly matched the second description.

Thousands of Drupal modules must be right. Wrong!

For the first type of project it is obvious that applications like Drupal, Joomla! and WordPress are unbeatable. If that does the job well enough there’s no point in coding yourself. Besides that, the community will provide you with free upgrades and enhanced functionallity as updates are released!

The second type of project is different though. What I believe went wrong in the case discussed, was that right at the start of the project the assumption was made that ‘the needed modules were sure somewhere out there’. Even if they are it may be hard to find them. Some simplified math: 2332 modules (wikipedia). 1 minute to quickly scan a module and take note if interested. 40 working hours a week equaling 2400 minutes. So it takes about a week to make a first inventory. Not entirely true of course but the time you win, you lose again by comparing the nitty gritty details between similar modules.

Module creep

Once the needed modules are found a situation like illustrated below might occur:

Module Creep

The modules found provide most of the functionallity neccessary. And more. Enough to pass whatever requirements check you want to perform. But take for example module E. That’s just there to cover for that little bit of ‘must have’ requirements. And modules B and D provide functionality that’s totally irrelevant. Depending on implementation details, for visitors or editors the user experience will be less focused. More is not always better. Maintenance and implementation might be harder than planned too.

Customization

So the second type of project might lead to the conclusion that customization is required. And that conclusion by itself poses all kinds of new questions, like:

• Does the application architecture allow for customization?
• Can enhancements and original software be kept separate? In other words: what is the quality of the application’s architecture?
• Are the resources (time/money/knowledge/management support) to build custom enhancements available?
• What are the risks of core- or module upgrades causing the custom enhancements to fail?
• What are considerations with respect to licensing?
• How well can risks involved be estimated?

These are questions that should be addressed very early in the project. Finally some aspects to take into consideration when trying to answer these questions:

• Besides looking from a functional point of view, technical details have to be addressed. That expertise has to be (made) available.
• Experience from previous projects or case studies greatly helps answering these questions. That experience is not always there.

Loading configuration data

Basically there are three ways of loading configuration data:

• 1.Using Zend_Config and passing a PHP array as parameter
• 2.Using Zend_Config_Ini to load an ini configuration file
• 3.Using Zend_Config_Xml to load an xml configuration file

$configData = array(
  'somecategory'  => array(
    'somesetting'     => 'somevalue',
  )
);
  // 1. Load array
$config = new Zend_Config($configData);
  // 2. Load ini file
$config = new Zend_Config_Ini('/path/to/config.ini');
  // 3. Load xml file
$config = new Zend_Config_Xml('/path/to/config.xml');

Alternatively, you can specify a file containing an array as require() returns the return value of a PHP script being included:

config.php

<?php
$CONFIG['somecategory']['somesetting'] = 'somevalue';
 
return $CONFIG;

  // 1b Load array
$config = new Zend_Config(require 'path/to/config.php');

Using configuration data

Zend_Config creates a hierachy of Zend_Config instances. So a specific part of the total configuration data can be extracted and passed to a specific component. All subparts behave the same. If the component requires configuration to be passed as an array the toArray() method can be used. Instead of accessing values as properties one can also use the get() method. The advantage of get() is that a default value can be supplied to be used when the requested variable isn’t available.

  // configure an instance using a specific part of the config
$modelComponent = new ModelComponent($config->components->componentName);
  // Or, if the component requires an array
$modelComponent = new ModelComponent($config->components->componentName->toArray());
  // Get an optional config setting, supplying a default value
$someValue = $config->common->get('someValue','myDefaultValue');

The data contained in Zend_Config is read-only which is normally a good thing. In case the configuration data has to be changed this can be overridden by supplying an additional parameter in the constructor. Then after making the neccessary changes the config object can be ‘sealed’ by calling setReadOnly().

  // read config with $allowModifications set to true
$config = new Zend_Config(require 'path/to/config.php',true);
 
  // perhaps change some bits here and there
if ($fullMoonMadness)
{
  $config->site->theme = 'silver';
  $config->blog->allowComments = false;
}
 
  // and prevent accidental modification
$config->setReadOnly();

To make the loaded configuration available throughout the entire application, Zend_Registry is probably the tool of choice.

$config = new Zend_Config(require 'path/to/config.php');
  // and store in registry
Zend_Registry::getInstance()->set('config', $config);

Organizing configuration data

When using ini or xml configuration files, sections can be declared. On loading the file the section to be used can be specified. A section can extend other sections thereby allowing configuration data to have a certain hierarchy.

Ini-file example:

[production]
www_root = www.mysite.com
site.title = "My Website - "
 
[test : production]
www_root = test.mysite.com

The root node of XML files can be named arbitrarily. If you want to use sections the first level in the XML has to correspond to the section requested. There are two reserved attributes: value and extends. Other attributes can hold values that otherwise would be childnodes. See example that holds the same data as the Ini file above:

<?xml version="1.0"?>
<config>
  <production>
	<www_root>www.mysite.com</www_root>
    <site title="My Website - " />
  </production>
  <test extends="production">
   <www_root value="test.mysite.com" />
 </test>
</config>

Now the section-specific configuration can be loaded by specifying a second parameter in the constructor:

$config = new Zend_Config_Xml('/path/to/config.xml','test');

Ini, XML or Array?

As mentioned at the top of this article: There is no ‘only’ way and there is no ‘right’ or ‘wrong’ way. Of course there are aspects that can make you favor one approach over the other, the most notable being:

• Only Ini and XML provide sections, allowing you to use hierarchic configuration data
• Ini and especially XML are better suited for tooling: Software other than PHP can read or modify configuration data.
• When using ini files it is not possible to use quotes in a value.
• PHP arrays have the benefit that you can put program logic in them. For example, you can construct variables based on defaults that are set initially. See example below

$CONFIG['defaults']['fs_root'] = '/var/www/mysite_com/';
// ...
$CONFIG['locations']['libraries']['zf'] = $CONFIG['defaults']['fs_root'].'lib/zf/';
 
return $CONFIG;

2009-05-15: added example of loading specific section by passing section parameter to constructor