Lose pounds of excess code in 1 easy step!

Slim controllers are easier to test, encourage the DRY principle and force business logic back into the model layer where it belongs.

In this first article, I’ll be looking at a quick way to de-bloat Zend Framework Action Controllers by using an Action Helper to automatically instatiate models and assign them to properties in the controller and view.

Lather, Rinse, Repeat

Controller actions often perform mundane, repetitive tasks. Checking for required parameters, creating objects and assigning variables (again and again) eats up line after line of code in a typical controller.

Using the address book example, a simple action in our Contact controller might look something like this:

class ContactController extends Zend_Controller_Action
{
    public function viewAction()
    {
	// check that we have a contact ID, otherwise redirect to index
	if ( !$this->_hasParam( 'id' ) || !Contact::exists( $this->_getParam( 'id' ) ) ) {
	    $this->_helper->FlashMessenger( 'No contact specified or contact does not exist.' );
	    $this->_redirect( 'contact' );
	}
	// lookup and instantiate the contact object
	$contact = Contact::find( $this->_getParam( 'id' ) );
 
	// assign contact to view
	$this->view->contact = $contact;
    }
}

A few things are happening here:

1. First, we check to see if the ‘id’ param exists in the request.
2. Then we use our model’s static exists() method to check that the contact ID corresponds to a real contact.
3. The contact object is then looked up using a static finder method.
4. …and finally we assign the contact to the view.

The exact code will vary depending on your model implementation, but this sort of process is pretty typical in my experience. In many actions, that’s all that’s required: the view then does its thing on the contact object that it’s been given.

Pretty boring stuff and chances are some or all of the above will be repeated in a handful of other actions in the same controller. That’s a “code smell” if ever I smelled one.

By automating these repetitive operations, there’s an opportunity to substantially reduce the size of our controllers without losing any functionality.

The Action Helper

Fortunately, Zend Framework has the perfect tool for this kind of job: an Action Helper.

By tapping into the preDispatch() hook provided and making a few basic assumptions, we can look for models specified in the request, instantiate them and then assign them to properties in both the action controller and the view.

Here’s the basic action helper class, which I’ve called “ModelWatcher”:

<?php
 
class Dog_Zend_Controller_Action_Helper_ModelWatcher extends Zend_Controller_Action_Helper_Abstract
{
    /**
     * @var string
     */
    protected $_controllerName;
 
    /**
     * @return void
     */
    public function preDispatch()
    {
	$request = $this->getRequest();
	$this->_controllerName = $request->getControllerName();
	$this->_view = $this->_actionController->view;
 
	try {
	    $model = $this->_getModel();
 
	    // assign to the controller and view
	    $this->_actionController->{$this->_controllerName} = $model;
	    $this->_view->{$this->_controllerName} = $model;
 
	} catch ( Exception $e ) {
	    return;
	}
    }
 
    /**
     * @return object The instantiated model object
     */
    protected function _getModel()
    {
	$request = $this->getRequest();
 
	if ( NULL === $request->getParam( 'id' ) ) {
	    throw new Exception( "ID parameter not found in request" );
	}
	$id = $request->getParam( 'id' );
 
	// attempt to find and instantiate the model object
	$modelClass = ucfirst( $this->_controllerName );
	$model = $modelClass::find( $id );
 
	return $model;
    }
}

Important: Don’t forget that you’ll need to add the helper to your bootstrap for this to work. Something like this should do the trick:

Zend_Controller_Action_HelperBroker::addHelper( new Dog_Zend_Controller_Action_Helper_ModelWatcher() );

When the helper’s preDispatch() method is called, it checks the request for the “id” parameter and attempts to find and create the model object. In the case of our address book, a request URL like http://www.example.com/contact/id/123 would try to retrieve an object of the class Contact whose ID is 123.

We wrap the call to _getModel() in a try…catch block to deal with two scenarios:

1. When no ID parameter exists in the request or
2. No record exists for the given ID

