Duration: 20 mins

Introduction

Welcome to another tutorial. Today, I will be giving you a walk through of zftool, which provides basic tooling support in Zend Framework 2. If you’re new to Zend Framework, or have been reading the introductory series here, it can come in quite handy.

But unlike other frameworks, such as Yii (through yiic) and Symfony (via the Command Line tool), the tooling support in Zend Framework 2 is rather light on.

These respective tools provide rather robust support for automatically generating models from database connections, checking logs and a host of other much required functionality.

I understand from some tweets with Enrico Zimuel new additions are planned for zftool. But for right now, Zend Framework is definitely the junior. However, that aside, I like to take the adage of a glass half full and see zftool as a good start. Today we’re going to use it to carry out the following tasks:

1. Create a basic ZF2 project
2. Create several modules
3. Creating an autoloader classmap
4. Checking if there are any issues

By the end of today’s tutorial, you will have a good understanding of how to get started with it and to be able to use it in your projects. Firstly, let’s install zftool and get started.

Installation

There are a number of ways in which zftool can be installed, including using Composer and downloading the Phar tool.

During the research for this article, I tried to install it via Composer, but continuously met with permission related errors. As a result, I’ve chosen to focus on the Phar tool approach, which works, almost, seamlessly.

If you’d like to go down the Composer route, run the following command in your Terminal or console and you’ll have it available.

$ composer require zendframework/zftool:dev-master

Otherwise, download the phar file. Once it’s downloaded, run the following commands. These make it accessible universally on your system:

sudo cp -v zftool.phar /bin/
cd /bin/
sudo ln -s zftool.phar zftool
sudo chmod +x zftool.phar

If you’re not familiar with the Linux command line, what we’ve done here is to copy zftool.phar to one of the directories automatically in a users PATH.

Then we’ve created a symlink to it, giving it a simpler name and finally set the executable bit on it – now it’s ready to run.

Running the Phar Tool

Now that we have the Phar file available, let’s have a look at the options available. Running the following command will display a help screen, showing all of the options supported:

zftool.phar

It will result in output similar to that below:

--------------------------------------------------------------------------------
ZFTool
--------------------------------------------------------------------------------
Basic information:
  zftool.phar modules [list]         show loaded modules
  zftool.phar version | --version    display current Zend Framework version
Diagnostics
  zftool.phar diag [options] [module name]    run diagnostics
  [module name]    (Optional) name of module to test
  -v --verbose     Display detailed information.
  -b --break       Stop testing on first failure
  -q --quiet       Do not display any output unless an error occurs.
  --debug          Display raw debug info from tests.
Application configuration:
  zftool.phar config [list]                list all configuration options
  zftool.phar config get <name>            display a single config value, i.e. "config get db.host"
  zftool.phar config set <name> <value>    set a single config value (use only to change scalar values)
Project creation:
  zftool.phar create project <path>    create a skeleton application
  <path>    The path of the project to be created
Module creation:
  zftool.phar create module <name> [<path>]    create a module
  <name>    The name of the module to be created
  <path>    The root path of a ZF2 application where to create the module
Classmap generator:
  zftool.phar classmap generate <directory> <classmap file> [--append|-a] [--overwrite|-w]
  <directory>         The directory to scan for PHP classes (use "." to use current directory)
  <classmap file>     File name for generated class map file  or - for standard output.If not supplied, defaults to
                      autoload_classmap.php inside <directory>.
  --append | -a       Append to classmap file if it exists
  --overwrite | -w    Whether or not to overwrite existing classmap file
Zend Framework 2 installation:
  zftool.phar install zf <path> [<version>]
  <path>       The directory where to install the ZF2 library
  <version>    The version to install, if not specified uses the last available

Creating a Project

Ok, with the tool ready to go, let’s set about using some of it’s functionality to creating and managing a Zend Framework 2 project, as outlined above.

Create the Project

Firstly, we’ll create a raw project, called ‘simple project’. To do so, run the following command:

$ php zftool.phar create project ./simpleproject

This will create the core project files in a directory in the current directory, called ‘simpleproject’. It will give you output similar to that below:

ZF2 skeleton application installed in ./simpleproject.
In order to execute the skeleton application you need to install the ZF2 library.
Execute: "composer.phar install" in ./simpleproject
For more info in ./simpleproject/README.md

Assuming there were no permission issues, the project directory should look as follows:

$ ls -l ./simpleproject/
-rw-rw-r-- 1 maltblue maltblue    342 Jun 12 06:34 composer.json
-rwxr-xr-x 1 maltblue maltblue 709565 Jun 12 06:34 composer.phar
drwxrwxr-x 3 maltblue maltblue   4096 Jun 12 06:34 config
drwxrwxr-x 3 maltblue maltblue   4096 Jun 12 06:34 data
-rw-rw-r-- 1 maltblue maltblue   1807 Jun 12 06:34 init_autoloader.php
-rw-rw-r-- 1 maltblue maltblue   1548 Jun 12 06:34 LICENSE.txt
drwxrwxr-x 3 maltblue maltblue   4096 Jun 12 06:34 module
drwxrwxr-x 5 maltblue maltblue   4096 Jun 12 06:34 public
-rw-rw-r-- 1 maltblue maltblue   1759 Jun 12 06:34 README.md
drwxrwxr-x 3 maltblue maltblue   4096 Jun 12 06:34 vendor

The Generated composer.json File

Looking in the project directory, we see a new composer.json file, which has the basic configuration and requirements for a Zend Framework 2 project. If you’d like to go further, feel free to alter it as suits your needs, running composer update afterwards.

{
    "name": "zendframework/skeleton-application",
    "description": "Skeleton Application for ZF2",
    "license": "BSD-3-Clause",
    "keywords": [
        "framework",
        "zf2"
    ],
    "homepage": "http://framework.zend.com/",
    "require": {
        "php": ">=5.3.3",
        "zendframework/zendframework": ">2.2.0rc1"
    }
}

Installing Zend Framework 2 in the Project (With Composer)

With the basic files in place, unless you have the Zend Framework libraries on your path, the application won’t run. So, in the project directory, run composer.phar install to bring in the required libraries and dependencies.

The output will look similar to that below. I’ve trimmed it for sakes of readability.

$ composer.phar install
Loading composer repositories with package information
Installing dependencies (including require-dev)
  - Installing zendframework/zendframework (2.2.0)
    Downloading: 100%
Writing lock file
Generating autoload files

Creating a Module

Now we’ve got the base project and dependencies, let’s create a module. We’ll call it "application".

NB: I believe case is not important; so Application = application.

To create it, run the following command, from your project directory:

$ zftool.phar create module application

Running it, however, returns output listing a series of mkdir errors. I believe this came about as the Application module was already there. If so, it would be helpful to print out a simple message indicating this, instead of attempting to proceed with creating an existing module.

Creating Another Module

Ok, now let’s create a module which doesn’t already exist; we’ll call it Generic. As before, we create the module via the command below:

zftool.phar create module Generic

You should see output similar to that below, indicating there were no problems.

The module Generic has been created

Looking in the Generic module directory, we see the following structure:

$ ls -l module/Generic/
total 16
drwxrwxr-x 2 maltblue maltblue 4096 Jun 12 06:47 config
-rw-rw-r-- 1 maltblue maltblue  437 Jun 12 06:47 Module.php
drwxrwxr-x 3 maltblue maltblue 4096 Jun 12 06:47 src
drwxrwxr-x 2 maltblue maltblue 4096 Jun 12 06:47 view

Under config is a module.config.php file. So, we now have the basic structure of a ZF2 module.

Viewing a List of Modules

But what if we want to see the list of modules? Well, here’s where I hit an issue. I believe the following command will show us that list.

$ php zftool.phar modules

But no matter what I tried, it always resulted in the following error:

No modules installed. Are you in the root folder of a ZF2 application?

At this stage, I’m not sure if it’s a bug or a user (me) problem. However, as I get more information, I’ll update the post about this issue.

Classmap Generation

Ok, we’re just about done. If you’re familiar with Zend Framework 2, you’ll know that performance can be increased through a classmap file.

A class map file stores a map of files which the application may require, saving it from performing a file location resolution. Effectively, it’s a class file location cache.

Let’s assume we have a series of classes in the module directory. Let’s create a classmap file for it. To do so, we run the following command:

$ zftool classmap generate module/ autoadclassmap.php

This looks for all class files in the module directory and then writes it out to autoadclassmap.php in the current directory. It will have output similar to that below:

Creating classmap file for library in /home/parallels/zftool/vendor/simpleproject/module
Scanning for files containing PHP classes .... DONE
Found 4 PHP classes
Creating classmap code ... DONE
Writing classmap to autoload_classmap.php...  DONE
Wrote classmap to /home/parallels/zftool/vendor/simpleproject/autoload_classmap.php

The Generated Classmap File

