var condition = another_condition = true; // For this example to work!

function animate (callback)
{
    c = (typeof(callback) == 'function') ? callback : function () {};

    if (condition) {
        c = function () {
            c();
            console.log('bar');
        };
    }

    if (another_condition) {
        c = function () {
            // More functionality.
            console.log('baz');
            c();
        };
    }

    c();
}

animate(function () { console.log('foo'); });

My intent was to allow a function reference to be passed into animate(), and modify the reference so that additional functionality would be added depending on the evaluation of several conditions.

Assuming that both condition and another_condition evaluated true I had expected the output of the above to be:

baz foo bar

Of course this isn’t what happened. The output was something like:

baz baz baz baz baz baz baz …

…before my browser crashed.

What happened?

What happened was simple, yet it’s cause was an obscurity of Javascript closures; the variable c changed to reference 3 different functions during the course of this code execution. Initially it pointed to the function reference passed into animate, however when condition, and later another_condition evaluated true, c was reassigned once, then again to now be a reference to the later newly created anonymous function.

I was aware than due to the phenomenon that is closures that each newly created function would have full access to c and be able to call the function directly. What I didn’t expect was that this function reference would not be dynamic and not necessarily reference the function that c referenced at the time the function was created.

So when c was called, all it ended up doing was calling itself recursively, repeatedly logging ‘baz’, and eventually overflowing and crashing Firefox.

The Solution

Obviously references to c would need to be stored somewhere for later retrieval. The solution was to store a reference to the current value of c in a local anonymous namespace.

var condition = another_condition = true; // For this example to work!

function animate (callback)
{
    c = (typeof(callback) == 'function') ? callback : function () {};

    if (condition) {
        (function () {
            var oldC = c;
            c = function () {
                oldC();
                console.log('bar');
            };
        })();
    }

    if (another_condition) {
        (function () {
            var oldC = c;
            c = function () {
                console.log('baz');
                oldC();
            };
        })();
    }

    c();
}

animate(function () { console.log('foo'); });

Not the neatest Javascript example I’ve ever written, but nevertheless this is an very powerful javascript pattern.

My particular use case was a fairly complex animation routine in which sections of the routine could be turned on or off. The callback passed in would be augmented in this fashion in order to ensure it would execute when the animation was complete.

However the solution above isn’t very scaleable; the code repetition seems to suggest that a useful abstraction could be added.

Function.prototype.extendFn = function (fn) {
    var c = this;
    return function () { fn(c); };
};

// Alternative, for those who don't like modifying Function.prototype:
var extendFn = function (callback, fn) {
    var c = callback;
    return function () { fn(c); };
};

The original code can now be rewritten:

var condition = another_condition = true; // For this example to work!

function animate (callback)
{
    c = (typeof(callback) == 'function') ? callback : function () {};

    if (condition) {
        c = c.extendFn(function (c) {
            c();
            console.log('bar');
        });
    }

    if (another_condition) {
        c = c.extendFn(function (c) {
            console.log('baz');
            c();
        });
    }

    c();
}

animate(function () { console.log('foo'); });

And will work as expected, printing:

baz foo bar

Much better! This solution was perfect for my particular use case, and I can see it being a useful functional programming pattern.

Update: Apologies for not mentioning this earlier, but thanks to the folks on Freenode's #javascript IRC channel, in particular joekarma for his original solution and suggestions. This post came out of a conversation yesterday in which we discussed possible solutions similar to those given above.

Data Models however are often tied heavily to their storage medium, whether that be an SQL database, files on a filesystem or a web-service. The idea of implementing a Model/Mapper system is to decouple the format in which we wish to manipulate data from the format that we store it.

PHP is a great language to attempt something like this. It’s dynamic nature allows us to create complex Domain Objects with a large range of functionality with minimal setup.

In Part 1 of this tutorial I’m going to show you how to build a generic Model base class from which you can easily extend concrete classes for use in your application.

In Part 2, I’m going to explore the role of the Mapper class, and how best to form a layer between your storage and your Domain Objects.

Not your average Model class

Take the following simple PHP Domain object:

class SerialKiller
{
    private $_name;
    private $_weapon;

    public function __construct ($name, $weapon)
    {
        $this->setName ($name)->setWeapon ($weapon);
    }

    public function getName ()
    {
        return $this->_name;
    }

    public function getWeapon ()
    {
        return $this->_weapon;
    }

    public function setName ($name)
    {
        $this->_name = $name;
        return $this;
    }

    public function setWeapon ($weapon)
    {
        $this->_weapon = $weapon;
        return $this;
    }
}

Ok, it’s a little unconventional but I’ve been watching a lot of Dexter) lately. Highly recommended! But it does illustrate a Model class in the classic sense: a class that abstract a set of data and provides a consistent interface to access it.

Many will argue that this could be done very simply using a PHP stdClass or even just a vanilla Array. What we are trying to promote here however is Encapsulation; the idea is that we hide the implementation of how our Model stores it data away from our client code.