The latter assumes that the find() method will throw an exception if the record is not found.

If the lookup is successful, the newly created object is assigned to the controller and view with a property named after the controller. So with our address book example, you’d access the contact object using $this->contact from within both the controller and the view.

On failure, we do nothing – leaving the action controller to implement its own logic for dealing with non-existent objects.

The Final Weigh-In

All this means we’re left with a significantly slimmer controller action:

class ContactController extends Zend_Controller_Action
{
    public function viewAction()
    {
	// check that we have a contact object
	if ( !isset( $this->contact ) ) {
	    $this->_helper->FlashMessenger( 'No contact specified or contact does not exist.' );
	    $this->_redirect( 'contact' );
	}
    }
}

The controller action now only needs to check that a contact object has been created by the action helper. There’s no need for it to get its hands dirty with the request params, object generation or assigning variables to the view as it’s already been done.

This approach does require an adherence to some naming conventions… primarily that the model class name has to mirror the controller name and the identifying parameter is always passed as “id” in the URL. Provided they aren’t too wacky, it should be reasonably easy to re-jig the code to suit any conventions of your own.

Further Weight Loss

A slightly more flexible approach is to use verbose ID parameters like “contact-id”. This gives you the ability to have model classes which don’t match the controller name and also allows multiple models to be instantiated by the ModelWatcher in one request, both of which can be useful. I use something similar in my own implementation.

You might also want to consider adding other logic in to the ModelWatcher helper like record locking or fine-grained access control. Even if you decide to separate these activities into a separate helper class, you can still use the models inserted into the controller rather than going back to the request parameters again. Just make sure that the ModelWatcher is added to the action helper plugin stack before any helper that relies on it or the models it creates.

Final Thoughts

Hopefully it should be fairly clear that this simple action helper has the potential to dramatically reduce the amount of boiler plate code in your controllers. Eagle-eyed readers might also have noticed that automatically assigning models to the controller is a feature of CakePHP.

Look out for future posts where I’ll be discussing more ways to de-clutter and cut down your controllers.

P.S. Thanks to Rob Allen, Matthew Weier O’Phinney, Pádraic Brady, Wenbert Del Rosario and others for retweeting/linking to my first post

This article discusses how to extend Zend_Db_Adapter to give the illusion of nested transactions – a handy workaround for use in object oriented applications. Although I focus on MySQL, it should be possible to apply these concepts to any other database flavour which supports transactions. There are some limitations to this approach, but I’ve found it to be very useful in practice.

A Brief Introduction to Transactions

You can’t work with database backed web apps for very long without coming across the concept of database transactions.