If you’ve not seen a classmap file before, here’s what the one we just created looks like (formatted for better readability):

    $ cat autoload_classmap.php
    <?php
    // Generated by Zend Framework 2
    return array(
        'Generic\Module' => DIR . '/module/Generic/Module.php',
        'Application\Controller\IndexController' => DIR .
'/module/Application/src/Application/Controller/IndexController.php',
        'Application\Module' => DIR . '/module/Application/Module.php',
        'Users\Module' => DIR . '/module/Users/Module.php',

Running Diagnostics

Now on to the last command we’re going to run, module diagnostics. I’m going to run diagnostics on the new, Generic, module we’ve created in this tutorial. From the project root, run the following command:

$ zftool diag --debug Generic

This will run diagnostics, showing debug information. In this case, just re-iterating the running version of PHP.

Starting diagnostics:
OK   ZF: PHP Version: Current PHP version is 5.4.6-1ubuntu1.2
--------------------------------------------------------------------
'5.4.6-1ubuntu1.2'
------------------------------------------------------------------------
OK (1 diagnostic tests)

Verbose Information

Running it again, with the verbose flag set, show’s approximately the same information, just less detailed. We can see here there were no issues with the module. So there was nothing to report.

$ php ../zftool.phar diag -v Application
Starting diagnostics:
OK   ZF: PHP Version: Current PHP version is 5.4.6-1ubuntu1.2

OK (1 diagnostic tests)

I must admit I’m not quite sure of the intent of the diagnostic tool. I’ve renamed Module.php in Generic, renamed the Generic module directory, yet still the tool reports everything is ok.

I’ll be doing so more research into this and updating the article with what is found.

Conclusion

And this brings us to the end of our walkthrough of zftool in Zend Framework 2. Now that we’ve finished the walk through, I hope you now have a good understanding of how to use it in your projects, to alleviate some of the manual work required in setting them up as well as creating modules.

I’m looking forward to it having a larger array of features, as time goes on. But for now, unfortunately, zftool is rather limited.

If you’d like to contribute to the project and help get the features reader sooner, clone a copy of the code and get involved. I’m sure your contribution will be well received.

What do you think of zftool? Good enough to use in your projects? Do you have home-made tools that already do what it provides (and more)? If so, share your thoughts in the comments.

Related Links

• Composer
• zftool on Github
• Yii tools
• Symfony tools

Related Posts

• Zend Form – Multiple Submit Buttons
• Rename uploaded files with Zend Framework
• Zend Framework 2 – The New HTML5 Form Fields
• Extending Zend Auth – A Zend Config Adapter
• Zend Framework 2 ServiceManager – Web Application Development Simplified

In this tutorial, I’ll be taking you through a few of the new HTML5-specific form elements available in the new Zend Framework 2. We’ll see: how they work, how to use them, so you can also see what they’re like.

This will be coupled with a good set of screenshots – so you know what they look like. By the end of this tutorial, you should be well on your way to being able to have fully HTML5 interfaces in your applications.

If you’re not familiar with forms in Zend Framework 2 yet, check out the online documentation first. Alternatively, read the introductory series here on Malt Blue:

• Dependency Injection
• Zend Framework 2 Modules
• Event Manager
• Service Manager

Difficulty

Beginner

Time Required

20 Minutes

Please Note:

The language set on the iPhone in the screenshots in this tutorial is German. This shouldn’t cause any real issues. But, here is a translation of the words that you are not likely to know if you’re not familiar with German:

• zurück – back
• weiter – forward
• fertig – finish/done
• löschen – clear/delete/empty

Why HTML5 elements?

As the online world becomes more mobile-centric, we need to be both aware of what this means and how we as developers, specializing in the Zend Framework, can implement them in the applications we’re building.

Here are a few facts from the recent Zend Developer Pulse Report:

• [IDC predicts](http://www.computerworld.com/s/
  article/9219932/MostwillaccessInternetviamobiledevicesby2015IDCsays) that by 2015, more people will access the Internet through a smartphone than a desktop
• By 2015, mobile app development projects will outnumber native PC projects by a ratio of 4-1
• A full 91% of application developers plan to deliver content and services to a mobile audience
• According to IDC: “Sales of smart mobile devices – smartphones and tablets – will grow by 20%, generate 20% of all IT sales and drive 57% of all IT market growth.”

These are impressive numbers and clearly show 2 things:

• Where the market is going
• Why mobile development is a good place to focus your development efforts

So today, let’s dip our toes in the HTML5 & Mobile development waters and get just a taste of what is available to us.

iPhone Warning: If you’re a Windows Phone or Blackberry supporter you may be a little disappointed by what you’re about to see. The screenshots in today’s post primarily focus around iPhone 5. However, I will be including some screenshots from Android, using the HTC One shortly.

The HTML5 Form Elements?

If you’re familiar with the HTML5 specification, you’ll know that there are a number of new elements. In the space that this tutorial has available however, I’ll only be focusing on just a few, specifically input.

These are:

• Telephone (tel) – control for entering a telephone number; line-breaks are automatically removed from the input value, but no other syntax is enforced. You can use attributes such as pattern and maxlength to restrict values entered in the control.
• Email – A field for editing an e-mail address.
• Url – A field for editing a URL. The user may enter a blank or invalid address. Line-breaks are automatically removed from the input value. You can use attributes such as pattern and maxlength to restrict values entered in the control.
• DateTime (date, datetime, datetime-local) – A control for entering a date and time (hour, minute, second, and fraction of a second) based on UTC time zone.

For further information about each of these fields, and the rest of the specification, check out the documentation over at MDN (Mozilla Developer Network).

Implementing Them

Implementing them is really trivial, no more difficult than implementing any of the other fields that you’ve been implementing up until now. The way that I’ve approached it is through form code, with a minimalist configuration.

A lot of these examples you’ll see are very similar. That’s OK, as there’s generally not a lot that you have to do which is different.

Email

What about email? Whether that’s a registration, forgot password or user management form, it’s arguably one of the most important fields in a form.

As you can see, in the image above, when the user clicks in an email field, the keyboard is changed to only provide characters that match the email specification. The email field will validate that value entered in the field represents a valid email address.

View Script

As with the telephone example above, I’ve rendered the email element in the view script using the viewscript form helpers (formLabel and formEmail).

<div class="control-group">
    <?php
    $active = $form->get('eventCategoryActive');
    echo $this->formLabel($active);
    ?>
    <div class="controls">
        <?php
        echo $this->formEmail($active);
        echo $this->formElementErrors($active);
        ?>
    </div>
</div>

Form Code

Now for the code. As with the telephone element, I’m adding the email element to the form by specifying the type as ‘Zend\Form\Element\Email‘. I’ve then specified the name and label values.

$this->add(array(
    'type' => 'Zend\Form\Element\Email',
    'name' => 'userWebsite',
    'options' => array(
        'label' => 'Website',
    )
));

This configuration allows for one email address. If you want to allow for multiple email addresses, then add specify multiple to true in the options array, as follows:

$this->add(array(
    'type' => 'Zend\Form\Element\Email',
    'name' => 'userWebsite',
    'options' => array(
        'label' => 'Website',
        'multiple' => true
    )
));

Url

Arguably, after emails (or maybe before), come URLs. Whether it’s a web address, ftp address or similar, they’re one of the most commonly used aspects on the web.

In the screenshot above, you see how the keyboard on the iPhone 5 has changed so that only allowed characters are available, with an extra .com button to help along. This element transparently adds the Zend\Validator\Uri validator, which ensures that the value entered is a value URI.

View Script

Here, I’ve rendered the url field using the formUrl ViewScript helper, as in previous examples.

<div class="control-group">
    <?php
    $active = $form->get('eventCategoryActive');
    echo $this->formLabel($active);
    ?>
    <div class="controls">
        <?php
        echo $this->formUrl($active);
        echo $this->formElementErrors($active);
        ?>
    </div>
</div>

Form Code

As with the previous examples, I’m adding the URL element to the form by specifying the type as ‘Zend\Form\Element\Url‘. I’ve then specified the name and label values.

$this->add(array(
    'type' => 'Zend\Form\Element\Url',
    'name' => 'userWebsite',
    'options' => array(
        'label' => 'Website',
    )
));

DateTime

One last example. This one is one that I feel is really important and consequently very helpful for users – the Date & Time field.

How often do we, as developers & designers, have to put in extra work or jump through hoops to ensure that the user enters the correct information when supplying dates and times? Arguably, too often is a pretty close answer. Right?

Well the HTML5 DateTime element goes a long way to cutting this effort down (at least on a Smart Phone). In the screenshot above, you can see that when the user’s given focus to the DateTime field, the keyboard has changed to only allow them to enter a valid date, using the ultra-efficient date input keyboard available under iOS.

Now, all we need to do is to convert one value sent from the form, into an applicable format required to be stored in our datasource (whether MySQL, PostgreSQL, MongoDB or whatever). When the user is finished, the field appears as a select box showing the specified date.

View Script

As with the previous examples, I’ve used the form ViewScript helpers to render the element. Nothing new here.

<div class="control-group">
    <?php
    $active = $form->get('eventCategoryActive');
    echo $this->formLabel($active);
    ?>
    <div class="controls">
        <?php
        echo $this->formSelect($active);
        echo $this->formElementErrors($active);
        ?>
    </div>
</div>

Form Code

Similarly, with the other elements, I’ve called the add method, passing in an array, specifying the type (‘Zend\Form\Element\Date‘), name and label values for the element, which has done the majority of the heavy lifting for us.

$this->add(array(
    'type' => 'Zend\Form\Element\Date',
    'name' => 'userWebsite',
    'options' => array(
        'label' => 'Website',
    )
));

If we wanted to provide even more guidance to the user, we could have specified a minimum and maximum date range in the additional attributes array (as below). Some examples of where this can be useful are:

• Users being over or under a certain age
• Users being within a certain age range
• Defaulting to a short, meaningful range so the user doesn’t need to search too much

Specifying the Minimum and Maximum Date Range

'attributes' => array(
         'min' => '2012-01-01',
         'max' => '2020-01-01',
 )

Telephone

At this point, given the wide differences in international phone number formats, no validation is performed by the browser. However, what we do get is, on mobile devices, a keyboard that is customized to entering the correct type of information.

You can see in the screenshot above that when you set focus in the field, that the keyboard changes to one that only provides options for entering phone number information (including the international dialing prefixes; i.e., +61, +49 etc).

View Script

In the view script output below, you’ll see that I’m using the formTel and formLabel view helpers. This will, assuming that the element is a telephone field, print out a telephone type field.

<div class="control-group">
    <?php
        $active = $form->get('eventCategoryActive');
        echo $this->formLabel($active);
    ?>
    <div class="controls">
        <?php
            echo $this->formTel($active);
            echo $this->formElementErrors($active);
        ?>
    </div>
</div>

Form Code

Now that we have the view script in place, let’s have a look at the code for creating a phone number field. Firstly, I’ve created a new Zend Form object, called $form.

I’ve then called add on this, which adds a new Form Element, specifying the type, name and options. You can see that it’s of type Telephone, the name is userPhone and I’ve set the label value to Phone Number.

$form = new \Zend\Form;
$form->add(array(
    'type' => 'Zend\Form\Element\Number',
    'name' => 'userPhone',
    'options' => array(
        'label' => 'Phone Number',
    )
));

Nothing hard about this one. Now your user has less work to do to enter phone and fax numbers on your forms.

Conclusion

So there we have it. We’ve gone through four of the new HTML5 elements available in Zend Framework 2 (Telephone, Email, URL and DateTime). As we’ve touched on, there are a number of other new elements, including Month, Color, Time, Week and Range.

We’ve seen what they look like in the most popular mobile browser, Safari on iOS, and how they make the job of user input simpler, quicker and easier to complete. You’re now in a position to use the remainder of the new HTML5 elements, as needed, in your applications.

Given the continued growth of smart phones and mobile internet access and the expected usage numbers over the next 5 years, these fields will help ensure that they’re the ones that continue to prosper and are thoroughly enjoyed by users.

For more information about the elements that I’ve used on today’s tutorial, or any of the other elements available in Zend Framework 2, be sure to check out the excellent online documentation.

Till then, share your thoughts, in the comments, about how you’re using the new HTML5 elements in your applications. How are they enhancing your applications? Have your users been giving you positive feedback?

Related Posts

• Zend Form – Multiple Submit Buttons
• Zend Framework 2 Modules – The Application’s Heart
• Zend Framework 2 Event Manager – A Gentle Introduction
• Zend Framework 2 – Hydrators, Models and the TableGateway Pattern
• Zend Form Mastery with Zend Config – Part 2 Core Form Configuration

Synopsis

Zend Framework 2 comes packed with an assortment of new features and functionality and greatly streamlines how common scenarios, such as interacting with datasources and application configuration and caching are implemented.

Whether it’s the new HTML5 form elements and view helpers, the new implementation of Zend\Http, the Service Manager, the Event Manager or that Modules are now first-class citizens – you can’t help but see that it’s bursting at the seams.

But one set of features has really been helping me of late ones that really have me smiling; these are: Hydrators, Models and Table Gateways. If you’re new to ZF2 or database interaction with frameworks, then you’re in a perfect position as today’s post will be giving you a good introduction to the basics of using both together.

We’ll be working through sample code which will show you how to create models, which are decoupled from data source logic, yet via a simple ServiceManager configuration and a not too complex hydrator, will be able to extract information from a database query and auto-fill the model with it – ready to be used.

Why This Approach?

In the past, in Zend Framework 1, when you wanted to have a datasource agnostic model, it wasn’t always so simple to implement. Though there is still a lot of talk of PHP & MySQL; we all know that there is a veritable cornucopia of choice, including MongoDB, CouchDB, PostgreSQL, Cassandra, Redis and much, much, more.

Applications we write can start out with simple, modest needs. At first, maybe a basic RDBMS will suffice. But, as your needs change and grow, it’s nice to know that, without too much code refactoring, you can change around to match.

Today’s approach does this – allowing for a nearly transparent data source, which the model class knows nothing about. It ensures that irrespective of where the information comes from, it will be transformed so that the model class will be able to use it.

How Does It Work?

In a nutshell here’s how it works. Firstly a TableGateway class performs the specific interaction with the datasource, such as fetching all records, deleting, adding and updating records. In this case it is a MySQL 5 database. The, the hydrator class maps (and transforms where applicable) the information retrieved from the TableGateway to the Model class.

In the getServiceConfig method in our Module class, the two are bound together and the Hydrator is configured. Finally, in a controller action, we can then access the datasource, querying records, auto-populating our Model and then iterate over the records. Sound good? Great!

Let’s get going!

The Table Gateway Class

Here we have the TableGateway class. I’ve called it UserTable as it is responsible for managing information in a user table. I’ve kept it simple and just focused on the retrieving of records skipping over the remainder of the CRUD operations.

In the constructor, we passing in a TableGateway object, which will be made available in the ServiceManager configuration. This provides us with simple access to the database. In the fetchAll function, we retrieve a result set by calling the select method on the TableGateway object.

The calls to buffer and next aren’t strictly necessary – but have been included as, in the list action, a Paginator object is returned. Errors will be thrown if these two methods aren’t called. Not much to it – right?

namespace MaltBlueCore\Model;
use Zend\Db\TableGateway\TableGateway;
class UserTable
{
    protected $tableGateway;
    public function __construct(TableGateway $tableGateway)
    {
        $this->tableGateway = $tableGateway;
    }
    public function fetchAll()
    {
        $resultSet = $this->tableGateway->select();
        $resultSet->buffer();
        $resultSet->next();
        return $resultSet;
    }
}

The Model Class

Now we have the User class. As you can see, this class has no code that relates to any kind of datasource or database. Here, we’re only concerned about the data that we want to work with – in this case a:

• user id
• name
• active flag
• record creation date

The exchangeArray method is a common mention in ZF2 for passing in a dataset, such as an array in this case and auto-populating the object. You can see that I’ve set all the properties from the respective array key. Nice clean and simple.

namespace MaltBlueCore\Model;
class User
{
    public $userId;
    public $userName;
    public $userActive;
    public $createdDate;
    public function exchangeArray($data)
    {
        if (isset($data['userName'])) {
            $this->userName = $data['userName'];
        } else {
            $this->userName = null;
        }
        if (isset($data['userActive'])) {
            $this->userActive = $data['userActive'];
        } else {
            $this->userActive = null;
        }
        if (isset($data['userId'])) {
            $this->userId = $data['userId'];
        } else {
            $this->userId = null;
        }
        if (isset($data['createdDate'])) {
            $this->createdDate = $data['createdDate'];
        } else {
            $this->createdDate = null;
        }
    }
    public function getArrayCopy()
    {
        return get_object_vars($this);
    }
}

The Hydrator

The Hydrator is the key aspect of the setup. It’s what maps the database field names on one side, to the entity properties on the other. However, it doesn’t store this information internally – as you’ll see. I went for a more generic approach, one class which could be applied to any table.

What this does is allow for an array of Column Names -> Entity Properties to be passed in as an array and, when its hydrate method is called, will transfer the respective information from the datasource to the model object.

namespace MaltBlueCore\Hydrator;
use ReflectionMethod;
use Traversable;
use Zend\Stdlib\Exception;
use Zend\Stdlib\Hydrator\AbstractHydrator;
use Zend\Stdlib\Hydrator\HydratorOptionsInterface;
class TableEntityMapper
    extends AbstractHydrator
    implements HydratorOptionsInterface
{
    protected $_dataMap = true;
    public function __construct($map)
    {
        parent::__construct();
        $this->_dataMap = $map;
    }
    public function extract($object) {}

In the hydrate method, we pass in the datasource and the model. If the model is not an object, we throw a BadMethodCallException. If it is, we proceed and iterate over the data available.

If there is a mapping available, we use that to determine which field in the model matches with which field in the datasource. If it doesn’t (if no mapping is required), we set the property directly. Any unknown or missing properties are silently skipped over.

    public function hydrate(array $data, $object)
    {
        if (!is_object($object)) {
            throw new Exception\BadMethodCallException(sprintf(
                '%s expects the provided $object to be a PHP object)',
                __METHOD__
            ));
        }
        foreach ($data as $property => $value) {
            if (!property_exists($this, $property)) {
                if (in_array($property, array_keys($this->_dataMap))) {
                    $_prop = $this->_dataMap[$property];
                    $object->$_prop = $value;
                } else {
                    // unknown properties are skipped
                }
            } else {
                $object->$property = $value;
            }
        }
        return $object;
    }
}

The Module Service Configuration

In the Module configuration, is where we tie everything together. I’ve been writing about the ServiceManager previously and I’ve listed some excellent links in the further reading section, which I encourage you to check out. Without this component, the rest really would not be possible.

Firstly we register an object in the factories list, which initialises the UserTable model we covered earlier, passing it the TableGateway object. Following that, we have the configuration for the TableGateway object. I have much to thank Evan Coury for in the approach that I’ve taken here.

What this does is to retrieve the application database adapter and initialise an instance of the hydrator that we previously covered, where we provide it with the mapping array; the table column names on the left and the model properties on the right.

We then provide the User model as the prototype to use with the HydratingResultSet object. If you’re not familiar with it, the HydratingResultSet is a truly amazing part of Zend Framework 2.

I’ll not try an invent the wheel and quote directly from the manual:

Zend\Db\ResultSet\HydratingResultSet is a more flexible ResultSet object that allows the developer to choose an appropriate “hydration strategy” for getting row data into a target object.

While iterating over results, HydratingResultSet will take a prototype of a target object and clone it once for each row. The HydratingResultSet will then hydrate that clone with the row data.

In essence, we provide the model, data and hydrator and it takes care of the rest. Following that, we return a new TableGateway object, specifying the underlying table, tbluser, that will be the source of the data, the database adapter and the resultset object we’ve just initialised.

Now, we have the two sides of the equation beautifully joined. Should the datasource change, the table name, the properties or column names, we only need make a slight adjustment here. No other classes or code need be touched.

public function getServiceConfig()
{
    return array(
        'factories' => array(
            'MaltBlueAdmin\Model\UserTable' =>  function($sm) {
                $tableGateway = $sm->get('UserTableGateway');
                $table = new UserTable($tableGateway);
                return $table;
            },
            'UserTableGateway' => function ($sm) {
                $dbAdapter = $sm->get('Zend\Db\Adapter\Adapter');
                $hydrator = new \MaltBlueCore\Hydrator\TableEntityMapper(
                    array(
                        'UserID' => 'userId',
                        'UserName' => 'userName',
                        'StatusID' => 'userActive',
                        'CreatedOn' => 'createdDate'
                    ));
                $rowObjectPrototype = new \MaltBlueCore\Model\User;
                $resultSet = new \Zend\Db\ResultSet\HydratingResultSet(
                    $hydrator, $rowObjectPrototype
                );
                return new TableGateway(
                    'tbluser', $dbAdapter, null, $resultSet
                );
            }
        )
    );
}

The Controller

Ok, now we show how to use it. In our controller, we have a list action, which, as the name implies, will retrieve a list of records, which we will iterate over.

namespace MaltBlueManagementAdmin\Controller;
use Zend\Mvc\Controller\AbstractActionController;
use Zend\View\Model\ViewModel;
use MaltBlueCore\Model\User;
use MaltBlueCore\Form\AddUserForm;
use MaltBlueCore\Form\EditUserForm;
class userController extends AbstractActionController
{
    protected $userTable;
    protected $_createUserForm;
    public function listAction()
    {

Firstly, we retrieve a copy of the userTable object through the Service Locator. We then call the fetchAll method, retrieving all rows from the table. I’ve used a filter iterator and a paginator to make for a more juicy example.

The filter iterator will only return records where the userActive field is set to “active”. All others will be skipped. This iterator is then passed to the Zend\Paginator object, a few properties are set on it and is returned in the ViewModel, ready to be iterated over in the view script.

        $sm = $this->getServiceLocator();
        $userTable = new \MaltBlueCore\Model\UserTable(
            $sm->get('userTableGateway')
        );
        $filterIterator = new StatusFilterIterator(
            $userTable->fetchAll(), "active"
        );
        $paginator = new Paginator(new Iterator($filterIterator));
        $paginator->setCurrentPageNumber(
            $this->params()->fromRoute('page')
        );
        $paginator->setItemCountPerPage(
            $this->params()->fromRoute('perPage', 10)
        );
        return new ViewModel(array(
            'paginator' => $paginator,
            'status' => $this->params()->fromRoute('status')
        ));
    }
}

Conclusion

So, there we have it. With, only a little bit of code, we’ve created a model that is able to interact with a variety of data sources, yet avoid coupling to tightly at the same time. If we move from MySQL to PostgreSQL or Redis, then the requisite parts can be changed to suit.

Now, I’m not as experienced with hydrators, data mappers and the table gateway pattern as others. So I’d love to get your feedback. Tell me where this approach can be improved. Are there other aspects of ZF2 that can take it further – such as Strategies by Jurian Sluiman.

Related Posts

• Zend Framework 2 Event Manager – A Gentle Introduction
• Zend Framework 2 Modules – The Application’s Heart
• Zend Framework 2 Core Concepts – Dependency Injection
• Zend Framework 2 – The New HTML5 Form Fields
• Zend Framework 2 ServiceManager – Web Application Development Simplified

Today using Zend Framework 2 RouteMatch, Router and Request objects, I show you an easy way to dynamically update the current route. It’s almost painlessly simple.

Working with Routes

In a Zend Framework 2 application that I’ve been building lately, I came across an unexpected routing situation; one that I’d not previously encountered. It started off pretty simply, with a small, segment, route that allowed me to render a page with two parameters: record status and page number.

It was for a fairly typical page that uses the Zend Paginator to paginate a large record set object and a status parameter to filter down the records displayed.

Well, like most things in web application development, what starts out simply in the beginner often grows more complex over time. So too is my once simple route. From humble origins, it’s evolved to have the following parameters:

Here’s a route in questions, so you can see how it’s configured:

'category-list' => array(
    'type'    => 'segment',
    'options' => array(
        'route'    => '/admin/category/list[/status/:status]
                          [/page/:page][/perPage/:perPage][/sortBy/:sortBy]
                          [/sortDir/:sortDir][/filterLetter/:filterLetter]',
        'defaults' => array(
            '__NAMESPACE__' => 'MaltBlueAdmin\Controller',
            'controller'    => 'Category',
            'action'        => 'list',
            'status' => 'all',
            'page' => 1,
            'perPage' => 10
            'sortBy' => "category-name"
            'sortDir' => "asc"
            'filterLetter' => ""
        ),
    ),
),

You can see that, as mentioned, I’m using the segment route type and all of the parameters are optional and have meaningful defaults. “What’s the big problem”, you ask. It’s an easy route to construct, has meaningful defaults. Add it to your module’s module.config.php and get going.

Well, I found it not so easy. You see, the route forms the foundation of a toolbar I’ve been creating in a custom view helper. It aims to give the user a large amount of power to filter the records available, so they can get to them quickly – but without overwhelming them with choice.

The toolbar works as follows: it sits atop the list of paginated records, followed by the list of records, then finally the pagination control. By default, no filter options are set. As desired, the user can then add different filters, of the types above. Have a look in the screenshots below and you’ll see a bit of what it looks like.

In a nutshell, here is the problem. We’ve set the route parameters and rendered the page. How can we change, add or remove a parameter and re-render the current page, simply and easily? Said differently, when the user clicks a filter, how can I redirect to the same page, enable that filter and re-render paginated results?

At first I tried a rather convoluted function that used the EventManager in ZF2. To say the least, it was long and convoluted. Then I came across a post from Sam Minds that lead me to the eventual solution I present here today.

It turned out to be so simple, that I can keep adding further route options and the code stay’s pretty small. And to do it, all I needed was 3 components from the new Zend Framework 2:

1. Zend\Mvc\Router\Http\TreeRouteStack
2. Zend\Http\Request
3. Zend\Mvc\Router\Http\RouteMatch

The key component though, is RouteMatch. If you’re not familiar with it, it looks as follows:

namespace Zend\Mvc\Router;
class RouteMatch
{
    public function __construct(array $params);
    public function setMatchedRouteName($name);
    public function getMatchedRouteName();
    public function setParam($name, $value);
    public function getParams();
    public function getParam($name, $default = null);
}

What it does is allow you to set and extract parameters from a given Route object, in my case, the current one. Even better, I only needed to use 3 functions. These are:

• getMatchedRouteName
• getParam
• setParam

I’ll skip from the story now and show you the code, so you can see what I did. In the code below, you can see a part of my getViewHelperConfig definition in the module’s Module.php file. Here, I’ve use the factories element to initialise my new ViewHelper, passing in the Router and Request objects retrieved from the ServiceManager.

This gives me access to the core of the information that I need about both the current route and request.

namespace MaltBlue;
use Zend\Mvc\ModuleRouteListener;
use Zend\Mvc\MvcEvent;
use MaltBlue\View\Helper\ListViewToolbar;
class Module
{
    public function getViewHelperConfig()
    {
        return array(
            'factories' => array(
                'listViewToolbar' => function($sm) {
                    $locator = $sm->getServiceLocator();
                    return new ListViewToolbar(
                      $locator->get('Router'), $locator->get('Request')
                    );
                },
            ),
        );
    }
}

In the constructor of the ViewHelper, I initialise two class variables with the Router and Request objects obtained.

namespace CoalescentCore\View\Helper;
use Zend\View\Helper\AbstractHelper;
use Zend\Mvc\Router\Http\TreeRouteStack as Router;
use Zend\Http\Request;
use Zend\Mvc\Router\Http\RouteMatch;
class ListViewToolbar extends AbstractHelper
{
    protected $router;
    protected $request;
    protected $viewTemplate;
    protected $allowedFilters;
    public function __construct(Router $router, Request $request)
    {
        $this->router = $router;
        $this->request = $request;
        $this->viewTemplate = "/toolbar/listview";
    }

Next I have a method _getFilterRoute. This is responsible for determining and setting the record status filter in the route. First I initialise a RouteMatch object, by calling match on the Router object and pass in the Request object.

If the statusFilter supplied is in an allowed list (currently a simply array) I set the status route parameter to the value supplied.

After that, I then assemble a new route, by calling the assemble function on the router object. I pass to assemble the complete, updated, list of route parameters (the previous list with the one change that I’ve just made) – along with the route name, retrieved with the getMatchedRouteName function. From this the function returns a fully formed Url.

    protected function _getFilterRoute($statusFilter = 'all')
    {
        $routeMatch = $this->router->match($this->request);
        if (in_array($statusFilter, $this->allowedFilters)) {
            $routeMatch->setParam('status', $statusFilter);
        } else {
            $routeMatch->setParam('status', 'all');
        }
        return $this->router->assemble(
            $routeMatch->getParams(),
            array('name' => $routeMatch->getMatchedRouteName())
        );
    }

Finally, in the __invoke method, the returned Url is passed as the value of a view parameter, activeFilterLink, and the rendered view template is returned.

    public function __invoke($searchPlaceholder, $newItemName, $newItemRoute)
    {
        return $this->getView()->render($this->viewTemplate, array(
            'activeFilterLink' => $this->_getFilterRoute(
               $statusFilter = 'active'
            ),
        ));
    }

So now, using a limited amount of custom code combined with the right objects and methods available in Zend Framework 2 and I can dynamically adjust an existing route on the fly. One last thing – the code sample will be up on the Malt Blue Github repository soon. Just need a bit more time.

Over To You

What do you think? Have you encountered a situation that could do with the solution presented in today’s post? Is there a simpler way that I’m overlooking (or haven’t learned yet)? Tell me today – share your thoughts, ideas and opinion in the comments!

Need help learning Zend Framework 2?

If you need a hand learning this amazing framework – you’re in luck. I’m actively working on a new Zend Framework 2 book, called Zend Framework 2 – For Beginners. Sign up today and be notified as soon as it’s ready. Plus – get samples and spoilers while you wait.

image copyright idvsolutions

Related Posts

• Zend Framework 2 ServiceManager – Web Application Development Simplified
• Zend Framework 2 Event Manager – A Gentle Introduction
• Zend Framework 2 Modules – The Application’s Heart
• Zend Form Mastery with Zend Config – Part 1 Custom Filter Paths
• How to Use the Zend Form ViewScript Decorator In All Modules

Don’t be part of that statistic

Like many of us, despite being told repeatedly how great testing is, the benefits it will bring, the time it will save and how it will improve the quality of my applications, I too considered testing a second-thought.

I saw it as something which was both expensive and time-consuming. If I was genuine with you, I’d say I believed it be be nothing more than a “nice to have”, after the application was written. If you also feel (or have felt) this way – know that you’re not alone.

What made it even more difficult for me, was hearing people regularly reinforcing these false and ultimately costly assumptions and beliefs. I’d start to get excited about it, only to hear a variety of the following phrases:

• Testing is too expensive
• Testing is too time consuming
• It’s too difficult
• It will take time away from real development
• The client’s not prepared to pay for it

So, possibly sadly, it’s only in recent times that I’ve started getting involved with TDD, BDD and related techniques.

But it’s never too late to begin!

 Testing Can’t Be an After-Thought

It’s treated as an after thought, a nice to have, an academic or utopian ideal that really can’t or doesn’t exist in the real world. Yet people wonder why projects regularly over-run both on cost and time and countless hours are spent bug fixing. The net result is we have a botched reputation and the joy of development saps away somewhere to die.

However, what’s reassuring to me is that the more I look around recently, the more projects I see that have testing not only as a serious going concern, but as an integral part of the development mindset.

As a result it becomes a natural part of the development process. It becomes integrally interwoven in the mindset of the application. If you’ve not seen them, here’s a small selection:

• Zend Framework 2 (integrated PHPUnit and Zend Test)
• jQuery & Node (Mocha, QUnit, should.js, expect.js, chai, better-assert)
• Grunt
• Silex
• Symfony

But It’s Not Always Easy

If you’re on the Malt Blue mailing list, you’ll know that recently I’ve undertaken a new Zend Framework 2 based project. In that project, I’ve been determined to correct my bad development habits and really take on a test-centric approach to development.

But as the saying goes the road to hell is paved with good intentions. And so it seemed at first with the project. There I sat, all excited to be testing, testing, testing. And at first, all seemed well.

Then it became difficult. I’d write loads of tests, for a range of components all at once, run the test and be faced with a litany of failures, across a range of different components. I’d start working through them, find more, fix them, find more and so on.

In the last post here on the blog I expressed my sense of dismay at the stress that was resulting from it all. Luckily, I am fortunate to have a very educated, wise and calm testing mentor in the form of a former colleague and friend.

Through much time, chatting on Skype, he gave clear guidance in how to approach it. I’ll skip over the full conversation but give you this one gem that he gave me.

Write just enough tests to test the smallest part of functionality, then implement the code and retest until it the tests pass.

A Simple Test Perspective

With that change of perspective, instead of trying to build the controllers, entities/models and related components, I took on a simpler approach, which is painlessly simple to follow. The image below describes it best.

I decided to just start building entities alone. I began afresh, writing a test first, then adding code to the entity accordingly. No more, no less.

Then, when the entity was complete, I built the form that would use the entity. I wrote tests first, then the coded the form itself. Following this, I built one or two TableGateway classes, as that’s what I’m using (maybe Doctrine on another project).

This change brought about a rapid escalation in productivity. Doing one thing well, then another, then another, produced great progress.

Was it Practically Working?

After a while however, I started to doubt the validity of what I was producing. It was great that I had all these tests for the individual components. But how would they go when they were bound together later on.

With a pressing deadline, I was rather concerned that maybe I was in the grip of an engrossing illusion. I held fast, thinking that no, this was a new path, one I’d not trodden down much before. I can’t just stop because I feel slightly uncomfortable or unsure.

But later the concern returned. So this time, I put the testing on pause and thought:

I’ll put one entity, form and table gateway together and just see how it goes

So, using the wonderful ZF2 service manager (for sakes of simplicity), I did just that.

I can’t express the amount of relief, joy, happiness and satisfaction I felt as I looked at what was rendered in the browser and how it operated. It 100% matched the mocked world of the tests which I’d been creating.

One fear still remained though:

Was the application development time, in some way increased, because of the time spent writing the tests?

In answer to you, initially it felt and still does in part, feels that way. But I believe I’m seeing a better placement of effort. I like to compare it to the anecdotal experiences of Windows and Linux systems administrators.

With Windows, you can seemingly get a system up and running quickly, but may spend a lot of time with it later. With Linux (and speaking from personal experience), you may spend a lot of time at first, doing a lot of things, but when it’s done, it’s done.

Just leave it, monitor it occasionally and it will just keep on humming. Now no, this isn’t a true and accurate reflection of reality, but the sentiment is correct. My experience can be summed up in one word.

Confidence

• Confidence that what I’ve made works as intended
• Confidence that when code is shipped it will work
• Confidence that the time spent in development, is not wasted (or just a downpayment on time to be spent later)

There’s phrase that also fits – Peace Of Mind.

When we’re working for others, but especially more so when we’re private freelancers, both us and our clients need peace of mind. If you aren’t confident that your code works (arrogance is no compensation), then how can we be sure what we give to our clients works?

How do we know that they won’t ring us up in the middle of the night, days, weeks or months later with a “seemingly random” bug. How do we know that the relationship that is so important, will grow and prosper.

In short, how can we rest assured that when we believe we’re finished (and grab that beer) that we actually are? I hear the questions coming already:

• What if you haven’t tested everything?
• What if the tests you wrote are wrong?
• What if you didn’t’ think of certain edge cases?

These are all valid questions, each and every one. And they will all happen from time to time. But the key take away from this article, is that at least by having tests, we’re in a much stronger position. If we find bugs, we add in regression tests, fix the error and move on, having tests in place to catch that.

Balance

This leads me to the last part of today’s post – balance. Testing can be just like a shiny toy. Once we have it, we want to do everything possible with it. So much so that we spend more time writing tests, even for situations where it’s not necessary to have them.

So, whilst I’ll be writing more about testing from now on. I encourage you to maintain a sense of balance. Integrate testing as an essential part of your development mentality and process – but don’t get carried away.

Do what you need first, then gradually build over time. With time and experience, you’ll find a natural level that suits both you and your specific project.

Over to you

So I’ve told my story and hope I’ve convinced you why testing won’t cost, but will save you time, stress and money. Tell me your story. What is it like in your organisation, your team, your job? Is testing taken seriously, is it integral to the development process, how much time does it save you. Share your thoughts in the comments.

Need Help?

If you’re new to testing, unsure about how to get started or the best approach to take, email me today. Better yet, Skype me. I want to help you integrate testing in to your applications, so that you’ll see the same productivity gains that I have. You won’t know yourself when you do.

image credit: thefangmonster

Related Posts

• Hassle Free Software Development
• PHP Needs Better Beginners
• Reflections on PHP Application Deployment + 1 More
• Do you REALLY know how to talk to your development team?
• Being Organised helps you work Best!

More Work != More Productivity (and Satisfaction)

Recently, I’ve felt rather under the pump to get through a series of client projects (lucky me you may say). There has been a lot to do, to organise, to plan and, ultimately to balance.

Whilst I’ve been a web application developer for over 12 years, I still found myself feeling overwhelmed and eventually having to deal with anxiety and stress, which if left unattended may have lead to burnout.

I had the thought, as is common in a western-based mentality, that to be busy, to be industrious, to try and multi-task a series of independent tasks and projects simultaneously was the right thing to do. It’s meant to be a simple formula:

1
Greater productivity = Greater self-worth right?

Sounds almost like Thatcherism.

I felt that this was not only right, but the sign of an intelligent and sophisticated developer, who truly had honed his craft. Perhaps you’ve felt the same at one time or another?

How about this – have you been offered an enticing project? One that gives you the ability to expand your knowledge of the subject matter (such as accounting, advertising or physics); one that challenges you to create a rather sophisticated and intelligent design, ultimately resulting in a very remarkable application for the client or organisation?

I’m sure, if you’re anything like me, you have and that it set your mind racing. You thought:

“I’ll create it around a set of modules. Those modules will have a set of sub-interdependent parts, which will intern interact seamlessly with related, external, services – and it will be AMAZING“.

Well, that was me. I did just that. This excitement, lead me to try do everything all at once. I was trying to create tests for forms, entities, controllers all at once.

However, instead of brilliance, this resulted in extreme stress and anxiety as well as a substantial workload. As a result I decided to stop, think and ultimately take a different approach. If this was the first time, I may well not have.

The New Approach

It takes many forms, but said most succinctly, it’s an idea that I’m sure you’re heard at least one time: Keep It Simple Silly. Yes, KISS.

Instead of trying to do everything at once – I stopped and decided to only do one thing at once. And that one thing, had my full attention and focus. When it was done, I then moved on to the next one. Not before and not after.

Why? Well have you heard the answer to the question – How do you eat an Elephant? If not here it is – one bite at a time.

Will It Work

At this stage, I’m not sure how this new approach will go. But I’m hopeful of what the results may be. The best thing is, one of my active projects will be acting as a test subject. So I’ll get to see how it goes.

As a bit of background – it’s a Zend Framework 2 based project. Whilst it’s not, technically, that complex, the amount of forms, entities, validators, filters, modules, controllers, actions and relationships within the components of the application, make it both complex and time intensive to complete.

As an aside: I’m confident that a good use of the Module Manager and Service Manager in zf2 will help make code easier to write and more maintainable. I’ll be blogging on the results, as well as how using database views reduces application complexity, over the coming weeks.

For the remainder of this project I will be following this new motto – doing one task at a time and doing it well. No more, no less. This doesn’t reduce the workload, but it should make it easier to manage.

I’m hoping that it will not only produce a better result than my previous approach and also one that will result in more satisfaction, less stress, and overall a better work/life balance – along with a happy client.

Over to you

Do you attempt to take on too many projects, or too many tasks, at the one time? Do you believe that results in better developed applications, greater satisfaction and happy clients?

If you’re honest with yourself now, is it working for you? Or would a simpler approach be more beneficial?

I leave this question with you and hope you’ll give your input today.

Image credit Erving_Lau

Related Posts

• Being Organised helps you work Best!
• The 5 Pillars of Successful Software Development
• 5 examples of good developer documentation
• Writing a secure, RESTful service in the Zend Framework, Part 2
• 5 Reasons Coding Standards Are Essential

I know for myself, on the web application projects which Malt Blue is currently undertaking, I need to be able to develop them as quickly and flexibly as possible, to help ensure project budgets and timelines are not overrun.

However, given the amount of options, configurability and flexibility required, this isn’t always easy. With Zend Framework 2, I believe the contributors have made some very worthy improvements, which help forms become the first class citizens they need to be.

In today’s post, I’m going to assume you have a basic understanding of how forms work now. So if I skip over any aspect of theory you’re not familiar with, there will be a number of links in the further reading section to help you.

I’m going to show you how to create flexible, reusable forms in one module and by the power of the ServiceManager reuse them throughout your application. Sound fun? Great. Let’s get started.

Setting Up Dependencies

One thing I need to mention is, though quite subtly, the form that we’re creating will be extending the ProvidesEventsForm class provided in ZfcBase. The simplest way to get it is to make it available is via ZfcUser in Composer. So, in your project’s composer.json file, add the following:

"require": {
    ...
    "zf-commons/zfc-user": "dev-master",
    ...
}

Then run the following to bring in the module to your vendor directory:

composer update

Under the vendor directory, you will have a new directory, zf-commons and under it, two directories: zfc-base and zfc-user. Enable ZfcBase in your application by adding ‘ZfcBase’ to the modules section of your config/application.config.php file. We now have all of the dependencies we need.

Creating the Reusable Module

The first thing we need to do is to create our new module. For simple nomenclature, let’s call it ContentCore. Whether by hand or with the assistance of ZF Tool, create a new module with the following structure:

• ContentCore
  • config
    • module.config.php
  • src
    • ContentCore
      • Entity
        • User.php
      • Form
        • UserFieldset.php
        • CreateUser.php
  • Module.php

This structure provides the basic requirements of a module, which are the Module.php file and the config/module.config.php file. Then we have the User class under Entity and two further files under Form.

I’ve skipped along a bit here; but what we’re going to do is to do minimal work in each section. The form will provide the form infrastructure, along with a submit button and CSRF security field.

The UserFieldset will handle rendering the Entity elements, stipulating the field types, options and validation rules. Finally, the Entity class will store the information passed through to the form by the user. Let’s now get in to the nitty gritty of each one.

The Entity Class

The entity class allows us to model and manipulate information the object requires. As you can see below, it has three properties:

• UserId
• firstName
• lastName

It’s fair to say this object can be mapped to a record in a database, but it needn’t be. It has two methods:

• exchangeArray
• getFullName

exchangeArray allows data from an external source to be mapped to the internal properties of the object. getFullName returns the full name of the user, like a contact list would, i.e., first name then last name or vice versa.

namespace ContentCore\Entity;
class User
{
    CONST DISPLAY_NAME_FIRSTLAST = "firstLast";
    CONST DISPLAY_NAME_LASTFIRST = "lastFirst";
    public $UserId;
    public $firstName;
    public $lastName;
    public function exchangeArray($data)
    {
        $this->UserId = (isset($data['UserId'])) ? $data['UserId'] : null;
        $this->firstName = (isset($data['FirstName'])) ? $data['FirstName'] : null;
        $this->lastName = (isset($data['LastName'])) ? $data['LastName'] : null;
    }
    public function getFullName($displayOrder = self::DISPLAY_NAME_FIRSTLAST)
    {
        if ($displayOrder === self::DISPLAY_NAME_FIRSTLAST) {
            return sprintf("%s %s", $this->firstName, $this->lastName);
        } else {
            return sprintf("%s %s", $this->lastName, $this->firstName);
        }
    }
}

Overall, nothing too difficult here.

The Fieldset Class

In the UserFieldset class, it gets a bit more difficult. Fieldsets are a way of grouping logically related elements and being able to dynamically share them between different forms.

The setObject method is used so the fieldset can extract from and set information supplied in the User object we just talked about. The setHydrator method, receiving the ObjectPropertyHydrator object is used to work with the User object.

If you’re not familiar with Hydrators, the Zend Framework 2 manual describes hydration as:

Hydration is the act of populating an object from a set of data.

There are a number of hydrators available. The ObjectPropertyHydrator is able to look at the properties of the entity provided, to know which values to populate in the form. I used this one to avoid writing specific methods.

Consequently, the entity properties and the form field element names need to match up. Your approach may differ. I’ll work through the class a bit more now.

use ContentCore\Entity\User;
use Zend\Form\Fieldset;
use Zend\InputFilter\InputFilterProviderInterface;
use Zend\Stdlib\Hydrator\ObjectProperty as ObjectPropertyHydrator;
class UserFieldset extends Fieldset
    implements InputFilterProviderInterface
{
    public function __construct()
    {
        parent::__construct('User');
        $this->setHydrator(new ObjectPropertyHydrator(false))
             ->setObject(new User());

This sets the label in the fieldset element.

        $this->setLabel('User');

Here we add two elements to the fieldset, specifying the name, options and attributes. As we’ve not set a specific type, the element will be rendered as a standard text field. If you want, specify any other in-built or custom one you like. Have a look under Zend\Form\Element for the in-built options available.

        $this->add(array(
            'name' => 'firstName',
            'options' => array(
                'label' => 'User\'s First Name'
            ),
            'attributes' => array(
                'required' => 'required'
            )
        ));
        $this->add(array(
            'name' => 'lastName',
            'options' => array(
                'label' => 'User\'s Last Name'
            ),
            'attributes' => array(
                'required' => 'required'
            )
        ));
    }

As the class implements InputFilterProviderInterface, it needs to implement the getInputFilterSpecification method. This specifies the validation rules for the fieldset.

I’ve just kept these relatively simple. However, you could get quite complex if you like. You can see all I’ve specified are that both the firstName and lastName fields are required. What other options would you consider specifying?

    /**
     * @return array
     */
    public function getInputFilterSpecification()
    {
        return array(
            'firstName' => array(
                'required' => true,
            ),
            'lastName' => array(
                'required' => true,
            )
        );
    }
}

The User Form

Now unless it’s not clear so far, it should become so rather quickly. The reason why I’ve decided to use Fieldsets is because with them, I can group together logically related form elements, along with related requirements for them, then pass them in to any form I create later.

In building Zend Framework 1 applications, I spent a lot of time with XML-based configurations and field groups with the intent of doing this. But to be honest, it was all rather a lot of overhead and work. Forms in Zend Framework 2 make this tremendously simpler.

use Zend\Form\Form;
use Zend\Form\Element;
use ZfcBase\Form\ProvidesEventsForm;
use Zend\InputFilter\InputFilter;
use Zend\Stdlib\Hydrator\ObjectProperty as ObjectPropertyHydrator;

Though I’ve not done anything with it, my CreateUser form extends ProvidesEventsForm from the ZfcBase module by Evan Coury.

This sets up a form so it’s EventManager aware. Other objects can now register to respond to events this form can trigger during its lifecycle. Perhaps you might want to send a tweet or email after information has been saved or updated?

class CreateUser extends ProvidesEventsForm
{
    public function __construct()
    {
        parent::__construct('User');
        $this->setAttribute('method', 'post')
             ->setHydrator(new ObjectPropertyHydrator(false))
             ->setInputFilter(new InputFilter());

We make the fieldset available to the form, which will render the elements it contains

        $this->add(array(
            'type' => 'ContentCore\Form\UserFieldset',
            'options' => array(
                'use_as_base_fieldset' => true
            )
        ));

As a base form contains no elements by itself, we now add two: a Csrf field and submit button. The Csrf field will contain an auto generated token to ensure the form submission was not spoofed.

        $this->add(array(
            'type' => 'Zend\Form\Element\Csrf',
            'name' => 'csrf'
        ));
        $this->add(array(
            'name' => 'submit',
            'attributes' => array(
                'type' => 'submit',
                'value' => 'Send'
            )
        ));
    }
}

With that, our form is complete. Now let’s take it a step further and make the form available anywhere in our application.

The Module Configuration

Under ContentCore\Module.php, first add the following use statements, so all of the definitions are available.

use ContentCore\Entity\User;
use ContentCore\Model\UserTable;
use Zend\Db\ResultSet\ResultSet;
use Zend\Db\TableGateway\TableGateway;

Then, in getServiceConfig, add the following definition. What this will do is to make available a key in the ServiceManager, which references an instantiated copy of the form we’ve just setup.

public function getServiceConfig()
{
    // ...
    return array(
    'contentuser_create_user_form' => function($sm) {
        $form = new Form\CreateUser();
        return $form;
    },
    // …
}

The Application Configuration

Now all of this work is nothing, if we don’t enable the module in the application. So in config/application.config.php, add the following under ‘modules’ at the top of the file.

'ContentCore',

The Application Controller Action

Right, so now we have our form setup, it’s available throughout the application via the ServiceManager and the module’s enabled in our application. Let’s get about using it in our controller action.

I created a trivial function formtestAction, in the IndexController class which comes with the default Application module to accommodate this.

You can see below I have three functions and a protected member variable. The member variable will contain the form, just to make things a bit simpler. The _getCreateUserForm function checks if the variable is defined.

If not, it retrieves a copy of the form via the ServiceLocator using the string we defined earlier and calls setCreateUserForm. Otherwise, it returns the form in createUserForm.

protected $_createUserForm;
protected function _getCreateUserForm()
{
    if (!$this->_createUserForm) {
        $this->_setCreateUserForm(
            $this->getServiceLocator()->get('coalescentuser_create_user_form')
        );
    }
    return $this->_createUserForm;
}
protected function _setCreateUserForm(\Zend\Form\Form $createUserForm)
{
    $this->_createUserForm = $createUserForm;
}

The last function, formtestAction, calls _getCreateUserForm and binds a new User entity to it. As mentioned earlier, this takes care of retrieving information from and persisting information in the User entity.

We then check if the request was a post, set form data from the post request information and run the form validation routine. There’s nothing special here and I’ve deliberately not fleshed out the steps after a successful validation.

The action finishes up by returning a ViewModel with one property, our form. This, in my mind, is a lot simpler than the approach Zend Framework 1 Forms took. It requires less code and is simpler to understand. In short, irrespective of the state of the form, one line makes it available to our view template.

public function formtestAction()
{
    $form = $this->_getCreateUserForm();
    $User = new User();
    $form->bind($User);
    if ($this->request->isPost()) {
        $form->setData($this->request->getPost());
        if ($form->isValid()) {
            // take action
        }
    }
    return new ViewModel(array('form' => $form));
}

The View Template

Ok, last piece in the puzzle – the view template. Please make a special note of the prepare method call. If you miss this, you’ll be scratching your head wondering why things don’t work. What this does is to:

ensure validation error messages are available, and prepares any elements and/or fieldsets that require preparation.

<?php $form->prepare(); ?>

Next, we use the form helper to open the form, retrieving properties from the form object.

<?php echo $this->form()->openTag($form); ?>

We then get access to the user fieldset, so we can use the formRow helper to render the elements for the firstName and lastName.

<?php $User = $form->get('User'); ?>
<?php echo $this->formRow($User->get('firstName')); ?>
<?php echo $this->formRow($User->get('lastName')); ?>

We then finish up by rendering the csrf and submit elements and close the form.

<?php echo $this->formHidden($form->get('csrf')); ?>
<?php echo $this->formInput($form->get('submit')); ?>
<?php echo $this->form()->closeTag($form); ?>

In Conclusion

We’ve now stepped through the process of creating a form, based on an entity which’s reusable anywhere in our application. I hope you can see forms truly are first class citizens which, combined with the Service Manager, have a tremendous amount of flexibility, configurability and reusability.

I appreciate it was rather a rapid discussion of the building blocks of the process. So if you need any further information about what was covered here – let me know in the comments.

Also, tell me in the comments how you’re using forms in your Zend Framework 2 applications? What novel and innovative ways are you approaching them?

Further Reading

• The Zend Framework 2 ServiceLocator
• Zend Framework 2 Hydrators
• Zend Framework 2 Forms Introduction
• Understanding Zend Framework 2 Modules
• Understanding the Zend Framework 2 EventManager
• Understanding the Zend Framework 2 ServiceManager

featured image, credit Brian J Bruemmer

Related Posts

• How to Build Extendable and Extensible Zend Framework Applications with Custom Resource Plugins
• Zend Form Mastery with Zend Config – Part 4 Configuring Zend Validators
• Zend Form Mastery with Zend Config – Part 1 Custom Filter Paths
• Zend Form Mastery with Zend Config – Part 3 Standard Form & Element Options
• Zend Form Mastery with Zend Config – Part 2 Core Form Configuration

If you don’t, you’re buying yourself and others a world of pain – which is painlessly simple to avoid.

Today I’m banging the drum, shouting from the street corner, calling from the cathedral spire, imploring you to do one thing, above all else – pick a coding standard and then BE CONSISTENT!

I don’t care if you hate standards, I don’t care if you think all of them are flawed, I don’t care if you feel locked in, chained up, with all your creativity is stifled.

Because if you think this way – You’re Wrong.

Poor, Inconsistent Code – Causes You Pain

I used to think this way but saw the, proverbial, light. Why am I banging on so hard today? At Malt Blue, I have the joy of working on a wide range of freelance web application projects, both big and small.

However a recent project I took over gave me reason to pause. This project, had a lot going for it. It seemed to have had good intent with the basics of a meaningful design behind it. It had potential to be something really worthwhile. It could have been a maintainable project which wouldn’t have ended up costing the client quite a lot of money to support.

Unfortunately, a number of things were done wrong, the key being inconsistency. This led to a series of problems in the code, which I’ll summarize for the sakes of brevity. The are as follows:

• Extremely time consuming to get to grips with the code base
• Code was not intuitive or semantically meaningful
• It was hard to see what linked to what – and more importantly – why
• Time was required to be spent re-reading the same blocks repeatedly for understanding
• Very difficult to tell where to find relevant sections of code

Here’s some examples of what was encountered:

• The code base was littered with large swathes of commented out code
• SQL queries were written using a DB abstraction layer, then later composed manually
• Variables and configuration options were named “my”, “m”, “last” and so on
• Multiple functions, with different names, in different modules performed nearly identical functionality
• Operations were performed in segments of code, multiple layers deep, with no semantic direction

To cut a long story short, countless hours were spent, searching, tidying, documenting, trying almost in vain, to understand a code base needlessly.

If the earlier developers would have adhered to a coding standard, not to be confused with a coding style, a lot of this could have been avoided.

Now I know some people hate coding standards. But if they want to waste time, both theirs and others, I never want to work on their projects.

So find a standard which works for your business, your organization – you – and stick to it ardently. I don’t care which one you adhere to (within reason) – so long as you adhere to one.

There are a wide range of standards to choose from. Personally I use the Zend Framework coding standard as I primarily work on Zend Framework-based projects.

But if you have another one, such as Pear, GNU, Symfony, even WordPress, make sure you know why, or if you’re in a team, you’re all in agreement and then make sure you adhere to it.

Now that I’ve had a rant, here’s the benefits they provide:

Your Code is Easier to Read

When you use a standard, your code is readable, both to you and others. Why, because it’s consistent. Now, it might not be the best standard, but at least, in a short period of time, you will be able to follow the flow.

Take the following code for example. To some it may seem trivial. But if you imagine this throughout a code base (even with a formatter in an IDE or script) this code is hard to read. Let’s leave out the obvious spelling mistakes

/**
 * @var array
 */
protected $_messageTemplates = array(self::OBJECT_CATEGORY_NAME_EXISTS_INSERT => '"%value%" is already chooosen. Pleas select another.',
        self::OBJECT_CATEGORY_NAME_EXISTS_UPDATE => '"%value%" is already chooosen. Pleas select another.',
);

Your Code is Easier to Understand

This is perhaps the biggest point for me. Whether it’s the variable naming convention or otherwise, the intent of your code is easier to follow. Take the following example:

/**
 * @var array
 */
protected $_messageVariables = array(
        'nice1' => '_nice1',
        'nice2' => '_nice2'
);
//...
public function eventContact($value, $niceName, $params = null)
{
    $this->_nice1 = $params[0];
    $this->_nice2 = $params[1];
    $this->_setValue($value);
    if ($this->_value == '' && $this->_nice1 == '' && $this->_nice2 == '') {
        $this->_error(self::MISMATCH);
    }
    return self::$_instance;
}

I’m not a rocket scientist or a Rhodes scholar, but neither am I unintelligent. But I can’t infer what nice1 and nice2 are meant to be for.

Can you? What do you think the class it was in may have been doing? Here’s a tip, it was for validating contact information.

Your Code is Easier to Maintain

From a model class in the same code base, here’s another example:

final public function query($query)
{
    return $this->_db->query($query);
}
final public function select()
{
    return $this->_db->select();
}
final public function fetchAll($select)
{
    return $this->_db->fetchAll($select);
}
final public function fetchRow($select)
{
    return $this->_db->fetchRow($select);
}
final public function fetchPairs($select)
{
    return $this->_db->fetchPairs($select);
}

The class constructor initializes a protected member variable, _db, with the application database connection, which these functions use. However, they’re doing nothing more than wrapping internal functionality. Here is another example:

final class My_Enums_DateFormat {
    const MYSQL_DATE_TIME           = 'Y-m-d H:i:s';
    const MYSQL_DATE                = 'Y-m-d';
    const ADMIN_NICE                = 'j M Y h:i:s A';
    const DAY_MONTH_YEAR_HOUR_MIN_SEC   = 'd/m/Y H:i:s';
    const MONTH_DAY_YEAR_HOUR_MIN_SEC   = 'm/d/Y H:i:s';
    const MONTH_DAY_YEAR_HOUR_MIN_SEC_MERIDIAN  = 'm/d/Y h:i:s A';
    const DAY_MONTH_YEAR                = 'd/m/Y';
    const MONTH_DAY_YEAR                = 'm/d/Y';
    const HOUR                      = 'H';
    const MINUTE                    = 'i';
    const MERIDIAN                  = 'A';
    const SMALL_HOUR                = 'h';
    const FRONT_END_NICE            = 'F j, Y';
    const MYSQL_TIME                = 'H:i:s';
    const ADMIN_TIME                = 'h:i:s A';
    const TIME                      = 'g:i a';
    const TWENTY_FOUR_HOUR          = 'Hi';
    const DOWNLOAD_DATE             = 'Ymd';
    //...
}

This doesn’t strictly fall in to the above category – more in to the DRY. However, what is the purpose of writing code which replicates existing functionality, i.e., PHP DateTime, Zend Date et al? Why would you do this?

Why would you write functionality yourself which already exists, has a range of high quality unit tests, has had 10′s, 100′s or 1000′s of eyes on on it, verifying its quality, holding it up to scrutiny?

Please don’t do this – unless there’s a really good reason for it.

Your Code is Easier to Collaborate On

As a result of all of these points, code is harder to collaborate on. Why? If it’s hard for one person to work on a code base without wondering where errors might turn up, extrapolate it over a team of 2, 3, 5 or more.

With clean code and a clear and concise standard which’s adhered to, at the very least ensures if you’re going to write rubbish code, it’s clear rubbish.

When you don’t though, as I’m sure you don’t you’re well on your way to building high quality, maintainable code, now and in to the future.

What are Your Horror Stories?

You’ve heard mine, now I want to hear your worst experiences. What have you encountered? More importantly, what have you done about it? Was it too hard to overcome or was it manageable?

Share with us all in the comments today. The best (or is that worst) story gets a free copy of the next edition of PHP Architect magazine.

image copyright marsmet481

Related Posts

• How Simplicity Leads to Greater: Productivity, Quality & Satisfaction
• A big thank you to Mayflower GmbH
• 11 Reasons Why a PHP Framework is better than Raw PHP
• What Is a Professional PHP Freelancer?
• 11 Reasons Why Raw PHP is better than a Framework

• Part 1 – Zend Framework 2 Core Concepts – Dependency Injection
• Part 2 – Zend Framework 2 Modules – The Application’s Heart
• Part 3 – Zend Framework 2 Event Manager – A Gentle Introduction

Summary

The Zend Framework 2 Service Manager simplifies web application development in a number of ways, primarily by making configuration a breeze. In this, the 4th post introducing Zend Framework 2, you will learn what the ServiceManager is, how to use it and how it simplifies app development time.

Getting Started

Welcome to the Zend Framework 2 Introduction 4-part series finale. Recapping the series so far:

• In part one, we went through Dependency Injection (DI)
• In part two, we looked at Modules and the ModuleManager
• In part three, we looked at the EventManager

In this, the fourth and final installment, we look at the ServiceManager component. This is a highly critical, but potentially misunderstood, aspect of the framework. One that, when understood, makes the rest of the framework a breeze (well, close).

From reading various blog posts and comments, it’s often believed that the ServiceManager over-complicates the entire framework. Some people say it’s an attempt to: out Java Java.

I – completely – disagree!

I believe that it’s this fundamental concept that makes the framework simpler, that makes developing web applications with it easier, less stressful and more maintainable. I hear scoffing, I hear peals of laughter, I hear the embers of a flamewar being stoked to burn me alive at the stake.

To support my point, in this post, I’m going to do 3 things:

1. Give you a good introduction to what the ServiceManager is
2. Show you how to configure it
3. Step you through a hands-on example of using it

Stay on to the end as we consider the critical question.

What is the ZF2 ServiceManager

Put in simplest terms, the ZF ServiceManager component is an implementation of the Service Locator pattern; in short a simple application registry that provides objects (in a lazy loaded fashion) within application as needed – but with some nice additions.

It allows us to perform Inversion of Control (IoC), which allows us to remove dependencies and tight coupling from our applications. The result of this, when combined with dependency injection and simple event management is applications that are simpler to build, test and maintain.

You can try to think of it in more complex ways if you’d like to, but really there’s no need. Where it does get a little complicated however, at least initially, is how it’s all configured. I grant you, that does take a bit of getting your head around – but not too much.

How Do You Configure It?

The Service Manager is able to be configured in 7 key ways. These are:

• abstract factories: This is one of a fully qualified class name, or an object implementing Zend\ServiceManager\AbstractFactoryInterface. This approach provides flexibility and extensibility to the ServiceManager. If, on request, the ServiceManager isn’t able to locate a class, it iterates through the registered Abstract Factories to see if any of them are able to satisfy the object request.
• factories: A fully qualified class name, PHP callable object, or a class implementing Zend\ServiceManager\FactoryInterface. These handle the dependency injection aspect of the ServiceManager.
• invokables: A string, which is a fully qualified class name, able to be instantiated later.
• initializers: A fully qualified class name, PHP callable object, or a class implementing Zend\ServiceManager\InitializerInterface. If listed, will be applied to objects retrieved from the Service Manager to perform additional initialization.
• configuration classes: This is a class implementing Zend\ServiceManager\ConfigInterface. Classes implementing this interface are able to configure the Service Manager, performing the initialization that is covered in these seven points.
• aliases: An associative array of aliases to services (or aliases to aliases). It may not seem like a good idea, but from a readability perspective, I believe this is an excellent technique to have available.
• shared: Depending on your application or circumstance, you may want to provide single access to an object, or return a new copy on each request. By default, when an object is retrieved from the Service Manager if it’s the first request, the object is instantiated and returned. If it’s any after that, the original object is returned.

What’s really great about this approach, is that each module loaded or created can also be a service provider. To do so, they need to do one of the following:

1. Implement the Zend\ModuleManager\Feature\ServiceProviderInterface
2. Implement getServiceConfig()

As the manual indicates, this function needs to return:

1. An array or Traversable object
2. The name of a class implementing Zend\ServiceManager\ConfigInterface
3. An instance of either Zend\ServiceManager\Config, or an object implementing Zend\ServiceManager\ConfigInterface.

A Simple Code Example

I’ve been creating a Generic module throughout this series and in it, I’ve added a simple model that lets me retrieve information from a SQLite database. So what better choice to use for an example that that.

In module/Generic/Module.php, I have an implementation of getServiceConfig which is as follows (formatted for readability):

// Add this method:
public function getServiceConfig()
{
    return array(
        'factories' => array(
            'Generic\Model\AlbumTable' =>  function($sm) {
                $tableGateway = $sm->get('AlbumTableGateway');
                $table = new AlbumTable($tableGateway);
                return $table;
            },
            'AlbumTableGateway' => function ($sm) {
                $dbAdapter = $sm->get(
                    'Zend\Db\Adapter\Adapter'
                );
                $resultSetPrototype = new ResultSet();
                $resultSetPrototype->setArrayObjectPrototype(
                    new Album()
                );
                return new TableGateway(
                    'album',
                    $dbAdapter,
                    null,
                    $resultSetPrototype
                );
            },
        )
    );
}

You can see here I’m configuring it with the ‘factories‘ option. In there I have two options:

• Generic\Model\AlbumTable
• AlbumTableGateway

Both of these use anonymous functions for the configuration. Now, let’s pop over to where they’re used in the IndexController. The default action, Index, goes as follows:

public function indexAction()
{
    return new ViewModel(array(
        'albums' => $this->getAlbumTable()->fetchAll(),
    ));
}

It calls the getAlbumTable method, which is as follows:

public function getAlbumTable()
{
    if (!$this->albumTable) {
        $sm = $this->getServiceLocator();
        $this->albumTable = $sm->get('AlbumTableGateway');
    }
    return $this->albumTable;
}

Now that we have the configuration and usage together, let’s see how it works. In indexAction, we set a variable ‘albums‘, which is the result of calling the fetchAll method on the object returned from the getAlbumTable method.

In the getAlbumTable method, we retrieve a copy of the application Service Locator object via the getServiceLocator method. We then retrieve the AlbumTableGateway object, by passing the name, as a string, to the get method of the Service Locator object.

Assuming the object is in the Service Locator registry and suitably configured, it’s then passed as the return value from the function, allowing us to call the method on it.

Looking back in to the configuration of the object we see it as follows:

'AlbumTableGateway' => function ($sm) {
    $dbAdapter = $sm->get(
        'Zend\Db\Adapter\Adapter'
    );
    $resultSetPrototype = new ResultSet();
    $resultSetPrototype->setArrayObjectPrototype(
        new Album()
    );
    return new TableGateway(
        'album',
        $dbAdapter,
        null,
        $resultSetPrototype
    );
},

We see we have a factory configuration, labelled AlbumTableGateway configured by an anonymous function.

You can see we first we use the ServiceManager to get access to the application-wide database adapter (I’ll cover it in a sec), by retrieving the object configured with the string Zend\Db\Adapter\Adapter.

We then create a new ResultSet object and set the prototype to be an Album object. When that’s done, we then create and return a new TableGateway object, specifying the type, database adapter and result set prototype.

Now, I’m deliberately skipping over delving in to the intricacies of the Zend_Db class here – as it’s really, a bit outside the purposes of this post. But I encourage you to give it a good read in addition to what you read here.

Now, for the final part, in config/autoload/global.php I have the following configuration:

$dbDSN = 'sqlite:' . dirname(__DIR__) .
    '/../data/databases/zf2skeleton.sq3.sqlite';
return array(
    'db' => array(
        'driver' => 'Pdo',
        'dsn'    => $dbDSN,
        'driver_options' => array(
            PDO::MYSQL_ATTR_INIT_COMMAND => 'SET NAMES \'UTF8\''
        ),
    ),
    'service_manager' => array(
        'factories' => array(
            'Zend\Db\Adapter\Adapter'
                => 'Zend\Db\Adapter\AdapterServiceFactory',
        ),
    ),
);

You can see how the Database adapter is made available, configured using the same convention – allowing me to query a SQLite version 3 database throughout the application.

Don’t forget, all code is available for download from the Malt Blue Github repository. Grab a copy of it and tell me what you think.

What We Have Learned?

This process of stepping through the configuration and usage of the ServiceManager has shown us X things:

1. Configuration Is Simple: Whilst a bit involved (because of all the locations where configurations can be located) it actually is simple because it follows a clearly defined set of conventions and stored in a standard set of locations.
2. It’s Easy to Debug: By having standard conventions and locations, we can track configurations in the application logically and systematically.
3. It Works with Across Modules: Whereas in Zend Framework 1, we had to jump through hoops to work with multiple modules, in ZF2 it’s all baked in. Just follow the conventions and it works.
4. Applications Are More Dependable: This is a bit of a reiteration of the previous points. But by being able to configure applications reliably, simpler, in a readily debuggable manner, you spend less time and effort, effort which can be spent more meaningfully in other aspects of development (and your business).
5. Easier to Maintain: When applications as more consistent, predictable, debuggable, logically (in my mind if nowhere else), they’re easier to optimise. Why? Because you’re working with a known quantity. Possibly a little “boring” but following convention makes adding new components quicker and more predictable. Being a maintainer, you know how applications hang together, you know where to look, the options which can be used, how to override them and so on.

Does it Really Make Development Simpler?

This is the burning question in this post. Does it really make web application development simpler? In short, yes. Now, at first, there’s a lot to cover, there’s a lot to learn. I grant you that.

There’s the 7 points mentioned above and you have to work with the different ways in which each work. Fine – I agree it does require work.

But think about any skill you’ve learned. Whether it was riding a bike, learning calligraphy, building running fitness, or what I’m doing – learning German.

At first it requires effort, it requires discipline and it requires concentration. It’s not easy, sure. But with time, this new skill makes doing what you used to do much simpler, such that you do more in less time, with less effort, with less concentration.

Consider the amount of work that went in to Zend Framework 1 applications and configuring them – especially integrating modules and the associated configurations.

As Evan Coury well said – they sucked!

There was the application.ini file, the module configuration that you could choose from a number of good implementations to get it to work, you could roll your own option and more.

Now, we have the option to spend some time learning, but with the result of ultimately writing cleaner applications, which are simpler to maintain both in terms of time and effort.

We’ll have applications which are much more:

• Flexible
• Testable
• Configurable
• Optimizable

I believe, therefore, it’s worth the investment of your time to learn. I believe it really is a blessing (potentially in disguise). I’m a learner, like you. So I want to know what you think, if you disagree with me. If you do, comment and tell me.

Get the Code

The code for this post – and all the posts in the Zend Framework 2 introductory series – is available on the Malt Blue Github account. I encourage you to clone a copy, play with it, comment on it, improve on it.

Over to You

Do you agree with me or want to flame me right now? If you agree with me that the ServiceManager will simplify use of Zend Framework 2, share with us how in the comments.

Alternatively, if you agree more with others, that it’s a pointless, over-complication, of what should be kept simple, say that too.

We can all grow through shared, constructive, opinions.

Related Posts

• Zend Framework 2 Event Manager – A Gentle Introduction
• Zend Framework 2 Modules – The Application’s Heart
• Why Kohana is an Excellent Alternative to Zend Framework
• Zend Form Mastery with Zend Config – Part 1 Custom Filter Paths
• Zend Framework 2 Core Concepts – Dependency Injection

• Part 1 – Zend Framework 2 Core Concepts – Dependency Injection
• Part 2 – Zend Framework 2 Modules – The Application’s Heart
• Part 4 – Zend Framework 2 ServiceManager – Web Application Development Simplified

Enjoying the introduction to Zend Framework 2? I hope so. In part one of the series, we looked at Dependency Injection, otherwise know as the Inversion of Control principle.

Then, in part two, we looked at Modules and the ModuleManager, the next key aspects. In this part, we started to work through what they are and stepped through how to build one from scratch; along with some pointers for taking them further.

In this, the 3rd of 4 parts, I’m taking you through the next key aspect of the framework – the EventManager. In today’s post, I’ll be doing the following:

1. Taking you through the EventManager key patterns
2. Looking at how it works
3. Stepping through using it with some hands on code

I know there’s a lot of theory behind each of these concepts, and the framework as a whole, but by having all of this foundation knowledge, the rest of the concepts become a whole lot simpler. Wouldn’t you agree?

So let’s get started with knowing how it works

It implements the Observer pattern

Observer pattern, credit: http://en.wikipedia.org/wiki/Observer_pattern

This is the key pattern to be familiar with when understanding the EventManager. The concept is simply this:

An application has a object, which has a registered list of observers. It performs its actions as normal and notifies the observers when a specific event has occurred. These observers are then able to take action relevant to only themselves.

On the surface of it, this is a rather simple and very effective method of looking at development, I’m sure you’ll agree. It also has several advantages. These are:

• No Monster Classes: This allows us to write code can be written with a single purpose in mind, following the Single Responsibility Principle.
• Easier to extend: So much code starts out simply, then new requests and desires appear. With the Observer pattern, it’s simple to meet both aims.
• Easier to test: Imagine trying to test a monolithic codebase, or one which has so many different needs and desires? When each part is simple, concise and decoupled, makes the job of testing far simpler.

It implements Aspect-Oriented programming (AOP)

This is one area I’m not yet totally familiar with. But it makes for really interesting reading. Wikipedia says this about Aspect-Oriented programming:

The motivation for aspect-oriented programming approaches stem from the problems caused by code scattering and tangling. The purpose of Aspect-Oriented Software Development is to provide systematic means to modularize crosscutting concerns.

The implementation of a concern is scattered if its code is spread out over multiple modules. The concern affects the implementation of multiple modules. Its implementation is not modular.

The implementation of a concern is tangled if its code is intermixed with code that implements other concerns. The module in which tangling occurs is not cohesive.

In short, I believe you can sum it up thinking about it this way: Write clean code, well organised code, with one purpose in mind. Code which doesn’t try to solve on more than one problem.

For example, if you write code which searches a datasource for information matching a query, it doesn’t attempt to render the information for the user as well.

Read this Aspect-Oriented programming series on PHPMaster for a fuller understanding.

It has an Event-Driven architecture

The following two statements from an article on Event-driven architecture show why it’s an excellent approach to take:

Building applications and systems around an event-driven architecture allows these applications and systems to be constructed in a manner that facilitates more responsiveness, because event-driven systems are, by design, more normalized to unpredictable and asynchronous environments.[2]

Event-driven architecture can complement service-oriented architecture (SOA) because services can be activated by triggers fired on incoming events.[2][3] This paradigm is particularly useful whenever the sink does not provide any self-contained executive.

To help you out a bit more, here’s an excellent, yet simple, diagram

courtesy of IBM

You can see from this definition how Event-Driven architecture, Aspect-Oriented design serve to compliment each other. And by implementing them, Zend Framework 2 allows you to write complex applications in a cohesive, yet greatly decoupled manner.

No?

Because you can write a series of components (or sub-components) all focusing on doing one, clear, task really well. These components are then linked together through listeners and are triggered (or called in to action) as needed. Not before, not after. I’d suggest this, in combination with good lazy loading makes it even simpler and more effective. Now, Matthew Weier O’Phinney may correct me here, but it seems right to me. Do you agree?

So what exactly is the EventManager?

The Event Manager is the component of the framework which allows you to hook in to named events in your application. Not so tough, right?

I’m not trying to over-complicate it (despite the lengthy introduction). In essence, it’s a pretty simple concept, nothing more nothing less. One thing I’ve been finding, as I learn Zend Framework 2, is there are a variety of ways in which you can use it can get, seemingly, complex.

Have a look at this zend framework community thread and some of the comments on MWOP’s post on ZF2′s New Controller::init()) to get an idea of current opinion.

There are an existing set of named events in the framework, such as the dispatch event in controllers. You can also create your own as suits your application’s purpose. That’s step one.

Then, you attach (or listen) to those events. When they fire – or are triggered – your code interrogates the context of the event and responds if needed.

Not bad hey? Still with me?

Now, so you have the whole picture, you can also do the following:

• Attach to many events at once: Need to listen on multiple events, such as logging the occurrence of all actions in a controller being fired? Easy.
• Detach listeners: Maybe a listener is no longer required, or not available due to a service outage. Then remove it from the list.
• Short-circuit execution: This helps you stop other listeners executing if, for example, there’s no further work to be done. It’s also handy for performance by flattening out the call stack.
• Set priorities on events: This is handy if different listeners need to fire off earlier or later in the event process. A trivial example is form validation where you want to log information before and afterwards. The higher the number, the higher it’s priority – and the earlier it will fire.

I hope you are starting to get an understanding of just how flexible this feature is. You can create simple, reusable, modular code and interlink throughout your application.

Let’s code an EventManager example

As I said there are so many possibilities – and as I’m still learning myself – I can’t do all of them justice. Tell me what you’ve done in the comments though. So what I’m going to do is to work through a few examples.

The first one is one MWOP provided in a recent post. I was looking for a way of testing the event manager and performing simple logging whenever a controller’s action fired.

In the code below, we setup the EventManager for our controller, passing in an $events object. It’s a nice starter example as it’s so self-contained. We’re self-attaching if you will.

Ok, so after we’ve composed an EventManager instance, we then attach to the dispatch event of the current controller.

Next we extract the method used for the current request (GET, POST etc). Then, we ask if the method was outside of PUT, DELETE or PATCH or if we had no id query parameter.

If either of these conditions are met, we do nothing. If either were, we are then redirected to a named route.

public function setEventManager(EventManagerInterface $events)
{
    parent::setEventManager($events);
    $controller = $this;
    $events->attach('dispatch', function ($e) use ($controller) {
        $request = $e->getRequest();
        $method = $request->getMethod();
        if (!in_array($method, array('PUT', 'DELETE', 'PATCH'))) {
          // nothing to do return;
        }
        if ($controller->params()->fromRoute('id', false)) {
          // nothing to do return;
        }
        // Missing identifier! Redirect. return
        $controller->redirect()->toRoute("generic");
    }, 100);
    // execute before executing action logic
 }

Let’s code another example

In this example, what I was trying to do was to get my own head around the process. I was working through basic ZF2 elements, such as forms, controllers, actions etc.

I’d already created a simple form, following along with the documentation on the ZendSkeleton application. The example I thought of was logging information about the form details both before and after the validation process.

So what I’m doing in the following example is to override and attach a listener to the isValid method. So here’s the relevant Form class code:

<?php
namespace Generic\Form;
use Zend\Form\Form;
use Zend\EventManager\EventManager;
use Zend\EventManager\Event;
use MaltBlue\Listener\Logging;
class AlbumForm extends Form {
  protected $events = null;
  protected $logger = null;
  public function events() {
    if ($this->events === null) {
      $this->events = new EventManager(__CLASS__);
      $logListener = new Logging();
      $this->events()->attach(
        'isValid.pre',
        array($logListener, 'logOutput')
      );
      $this->events()->attach(
        'isValid.post',
         array($logListener, 'logOutput')
      );
    }
    return $this->events;
  }
  public function isValid() {
    $response = $this->events()->trigger(
      __FUNCTION__ . '.pre', $this, $this->data
    );
    $isValid = parent::isValid();
    $response = $this->events()->trigger(
      __FUNCTION__ . '.post', $this, $this->data
    );
    return $isValid;
  }
  …
}

I’ve created an $events object and defined an events method. In the events method, I instantiate an EventManager object using the current class. I also instantiate a new Logging class, which is, to be fair, a poorly named class which logs to a file, the information available.

I attach then attach to the self-named isValid.pre and isValid.post, passing the logging class. I then override the isValid method, triggering the pre method before validation and post afterwards, passing in the form class and form data.

I don’t hold up execution or change it in anyway as you can see with return $isValid.

Now the listener class

<?php
namespace MaltBlue\Listener;
use Zend\Log\Writer\Stream;
use Zend\Log\Logger;
use MaltBlue\Listener\Exception;
class Logging {
  public static function logOutput($event)
  {
    $logdir = dirname(__DIR__) . "/../../data/logs/";
    $stream = @fopen($logdir . "logs.log", 'a', false);
    if (!$stream) {
      throw new Exception\InvalidFileException( 'Failed to open stream' );
    }
    $writer = new Stream($stream);
    $logger = new Logger();
    $logger->addWriter($writer);
    switch ($event->getName()) {
      case ("isValid.post"):
        list($id, $title, $artist, $submit) = each( $event->getParams() );
        $message = sprintf(
          "Post form validation: %s %s ", $title, $artist, $event->getParam('id')
        );
        $logger->info($message);
      break;
      case ("isValid.pre"):
        list($id, $title, $artist, $submit) = each( $event->getParams() );
        $message = sprintf(
          "Pre form validation: %s %s ", $title, $artist, $event->getParam('id')
        );
        $logger->info($message);
      break;
    }
  }
}

The function, logOutput, above receives an EventManager object and initialises a Zend Log object adding a stream writer. I then have a simple switch statement looking at the $event object.

It uses one of the methods of the object, getName, to determine what event just fired. If it’s either isValid.post or isValid.pre, then it takes action, extracting the information passed in through the getParams method. It trivially logs some of the information to a log entry.

In this, slightly longer example, you can see more of the functionality available. You can see how:

• We can trigger events as required
• Create our own named events suiting our purpose
• Know what event was fired
• Look at the information in the event

All without extending a class needlessly and poorly. I could have taken a lot of different types of action here. I could have:

• Sent a tweet
• Sent an email
• Displayed further information

However, I’ve kept it intentionally simple as my intent is to introduce the EventManager, not give it an exhaustive run through.

I’ve provided a list of helpful and valuable links in the further reading section below to help you see how you can use it in a range of forms.

What are your thoughts on the Zend Framework EventManager?

What I’ve written here is my take on how the EventManager works and understanding of the key concepts which compose it. However I’m still learning about it too and would love to hear your understanding about it.

Do you believe it’s written the write way and really does allow us to develop cleaner, more effective and scalable applications? Feel free to share your experience and knowledge in the comments below so we can all better use the EventManager in ZF2.

Further Reading

• http://msdn.microsoft.com/en-us/library/dd129913.aspx
• http://www.mwop.net/blog/2012-07-30-the-new-init.html
• http://p0l0.binware.org/index.php/2012/02/18/zend-framework-2-authentication-acl-using-eventmanager/
• http://samsonasik.wordpress.com/2012/08/23/zend-framework-2-controllerpluginmanager-append-controller-pluginto-all-controller/
• http://zend-framework-community.634137.n4.nabble.com/ZF2-Doing-something-before-calling-the-controller-action-td4656922.html

Related Posts

• Zend Framework 2 Modules – The Application’s Heart
• Zend Framework 2 Core Concepts – Dependency Injection
• Zend Framework 2 ServiceManager – Web Application Development Simplified
• Zend Framework 2 – Hydrators, Models and the TableGateway Pattern
• Zend Form Mastery with Zend Config – Part 1 Custom Filter Paths