Now that was a fair bit of code for a class that basically allows the getting and setting of two fields. In just writing that example, I had to make at least 3 typo corrections, and that’s only for two fields.

Our Model class take 2

Hmmm… seems like there would be a smarter way to do this. After all we do have a very flexible programming language to work with. Let’s try abstracting the getting and setting somewhat:

class SerialKiller // Mk.2
{
    private $_data = array (
            'name'   => null,
            'weapon' => null
        );

    public function __construct ($name, $weapon)
    {
        $this->setField ('name', $name)->setField ('weapon', $weapon);
    }

    public function getField ($name)
    {
        return isset ($this->_data[$name]) ? $this->_data[$name] : null;
    }

    public function setField ($name, $value)
    {
        if (isset ($this->_data[$name])) {
            $this->_data[$name] = (string) $value;
        }

        return $this;
    }
}

Ok, much more concise! The new and improved SerialKiller class gives us a couple of advantages over it’s predecessor:

1. It’s become a lot more general. For instance if we wanted to add another field, we could simply add a new key to SerialKiller::$_data.

2. The code is less prone to bugs since it’s shorter, more elegant and easier to read.

3. The code is easier to maintain now since it doesn’t contain as may functions.

However I think we can still improve more on this, say for instance I want some special functionality for the ‘weapon’ field. Say I want it to be in a range of certain values, and if it isn’t an exception should be thrown. How would I implement this?

Easy you say! You would insert a quick check into the SerialKiller::setField function that checks for a field name and acts accordingly. But of course, say I have 20 fields and 5 of them require custom handling. Not a very scalable solution!

So what’s the real problem here? The problem is twofold:

1. We’ve now changed the external API to something that is less consistent and meaningful than our first attempt.

2. Every field is accessed by calling the same function externally.

What we really need is a separate external function for each field that’s abstracted internally somehow.

Further Improvements

Remember that PHP can catch calls to non-existent functions in a class if you define a public function name __call. Let’s see what use we can make of this feature:

class SerialKiller //Mk.3
{
    private $_fields = array ('name', 'weapon');

    private $_data = array ();

    public function __construct ($name, $weapon)
    {
        $this->setName ($name)->setWeapon ($weapon);
    }

    public function __call ($fn, $args)
    {
        $type = substr ($fn, 0, 3);
        $name = strtolower (substr ($fn, 3));

        if ($type == 'get') {
            return $this->_getField ($name);
        }

        if ($type == 'set') {
            return $this->_setField ($name, $args[0]);
        }

        throw new Exception ("Function {$fn} is not implemeted.");
    }

    private function _getField ($name)
    {
        $this->_checkField ($name);

        return isset ($this->_data[$name]) ? $this->_data[$name] : null;
    }

    private function _setField ($name, $value)
    {
        $this->_checkField ($name);

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

    private function _checkField ($field)
    {
        if (!in_array ($field, $this->_fields)) {
            throw new Exception ("Field {$field} is invalid.");
        }           
    }
}

So there’s quite a jump between Mk.2 and Mk.3. Let me go through some of features we now have with our latest revision:

1. We now have the API of the first class with the internal benefits that the second class offered.

2. We’ve abstracted the process of adding fields to our serial killer. This means that to add a field for ‘Age’, all we’d need is to add the value ‘age’ to the SerialKiller::$_fields array.

   The benefit of that is that by making that small 7 character change (, ‘age’), we now can call getAge and setAge on any SerialKiller instance automatically!

3. Since __call is only called when a matching function is called and not found, we can easily introduce functionality for specific fields without altering existing functions:

   private function setWeapon ($weapon)
   {
       if (!in_array ($weapon, array ('knife', 'axe', 'chainsaw'))) {
           throw new Exception ('Invalid weapon type!');
       }
   
   	return $this->_setField ('Weapon', $weapon);
   
   }
   

4. Our SerialKiller is now extremely generic. If we wanted to specialise his class at all, we could do so very easily. In fact, if we were to rename SerialKiller to Model and make his class an abstract one, we now have a very generic Model class capable of storing all sorts of data in a very flexible way.

In Practice

Of course I like to bring these discussions back to something more pragmatic rather than keep the theoretical SerialKiller example going.

In practice this class works extremely well. All our internal Model classes extend a base class not dissimilar to the one we created above. Of course we’ve fleshed out our version considerably. Here’s a brief description of some features:

1. Better inflection of field names: Current this class converts everything to lowercase. Not a great idea since it means that more than one function can map to a field (e.g. setName, setNAME, setnAMe etc.).

   We like to inflect names from camel case (setFieldValue) to names that match our backend storage, usually underscore separated (field_value).

2. Setting & Getting fields en masse: This one is mostly useful in circumstances where you want to convert from Form data say to a Model class. We’ve incorporated this into the Constructor so creating a model from an array becomes as simple as:

   $serialKiller = new SerialKiller (array (‘name’ => ‘Dexter’, ‘weapon’ => ‘knife’));

3. Marking Concrete instances: We’ve added an id field to our base Model class separate from the other fields. This acts as a marker for Model instances that ties it to a row in the database. Instances without their id set are considered volatile instances and will expire when they go out of scope if they’re not saved.

There are hundreds of improvements you could make on the base class, and I’d strongly urge people to make improvements of their own.

I tend to work best through example, so let me walk-through how we use ZF in our business, and what components I used in this site to build a blogging engine. At the office we’ve been using the Zend Framework in production for about a year now. A lot has changed in the last year, but as most people who use open source software in a production environment will tell you, this is definitely common for a fairly young project like ZF.

Now almost all of our projects are based on ZF, and it’s modular architecture has led us to develop our own internal library which mostly houses extensions to existing ZF Components.

This site too is also based on ZF combined with our internal library and a simple blog engine I’ve dubbed mblog until I can come up with something easier to say (that or some kind of recursive acronym).

The major benefit that the ZF team touts is it’s modularity and it’s intentional lack of conventions and expectations; basically most components in ZF are design so that you can drop them into your code where it makes sense. There are a heap of benefits to this idea, and it tends to suit a lot of different approached web application development. However it also means that often you will need to go the last mile with ZF and really customise aspects to suit your code base.

That said, here’s how I’ve utilised parts of ZF to build this blogging engine:

Zend_Controller

If you are using Zend Framework for a web application and you have the flexibility I would definitely recommend using Zend_Controller as the backbone of your application.

ZF’s MVC implementation is very mature and supports features like complex routing and seamless view integration. It’s architecture provides an huge selection of hook points with which to integrate your own code.

mblog makes great use of the Action_Helpers, abstracting out large pieces of functionality and giving Controllers a simpler interface with which to execute and manage that functionality.

One example of this would be the comments form on every article page. All form creation and management (including setting cookies, managing form data etc.) is managed by an Action Helper. This is bridged to the view with a View Helper making access to the comments form easy from both controller and view code.

Zend_Feed

Although Zend_Feed is aimed more at consuming feeds, it does have the ability to generate dynamic feeds and provides a nicely abstracted set of base classes for you to implement custom feed types.

In this case the main site RSS feed is generated by passing an array of all current articles to the RSS feed and letting Zend_Feed generate the XML required.

Zend_Db

Internally at JB Interactive we don’t tend to use many of the Zend_Db components directly. Instead we have a Domain Model/Mapper layer (see here for a great article that describes a PHP implementation of this pattern) that sits between application code and the database. I’ll save Jb_Model for a later blog post, but in generally I find the Zend_Db classes somewhat too heavy for widespread application use.

That said, the Zend_Db Select API is fantastic and more or less gives you all the functionality of custom SQL queries with an OO interface.

In particular blog posts are retrieved and filtered using the select API, and the following is possible:

public function getPageByDetails ($slug, $year, $month, $day)
{
    $select = $this->_table->select ()
        ->where ('slug = ?', $slug)
        ->where ('YEAR(date_created) = ?',  (int) $year )
        ->where ('MONTH(date_created) = ?', (int) $month)
        ->where ('DAY(date_created) = ?',   (int) $day  );

    return $this->getDomainObjectWhere ($select);
}

Zend_Form

One of the newest members of the ZF family and definitely one of the most powerful; Zend_Form has a steep learning curve, but once setup allows you to create objects capable of gathering, filtering and validating data, as well as rendering the HTML required to display the form.

Forms however tend to be a very personal thing: each developer has their own views on what markup should be used, how fields should be placed and arranged. And since forms come in many different shapes and sizes, they often require logic powering how they are rendered.

Zend_Form is relatively new, and as such the API is very flexible, but it’s definitely missing pieces (file uploads for instance). By it’s nature it’s a difficult problem to address, and as such it’s ‘out-of-the-box’ functionality tends to lean towards the lowest common denominator.

To this extent I nearly always subclass Zend_Form depending on the project to provide some of functionality I need for the particular application. One thing that needs addressing in the short term is a method for quickly rendering hidden elements by themselves without resorting to Display Groups or Sub-Forms.

Zend_View

Most budding PHP developers go through stages. They start off with reasonably simple, self-contained PHP scripts. They then learn to include files and how to make simple templating systems. But eventually they get to the point where a separation of back-end code and display code is needed.

I always thought that PHP itself was high level enough to use as a “templating language”. Efforts like Smarty mean well, but are constantly forced to justify their existence with arguments like: “It’s easier to learn than PHP” or “the syntax is simpler and makes more sense to designers”.

For most modern web developers however layering another language on top of an interpreted scripting language is not a favorable solution. Why not just use plain old vanilla PHP scripts.

Zend_View to the rescue! The simple yet effective use of PHP as a templating engine makes for clean view scripts that really give you the option to abstract HTML and hide any complex logic.

Expect a lot more!

This is just a brief look at some pragmatic ways to use ZF in your application. I’d definitely encourage you to try it out and see how it fits into your development workflow.

In the coming weeks I’ll be going into some details as to how we’ve integrated ZF and our own internal code base and specifically how it’s helping us develop web sites and applications.