Transactions (http://en.wikipedia.org/wiki/Database_transaction) are a way of encapsulating a group of database queries, typically INSERT and UPDATE statements, so that they all must complete successfully in order for the changes to be written (“committed”) to the database. If any single query fails, any changes to the database can be “rolled back” to how they were when the transaction began.

This has great practical value. Many operations consist of several steps where the changes should only be applied if every step is successful. The classic example is transferring funds between two bank accounts, which is a three stage process:

1. Checking that the sender’s account has a balance greater than the amount to be transferred.
2. Subtracting that amount from the sender’s account
3. And, finally, adding it to the recipient’s account.

The SQL for this transaction might go something like:

START TRANSACTION;
SELECT balance FROM account WHERE account_number = 123456789;
UPDATE account SET balance = balance - 100.00 WHERE account_number = 123456789;
UPDATE account SET balance = balance + 100.00 WHERE account_number = 987654321;
COMMIT;

If an error is thrown at any point in the process, the ROLLBACK statement can be used to revert the database to its state before the transaction began.

In an application that doesn’t use transactions, a typical approach might be to check the return value of each query or enclose it in a try…catch block:

try {
    $balance = $db->fetchOne( "SELECT `balance` FROM `account` WHERE `account_number` = 123456789" );
    $db->update( 'account', array( 'balance' => new Zend_Db_Expr( "`balance` + 100" ) ), "`account_number` = 123456789" );
    $db->update( 'account', array( 'balance' => new Zend_Db_Expr( "`balance` - 100" ) ), "`account_number` = 987654321" );
} catch ( Zend_Db_Exception $e ) {
    echo $e->getMessage();
}

The problem with this approach is that although we know the operation failed, we don’t know when it failed. Perhaps the first update statement was executed, but the second one wasn’t. Perhaps the database connection was lost before we even started. The end result is that we may have introduced inconsistencies into our data that, even with this simple example, are going to be hard to track down and correct.

Using transactions we can ensure that each step is carried out successfully or the whole operation fails.

try {
    $db->beginTransaction();
    $balance = $db->fetchOne( "SELECT `balance` FROM `account` WHERE `account_number` = 123456789" );
    $db->update( 'account', array( 'balance' => new Zend_Db_Expr( "`balance` + 100" ) ), "`account_number` = 123456789" );
    $db->update( 'account', array( 'balance' => new Zend_Db_Expr( "`balance` - 100" ) ), "`account_number` = 987654321" );
    $db->commit();
} catch ( Zend_Db_Exception $e ) {
    $db->rollBack();
    throw $e;
}

By calling the beginTransaction() method, we temporarily delay any actual modifications to the database. If each query is successful, the changes are committed using the commit() method. But if an exception is thrown, the changes are reverted using rollback().

The Problem

Although transactions are a useful tool, sadly they don’t always fit well into an object oriented application.

It’s common to delegate the actual persistence (inserting and updating) of models to a save method which, in turn, goes on to save child objects. Say we have a simple address book application which allows you to enter multiple notes for each contact. The save method for the Contact model might look something like this:

public function save()
{
    $db = $this->_db;
 
    try {
	$db->beginTransaction();
	if ( !$this->hasId() ) {
	    // new model
	    $db->insert( 'contact', $this->getData() );
	} else {
	    // existing model
	    $db->update( 'contact', $this->getData(), $db->quoteInto( '`id` = ?', $this->getId() ) );
	}
	// save the contact's note
	foreach ( $this->getNotes() as $note ) {
	    $note->save();
	}
	$db->commit();
    } catch ( Zend_Db_Exception $e ) {
	$db->rollBack();
         throw $e;
    }
}

The save method for the Note class is similar, starting a transaction and saving the individual note.

Herein lies the problem: attempting to start an new transaction implicitly commits the current transaction (http://dev.mysql.com/doc/refman/5.0/en/implicit-commit.html). Without ugly hacks which tie the models directly to the database operations, it becomes difficult to establish which object started the transaction and when it should be committed.

The Solution

Disclaimer: This solution is adapted from the extended Pdo_MySql adapter in Varien’s Magento e-commerce product. A similar approach is adopted by Bryce Lohr’s Nested Table Support for Zend_Db proposal. You should read Bill Karwin’s comments about that proposal and understand the limitations of this method before implementing it. That said, I still believe this is a useful and practical way of simulating nested transactions and I have used it a number of times.

A simple solution to the problem is to keep track of the “depth” of the transaction, that is, how many times the beginTransaction() method has been called. That way, we can hold off committing the changes to the database until we are certain that all the save operations have completed successfully.

Since transactions apply to the whole database connection, the most logical place to manage this process is in the DB adapter class. To do this, we extend our adapter class like so:

class App_Zend_Db_Adapter_Mysqli extends Zend_Db_Adapter_Mysqli
{
    /**
     * Current Transaction Level
     *
     * @var int
     */
    protected $_transactionLevel = 0;
 
    /**
     * Begin new DB transaction for connection
     *
     * @return App_Zend_Db_Adapter_Mysqli
     */
    public function beginTransaction()
    {
        if ( $this->_transactionLevel === 0 ) {
            parent::beginTransaction();
        }
        $this->_transactionLevel++;
 
	return $this;
    }
 
    /**
     * Commit DB transaction
     *
     * @return App_Zend_Db_Adapter_Mysqli
     */
    public function commit()
    {
        if ( $this->_transactionLevel === 1 ) {
            parent::commit();
        }
        $this->_transactionLevel--;
 
        return $this;
    }
 
    /**
     * Rollback DB transaction
     *
     * @return App_Zend_Db_Adapter_Mysqli
     */
    public function rollback()
    {
        if ( $this->_transactionLevel === 1 ) {
            parent::rollback();
        }
        $this->_transactionLevel--;
 
        return $this;
    }
 
    /**
     * Get adapter transaction level state. Return 0 if all transactions are complete
     *
     * @return int
     */
    public function getTransactionLevel()
    {
        return $this->_transactionLevel;
    }
}

Update your bootstrap to use the extended class et voila – a single START TRANSACTION and COMMIT or ROLLBACK is sent to MySQL, regardless of how many levels of nested pseudo-transactions have been created.

Please Note:

• It’s important that each child save() method re-throws the exception so that transaction depth is reduced by successive calls to rollBack(). The end result is that the originally called save() method then performs the actual rollback.
• All the tables used in the transaction must use a storage engine that supports transactions. For MySQL, this will most likely mean using InnoDB. To convert a MyISAM or other table type to InnoDB, use “ALTER TABLE table ENGINE = InnoDB”. It could take some time to rebuild the indexes on large tables. There are other considerations about the use of InnoDB – please consult the MySQL manual.
• If the tables used don’t support transactions, it’ll just fail silently. Bad times. I highly recommend using Firebug and Zend_Db_Profiler to monitor database queries during development (see http://framework.zend.com/manual/en/zend.db.profiler.html);

I hope you find the above useful – if so, please leave a comment. If not, please be gentle… it’s my first blog post!

Gratuitous and unnecessary dog picture (Pic: Steven Jack)

To be honest, I’m a bit ashamed.

I’ve been working with web development and internet marketing for almost half a decade and only now, in 2010 for Christ’s sake, have I got round to starting a blog.

There are plenty of excuses: haven’t had the time, I thought it might be tricky to set up, didn’t need another codebase to get to grips with. But frankly, they’re all pretty pathetic.

As it happens, I’ve been amazed by just how easy it’s been to set up a WordPress blog. I bought this snazzy, clean theme and had it all up and running on my Windows dev server in about 5 mins. Transferring it to my cluster took a little more effort, but the whole thing has only taken a few hours, and most of that was browsing through different themes.

Anyway, I’m here now, so let’s look to the future.

The plan is to blog about the trickier issues that I come across working as a web developer. So you can mainly expect stuff relating to PHP, MySQL and Zend Framework. I wouldn’t be at all surprised if there ends up being a smattering of Apache, jQuery and server admin posts too.

The inspiration, if you can call it that, is a pretty selfish one. I’ve recently been working on Entertainment Manager, an “enterprise-level” business management tool for Entertainment Agencies (which I’ll blog about at a later date). Inevitably, I’ve stumbled into a few issues where it’s been tough to find any real solutions online.  It may be because PHP is a relative new comer as an ”enterprise” (I hate that term) language, or just because some of the terminology gets a bit vague when dealing with more complex problems.

In any case, the aim of this blog is to document these thorny problems and their solutions so that I have something to refer to in the future when I’ve forgotten all the details (like next week… OK, tomorrow). It’d be a massive bonus if other people could benefit from my experience and save themselves a few hours of head scratching in the process.

There’s a real danger that I won’t post often enough and that the quality of the content may be, um, variable. But, hey, it’s taken me five years to get to this point, so give me a break, eh?

There are a handful of issues on the to-blog list at the moment:

• Nested transactions using Zend_Db (done)
• Plugin functionality for models
• Practical Model/Resource (i.e. DB) separation
• “Real” modular bootstrapping with Zend_Application
• How to make your models fatter and your controllers thinner (Part One)

Hopefully I’ll come up with something of interest so you’ll be back soon.

Steve