First, I should point out that the title of this post is a bit of an intentional misnomer. There’s really no such thing as “module-specific” anything in ZF2, so what we’re really talking about is the topmost namespace of the controller being dispatched. So in the case of MyModule\Controller\SomeController, the topmost namespace would be MyModle. In most cases, this will be the name of a given module.

Here’s how you can easily switch the layout (or perform any other arbitrary logic) for a specific module in Zend Framework 2.0 (as of d0b1dbc92)

He shows how easy it is to register an event that is only triggered when an action belonging to the namespace of the current module is dispatched. If you need to change the layout for a given module, this is the best way to do it as of today.

His point that a Module is merely the namespace of the dispatch controller is very important to understand too!

Vagrant is a fantastic tool that enables you to manage and run virtual machines from the command line, including automatic provisioning of them using puppet or chef. The really cool thing about it however from my point of view is that vagrant automatically sets up the VM with a folder called /vagrant that holds the code on your local hard drive from where you started the VM. This means that you can continue to edit your code in your local editor/IDE and test it within the VM easily.

I highly recommend checking it out.

ZF1's Vagrant set up

The Vagrant set up for ZF1 is designed for testing ZF1 against multiple PHP versions. As such it sets up a simple Ubuntu VM with the required toolchain for compiling PHP and provides a script called php-build.sh which will download and build any PHP 5.2, 5.3 or 5.4 version that you are interested in. I based this script on information in Derick Rethans' excellent Multiple PHP versions set-up article.

One thing that I discovered was that by default, the VM cannot create symlinks in /vagrant. The way to solve this is to add the following to the Vagrantfile:

  config.vm.customize [
    "setextradata", :id, "VBoxInternal2/SharedFoldersEnableSymlinksCreate/v-root", "1"
  ]

I chose to use puppet to install the required packages and created a simple default.pp configuration. I'm sure this isn't optimal, but it works :)

Running ZF1 unit tests

The process to set up ZF1 to run unit tests in a VM using PHPUnit 3.4, follow these steps:

1. Install requirements for running the VM:

• VirtualBox (https://www.virtualbox.org/)
• Ruby (http://www.ruby-lang.org/)
• Vagrant (http://vagrantup.com/)

2. Checkout the ZF1 repository:

    $ svn checkout http://framework.zend.com/svn/framework/standard/trunk zf1-dev
    $ cd zf1-dev

3. Start the process by running Vagrant.

    $ vagrant up

This will take a long while as it has to download a VM image and then provision it. Once it has finished, it will exit and leave you back at the command prompt.

4. SSH into the VM

    $ vagrant ssh

Vagrant sets up key-less ssh connections to the VM that "just works" :)

5. Build a version of PHP.

    $ php-build.sh 5.3.11

This also takes a while as it compiles PHP for you! It also installs PHPUnit 3.4 as that's the version we need to unit test ZF1.

Each version of PHP that you compile is stored in /usr/local/php/{version number}. You can compile any version; I have 5.2.4, 5.2.12, 5.3.3 and 5.3.11 installed at the moment…

6. Select PHP to use:

   $ pe 5.3.11

pe is a handy shell function that Derick wrote that changes your PHP environment to whichever version your specify.

7. Run tests

   $ cd /vagrant/tests
   $ php runtests.php

Alternatively, you can run each component's tests individually:

   $ phpunit --stderr -d memory_limit=-1 Zend/Acl/AclTest.php
   $ phpunit --stderr -d memory_limit=-1 Zend/Amf/AllTests.php
   (etc...)

Obviously, you repeat steps 5 through 7 for each version of PHP you want to test on.

To stop your Vagrant VM, exit the SSH shell and type `vagrant halt` or `vagrant suspend`. For more details on controlling your Vagrant VM, I recommend Lorna's article

Running unit tests on Zend Framework 1 is now considerably easier!

Installing PHPUnit 3.4

The first challenge that I encountered was that ZF1's unit test are not compatible with PHPUnit 3.6. As there are over 14,000 ZF1 unit tests which have been written since 2006, there hasn't been much enthusiasm for rewriting them to be PHPUnit 3.6 compatible. (However, if someone wants to volunteer, please contact me!)

As I have PHPUnit 3.6 installed for testing other projects, I needed to install PHPUnit 3.4 side-by-side with version 3.6 This turns out to be relatively easy and has been documented by Christer Edvartsen in his article Running Multiple Versions of PHPUnit.

I ran into one problem with his instructions though and needed this code to be added to the top of phpunit:

set_include_path(implode(PATH_SEPARATOR, array(
    __DIR__ . '/../share/php',
    '/usr/share/php',
    get_include_path()
)));

Having done this though, PHPUnit 3.4 works correctly and we can run ZF1 unit tests.

Running the ZF1 unit tests

To run ZF1's unit tests, you first need to check out the code from the Subversion repository.

svn co http://framework.zend.com/svn/framework/standard/trunk/

Due to the number of tests and the memory that they take up, you should run tests for each component individually.

The command to use is:

phpunit34 --stderr -d memory_limit=-1 Zend/{Component}/AllTests.php

Note:

• --stderr pipes PHPUnit's output to stderr which means that any tests that rely on header() will work. (i,e. don't test Zend_Session without it!)
• -d memory_limit=-1 will turn off PHP's memory_limit setting. The ZF1 unit tests use a lot of memory, so this is easiest.
• The tests rely on being set up correctly. This is done using AllTests.php so don't forget this. Tests will fail if you forget!

All that needs to happen now is that any failing tests are fixed!

With the new modular infrastructure in Zend Framework 2, one of the most common questions will indoubitably be how to share a database connection across modules. Here’s a quick explanation of how to share your database connection across multiple modules in a way that can even allow you to use a single connection between Zend\Db, Doctrine2, and possibly even other database libraries / ORMs.

If you're using ZF2, this is a must-read.

Terminology

For the purposes of this article, we will use these definitions:

• An EventManager is an object that holds a collection of listeners for one or more named events, and which triggers events.
• An event is an action that is triggered by an EventManager.
• A listener is a callback that can react to an event.

When the EventManager's trigger() method is called, all the listeners attached to the event are called in turn and are passed an Event object which contains a target and additional parameters as required.

Triggering events

A typical use-case for EventManager is to trigger events within a mapper class:

use Zend\EventManager\EventManager;
use Zend\EventManager\Event;

class PhotoMapper
{
    public $events;

    public function events() 
    {
        if (!$this->events) {
            $this->events = new EventManager(__CLASS__); 
        }

        return $events;
    }

    public function findById($id)
    {
        $this->events()->trigger(__FUNCTION__ . '.pre', $this,
            array('id' => $id));

        // retrieve from database and create a $photo entity object

        $this->events()->trigger(__FUNCTION__ . '.post', $this, 
            array('photo' => $photo));

        return $photo;
    }

    //  class continues...

Firstly, note that, by convention, the EventManager instance is called $events and we use a method called events() and that will instantiate the EventManager for us when needed. This is a very common code pattern in ZF2 classes; so common in fact that the ZfcBase module contains a class called ZfcBase\EventManager\EventProvider that you can extend from to provide you with this functionality.

Within our mapper's findById()method, we trigger two events: before and after the actual work is done. When triggering an event, we supply the event's name, the target class and an array of data that the listeners may be interested in.

By convention, we use the name of the method as our event's name. This makes it predictable for users of the class. Also, by convention, if there two events, then we append '.pre' and '.post' to the event name. the target class is usually the class that triggered the event, and so we pass in $this. Finally, we can provide some additional data to the listeners. In this particular method, we supply the id before we retrieve (as that's all we have!) After retrieval, we have the entity object itself, so we supply that to the listener callbacks.

Listening for an event

A listener is just any PHP callback function which takes a single argument, $event, which is an instance of an Event. The listener is attached using event manager's attach() method. For example, we could attach a logger to our mapper's findById.pre event like this:

$photoMapper->events()->attach('findById.pre', function(Event $event) {
    $message = "Trying to retrieve photo: " . $event->getParam('id');
    MyLogger::log($message);
});

The $event parameter that is passed to the listener method has three user methods:

• getName() - Useful when the same listener is attached to multiple events
• getTarget() - Usually the class that trigger the event
• getParams() - Retrieve the parameters sent when the event was triggered.

Priority
When attaching a listener to an event, you can specify the priority in the third parameter. The larger the number, the earlier the listener is called. i.e. for a listener that you want to be executed first, set the priority to say 1000. For a listener that you want to be executed last, set the priority the -1000. The default priority is 1 and listeners with the same priority are executed in order or priority.

Short circuiting

The return value from trigger() is a ResponseCollection which is a collection of all the returned results from every listener that has been called in reverse order. i.e. the result from the last listener is first in the collection.

As this result is passed back to trigger, we can use it to stop processing of the listeners if something interesting happens. This is known as short-circuiting and we do this by attaching a callback as the last parameter to trigger().

A good example of this is a caching solution on our findById() method. We change it so that it looks like this:

    public function findById($id)
    {
        $results = $this->events()->trigger(__FUNCTION__ . '.pre', $this, 
            array('id' => $id),
            function ($result) {
                return ($result instanceof Photo) ? true : false;
            }
        );

        if ($results->stopped()) {
            // we ended early. Result returned from last listener was an entity
            $photo = $results->last();
            return $photo;
        }        

        // retrieve from database and create a $photo entity object

        $this->events()->trigger(__FUNCTION__ . '.post', $this,
            array('photo' => $photo));

        // save $photo to cache here

        return $photo;
    }

We have added a callback to our trigger() call that returns true if the result returned by a listener is an instance of Photo. This means that we can attach a listener that tries to read a cache for the id. If it finds one, then it returns the cached object. The trigger callback notices and returns true and the ResponseCollection's stopped flag is set to true.

We then test for stopped() and if it has been set, $results->last() contains the Photo entity that we need.

SharedEventManager

It's common that you may want to set up listeners before the objects with the event manager you need has been instantiated. Good examples are listeners that log or cache. ZF2 comes with the concept of the SharedEventManager. Essentially you attach listeners to the SharedEventManager and then when the particular event manager's trigger() is called, it will also call all the listeners attached to the shared event collection.

There are two ways to access the SharedEventManager: DIC injection into the object where you need it or via a static class called (rather unimaginatively) StaticEventManager. The exact details of how the injection will work are up in the air at the moment as it's expected that some additional defaults will be provided to make it easier in beta 4 and the use of the StaticEventManager will become deprecated.

In either case, the way to attach a listener to the SharedEventManager is the same:

// $events is a Zend\EventManager\SharedEventManager instance either injected
// or acquired using $events = StaticEventManager::getInstance();

$events->attach('Gallery\Model\PhotoMapper', 'findById.pre', function(Event $event) {
    $message = "Trying to retrieve photo: " . $event->getParam('id');
    MyLogger::log($message);
});

Note that the only change to the attach call is the addition of a new first parameter which is the name of the class where the event manager is to be found. In this case, it's Gallery\Model\PhotoMapper. The other three parameters are the same: event name, callback and priority.

In terms of execution of listeners with the same priority, those attached directly are executed before those attached via the SharedEventManager.

Summary

This article covers how to use the EventManager in your application. The biggest advantage to using EventManager in your application is that you can decouple classes that really shouldn't be coupled together which makes your code easier to write and maintain. In fact, this is so useful, that ZF2's MVC system makes heavy use of EventManager; The module manager, routing, dispatching and the view layer are all implemented using listeners attached to events.

Recently they have been working on a new product called Natural Load Testing which is intended to make load testing your web application very simple. It's a very friendly service which is immediately apparent on the home page where it says "not logged in, no greeting. how sad". It's a little touch that appeals to me.

Natural Load Testing is currently in private beta and the WonderNetwork guys invited me into the beta and have been generous enough to spend a small part of their marketing budget to enable me to be able to publish this article. They've even managed to cope with my list of complaints and still talk to me! In this tutorial I will walk through how to use the Natural Load Testing product (as is today) to get some results. Interpreting the results and improving your website and server infrastructure is your job though :)

Getting Started

Natural Load Testing (shortened to NLT in this article!) consists of 4 main areas where you interact with it:

• Creating tests
• Configuring test suites
• Running test suites
• Reviewing results

Upon log in, the home page consists of a set of friendly buttons:

We start at the beginning: creating tests.

Creating tests

When load testing you need to configure your testing tool with the URLs of the pages and resources the you want to be tested. Natural Load Testing makes this job trivial by cleverly leveraging their proxy technology. By configuring your browser to use the NLT proxy, it will record every page you visit and provide you with a list of URLs which you can then use to create tests.

Obviously, as load testing involves hitting the server with a lot of requests, by the time NLT is out of beta, you will need to authorise each domain that you want to use. This is done in the "Manage Authorised Domains" section.

There is a helpful page on the NLT site that explains how to do this. Don't forget to turn off the proxy after recording. The WonderNetwork people have also remembered that you may want to record HTTPS traffic for load testing, and have provided a root certificate that you'll need to install. Again, there's help available on how to install this.

Once you have recorded some URLs, you can then click on the "Create" button and you are presented with a list of the most recent URLs you have recorded.

To create the test, you select the URLs that you require to be included (the checkbox in the header selects all within the group, which is very handy!). You then choose a name that will help you remember what this test does and create the test.

In order to create some interesting load tests on our site, I created a good few tests which I could then group into test suites.

Configuring test suites

Your tests are grouped into suites that are then run either sequentially or as a set of random loads. To create a suite, you click on the "Configure" button which then shows you the list of the suites that you have already created.

In this screenshot you can see two test suites that I've created. The second test "ZF2 Tutorial only" is the simplest suite possible as it contains a single page load within a single step. The top suite shows a more complex suite which hints at the complexity of the suites that you can create.

A suite is composed of one or more steps which are run in sequence. Each step can have multiple tests. If there are multiple test in the same step, then NLT will randomly pick one test for each run.
In this suite I have four tests in step 1 which are a set of pages within the BRI website. Step 2 is the contact page and so this test suite is measuring visiting one of 4 pages within the site and then choosing to go to the contact page.

Creation of a new test suite is done via drag and drop:

You simply drag your green tests over to the list of steps on the right hand side. It's all quite easy. Rather weirdly, you can't reuse the same test in multiple steps, so if you're testing a cycle, then you need to duplicate the same test so that you can place it into two different steps. I haven't found a way to edit the steps within a test suite once created either, so make sure you get it right!

Once you have added tests to steps, you can then tell NLT to send data whilst load testing. This is useful for filling in forms or logging into the website, for instance. I haven't used this section as I haven't yet tested any pages with forms or requiring login.

Rather useful fully, you can change the domain that a test suite uses. This enables you to duplicate a test suite and then change the domain to test domain that's running on another server or using a different configuration which makes side-by-side testing a little easier.

Calibration

Once we have created a test suite, the next step is to calibrate it. NLT will not allow you to run a test suite before calibration, so don't forget this bit! Calibration is done from the test suites list page where there is a drop down box of operations you can do on each suite:

Simply pick Calibrate and press Go. NLT will then perform a single run over your suite and present the standard results page. Ideally, I would like to see this page look different from the standard results page as it's a calibration run, not a standard test and so I was slightly confused at this point. Also, whilst the test is running, you simply see one of those "spinning gifs" to let you know that something is happening. I ran into a bug in this section which resulted in the calibration run failing, but I was never notified on the page that an error had occurred.

The calibration results on my ZF2 tutorial page suite look like this:

The intent of calibration is to provide a base-line to the NLT of the performance of the suite when there is no load. i.e. the idea is that this single run has provided an indication of the optimal conditions and we are expecting to be within 15% of this performance when testing under load.

Running test suites

Now that we have calibrated test suites, we can run some load tests and see what happens. In NLT parlance, we run test suites by pressing the Play button at which point the terminology changes to from play to execute. Simply select your test suite and press the Execute button. You are then presented with a form in order to set the run parameters:

There are three parameters you need to set:

We set these numbers up to create the required load testing profile. I've been using 100 users at 250ms spin-up for 2000 total executions as this takes around 30 to 60 seconds to complete a run and seems a reasonable profile for my blog given its traffic levels.

Upon pressing execute, NLT will spin up a number of worker processes on its servers and then display a graph that updates every few seconds showing you what happening:

As you can see in the screenshot above, you get this information:

• A bar showing number of active requests (blue) on top of number of requests initiated.
• A line chart of median response time.

The x-axis is in seconds. Hence the red bar chart shows the number of requests initiated during each second and the blue bar shows the number of requests that were still active at the end of the second. Hence a request that completed within a second is counted in the red bar, but not in the blue. Ideally, therefore we would like to see smaller blue bars than red bars and we definitely don't want to see blue bars getting bigger.

The green line shows us the average time it takes to server all requests in that second. Ideally, we want this number to be lower. Clearly, if there are any errors serving a request (e.g. an nginx bad gateway error), the rather fast failure time is not counted as it would bring the average down!

We can also view the data as a table:

Obviously, this is right at the start of the run, and so all look good. Clicking on a given run id will provide us with more information. This is a run that's later in the test:

As you can see, the server was struggling now! The red background means that the request took more than 15% longer than the calibration run and the difference from calibration is shown in brackets in the Response Time column. In this particular run, the main HTML took 760ms to deliver which as 411ms longer than the calibration run. We're also struggling to serve images in a sensible time. This is clearly not ideal!

Looking at what's going on on the server whilst running a load test is also instructive. A good introduction to the server tools that are useful is 16 Linux server monitoring commands you really need to know by Steven Vaughan-Nichols.

Reviewing results

Once you have a few runs under your belt, the Review page becomes useful. In this page we can see a list of all our previous runs and most importantly, we can edit the title of each run and give it a useful name. It would be nice to be able to store additional notes about each run though.

Adding the title makes it much easier to remember why a given run was performed and I've found it useful.

Using Natural Load Testing to improve performance

The obvious first target for testing NLT, was my blog at akrabat.com. This is a simple WordPress blog which recently moved to a new server. I haven't been particularly worried about performance and don't really expect to ever be slash-dotted (or is it Cal-dotted, nowadays!) any time soon.

However, as I've done nothing to tune the system, this is a good time to see how it behaved. The first run produced these results:

This isn't good! The only good sign was that none of the 2000 runs actually resulted in an error. A median response time around 1.5 seconds didn't sound good and the maximum run time was 13 seconds!

Something had to be done!

A little bit of investigating showed that neither APC or WP Super Cache was installed on the server. So I turned them on.

The effect of APC can be seen here:

We now have an average response time of much less than 500ms which seems much saner. There were a number of very long requests of over 1 second though.

To see if I could improve this further, I then installed and enabled WP Super Cache in PHP mode and re-ran Natural Load Testing. The results were:

Note that you need to be careful when comparing graphs as the axes are automatically scaled. Looking at the results with WP Super Cache was enabled, I can see that the response time display of the graph is much smoother. The tabular data backs this up as it shows that the vast majority of requests were taking less than 200ms with significantly fewer runs taking much longer. Also, the curve of the number of requests initiated vs request active at the end of each second is much smoother, which indicates that with WP Super Cache enabled, the server should be able to hold its own over a longer time period much more easily.

I tested this hypothesis by doing 5000 runs rather than the 2000 shown above. The result was:

Again, the median response time is nicely under 150ms for most of the time, but we have more variance in the response time, with a couple of seconds where the median was significantly over 250ms.

On the whole, my investigations with NLT have made my blog much more responsive and more likely to be able to handle more traffic than before I started this process.

Other thoughts

Having walked though what Natural Load Testing does, I also need to point out that when using it, you can tell that this is a product still in beta! Incidentally, the WonderNetwork people have responded to my reports quickly, even if half the time it was to let me know that my idea or complaint was already on their list!

Nearly all the issues I have with NLT at the moment are related to usability, which I'm sure will be ironed out over time. My "favourite" annoyance as noted above is on the create test suite page where the Save button is above the section where you set up the suite's steps. If you accidentally press Save after entering a title, then you find you can't actually add any tests to the steps! There's also no menu bar or easy way to get from one section to another. You very quickly learn to click on the NLT logo at the top which takes you to the home page.

It would also be good if NLT would allow me to store "execution profiles" so that I don't have to keep typing in that I want 100 users for 2000 total runs.

I would also like to see more aggregate results. In particular, I'd like to have stats on the response time for say the 50th and 95th percentile. I'd also like to graph these against multiple runs along with the run title so I can see how the site's performance changed over time. This then leads to the idea that it would be nice if I could schedule a load test once a month at 3am local time!

Conclusion

Natural Load Testing is the first product I've used that makes me actually want to do load testing. It makes it easy to run a specific load test and repeat exactly the same test as frequently as you need to. Tweaking the server to see the effect that any given change has becomes an interesting task and your websites can only benefit as you reduce and remove the bottle necks that you find.

On the whole, I'm quite impressed with Natural Load Testing and can see that it could turn into a very useful tool in the web developer's toolbox.

As I mentioned at the top, NLT is currently in private beta. If you want to get an invite, head over to the sign up form and fill in your details. You also have to read the thank you for signing up message!

Accessing action variables in the layout

Consider this controller code:

class IndexController extends ActionController
{
    public function indexAction()
    {
        return array('myvar' => 'test');
    }
}

If you are in the layout.phtml, then to retrieve this value you do:

layout.phtml:

<?php
$children = $this->viewModel()->getCurrent()->getChildren();
$child = $children[0];
?>
<!-- some HTML -->
<?php echo $this->escape($child->myvar);?>

If you really want to make sure you collect the correct child view model, then you could iterate over $children and look for the child that has the correct captureTo name set. For the action's view model, this defaults to content:

layout.phtml:

<?php
$children = $this->viewModel()->getCurrent()->getChildren();
foreach($children as $child) {
    if ($child->captureTo() == 'content') {
        break;
    }
}
?>
<!-- some HTML -->
<?php echo $this->escape($child->myvar);?>

Accessing layout variables in the action view

If you have assigned a variable to the layout's view model in, say, an event listener within Module.php:

Module.php:

    public function onBootstrap($e)
    {
        $application = $e->getParam('application');
        $viewModel = $application->getMvcEvent()->getViewModel();
        $viewModel->some_config_var = '12345';
    }

This is how you access some_config_var in the action view:

view/index/index.html:

<?php echo $this->escape($this->layout()->some_config_var); ?>

Another, more long winded way is to use the getRoot() method on the viewModel view helper:

view/index/index.html:

<?php
$layoutViewModel = $this->viewModel()->getRoot(); 
?>
<!-- Some HTML -->
<?php echo $this->escape($layoutViewModel->some_config_var); ?>

Setting configuration variables into the view

It therefore follows that if you need to set a variable that could be accessed from any view script, it's easiest to set it into the layout's view model and then access it via the layout() view script. This is handy for view layer config variables that you want to store in your config files, such as the Google search API key.

Application/config/module.config.php:

<?php
return array(
    'layout' => array(
        'google_search_api_key' => '1234567890',
    ),

Application/Module.php:

    public function onBootstrap($e)
    {
        $application = $e->getParam('application');
        $config = $e->getParam('config');

        $viewModel = $application->getMvcEvent()->getViewModel();
        $viewModel->config = $config->layout;
    }

view/search/index.html:

<?php echo $this->layout()->config->google_search_api_key; ?>

Set up the JsonStrategy

We set up the JsonStrategy as we did in returning JSON from a ZF2 controller action.

Return a ViewModel from the controller

As we're letting the JsonStrategy intercede for us, we don't need to do anything special in our controller at all. In this case, we simply return a normal ViewModel for use by either the JsonRenderer or PhpRenderer as required:

module/Application/src/Application/Controller/IndexController.php:

<?php

namespace ApplicationController;

use ZendMvcControllerActionController,
    ZendViewModelViewModel;

class IndexController extends ActionController
{
    public function anotherAction()
    {
        $matches[] = array('distance' => 10, 'playground' => array('a'=>1));
        $matches[] = array('distance' => 20, 'playground' => array('a'=>2));
        $matches[] = array('distance' => 30, 'playground' => array('a'=>3));

        $result = new ViewModel(array(
            'success'=>true,
            'results' => $matches,
        ));
        return $result;
    }
}

with our HTML view script:

module/Application/view/index/another.phtml:

<?php if ($success): ?>

<h2>Results</h2>

<ul>
<?php foreach ($results as $row): ?>
    <li>Distance: <?php echo $this->escape($row['distance']);?>m</li>
<?php endforeach; ?>
</ul>

<?php endif; ?>

So if you set up a route and browse to it, you'll see a nicely rendered page.

Retrieving the data as JSON

To retrieve the data via JSON, we need a client where we can set the Accept header. We'll use curl for this test. When doing anything with APIs and testing, we head over to LornaJane's blog for the Curl Cheat Sheet and use this command line:

curl -H "Accept: application/json" http://zf2test.dev/json/another

and you should see the output of:

{
  "content":{
    "success":true,
    "results": [
      {"distance":10,"playground":{"a":1}},
      {"distance":20,"playground":{"a":2}},
      {"distance":30,"playground":{"a":3}}
    ]
  }
}

(Formatted for readability - you get the result back on a single line from curl.)

This way you can use the same controllers for your HTML views and for returning JSON to those clients that can use it.

Set up the JsonStrategy

Firstly we need to set up the view's JsonStrategy to check to a situation when returning JSON is required and then to render out JSON for us. The JsonStrategy will cause the JsonRenderer to be run in two situations:

1. The view model returned by the controller action is a JsonModel
2. The HTTP Accept header sent in the Request include "application/json"

The enable the JsonStrategy, we simply attach it to the view's event manager with a reasonably high priority. This can be done in our Application's Module class. Firstly we create an onBootstrap() callback on the bootstrap event and then we implement onBootstrap() to attaché the JsonStrategy:

module/Application/Module.php:

class Module implements AutoloaderProvider
{
    public function init(Manager $moduleManager)
    {
        $events = StaticEventManager::getInstance();
        $events->attach('bootstrap', 'bootstrap',
            array($this, 'onBootstrap'));
    }

    public function onBootstrap(Event $e)
    {
        $application  = $e->getParam('application'); 
        /* @var $application \Zend\Mvc\Application */
        $locator      = $application->getLocator();
        $view         = $locator->get('Zend\View\View');
        $jsonStrategy = $locator->get('Zend\View\Strategy\JsonStrategy');
        $view->events()->attach($jsonStrategy, 100);        

    }

    // more methods such as getConfig() and getAutoloaderConfig()
}

As you can see, in init() we grab the StaticEventManager to attach our onBootstrap() method to the bootstrap event. Then, within onBootstrap(), we grab the view and the JsonStrategy from the locator (via application) and attach the JsonStrategy to the view's events() event manager.

Return a JsonModel from the controller action

To send JSON to the client when the Accept header isn't application/json, we use a JsonModel in a controller action like this:

module/Application/src/Application/Controller/IndexController.php:

namespace Application\Controller;

use Zend\Mvc\Controller\ActionController,
    Zend\View\Model\ViewModel,
    Zend\View\Model\JsonModel;

class IndexController extends ActionController
{
    public function indexAction()
    {
        $result = new JsonModel(array(
        'some_parameter' => 'some value',
            'success'=>true,
        ));

        return $result;
    }
}

The output will now be JSON. Obviously, if you're sending JSON back based on the Accept header, then you can return a normal ViewModel.

This is how to do it.

Apache configuration

The Apache magic is in an extension called mod_vhost_alias which you may need to enable in your httpd.conf file.

You can then set up the VirtualHost wherever you keep such things. On a stock OS X, the extras/httpd-vhosts.conf file is used.

Add the following to the bottom:

<Virtualhost *:80>
    VirtualDocumentRoot "/www/dev/%1/public"
    ServerName vhosts.dev
    ServerAlias *.dev
    UseCanonicalName Off
    LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon
    ErrorLog "/www/dev/vhosts-error_log"
    <Directory "/www/dev/*">
        Options Indexes FollowSymLinks MultiViews
        AllowOverride All
        Order allow,deny
        Allow from all
    </Directory>
</Virtualhost>

In the VirtualHost configuration, I have used the ServerAlias and VirtualDocumentRoot directives to map http://foldername.dev to the directory /www/dev/foldername/public. Hence, any folder that I place in /www/dev will have its own virtual host. Alter these appropriately for your set-up.

Don't forget to restart Apache.

Unfortunately, the computer hasn't a clue how to handle http://foldername.dev and the obvious solution is to run a local DNS server. Another solution is to use a PAC file.

DNS server configuration

This is easy enough with dnsmasq. On OS X, use Homebrew to install like this: brew install dnsmasq. On Linux, use your package manager; on Windows, you're own your own!

Note that on OS X, you should set it to start up automatically using launchd as noted in the instructions after installation. You also need to copy the configuration file to /etc using: cp /usr/local/Cellar/dnsmasq/2.57/dnsmasq.conf.example /usr/local/etc/dnsmasq.conf (or whatever the latest version number is). on Linux, I would guess that your package manager provides a dnsmasq.conf file in /etc or /etc/dnsmasq.

Next, edit dnsmasq.conf file and added the following lines to the bottom:

listen-address=127.0.0.1
address=/.dev/127.0.0.1

Add the name server to your network configuration

On OS X, Go to System Preferences -> Network -> {Wifi or Ethernet} -> Advanced… -> DNS and click on + button at the bottom of the left hand panel and add 127.0.0.1 to the list of DNS servers. Drag 127.0.0.1 at the top of the list.

On Linux, you should use the appropriate GUI tools for your distribution or potentially edit etc/dhcp/dhclient.conf and uncomment the domain-name-servers 127.0.0.1; on line 20 (on Ubuntu).

Restart dnsmasq and you should now be able to execute host test.dev on the command line and see 127.0.0.1 as the resultant address.

Alternative to DNS server: PAC file

Since publishing this article, Chris Morell pointed out that you can also use PAC files rather than install a DNS server. Details are on his blog post.

Check it works

Create a directory called test in your dev directory. Within test, create public/index.php and within index.php add some code to prove it works. e.g. < ;?php echo "Hello World"; ?>;

If you navigate to http://test.dev, you should see "Hello World" displayed.

Caveats

A couple of caveats:

• DOCUMENT_ROOT is not /www/dev/test as you'd expect. Instead it is the global document root. See this gist for a neat way to solve this using a prepend file.
• If you use mod_rewrite, then you'll need a RewriteBase / in your .htaccess file. Alternatively, you can change the Directory section of your vhost to do the rewriting for you if all your projects are alike. Something like this should work:

      <Directory "/www/dev/*">
          Options Indexes FollowSymLinks MultiViews
          AllowOverride None
          Order allow,deny
          Allow from all
  
          RewriteEngine On
          RewriteBase /
          RewriteCond %{REQUEST_FILENAME} -s [OR]
          RewriteCond %{REQUEST_FILENAME} -l [OR]
          RewriteCond %{REQUEST_FILENAME} -d
          RewriteRule ^.*$ - [NC,L]
          RewriteRule ^.*$ index.php [NC,L]
      </Directory>
  

All done

That's it. You can now create as many projects as you like without having to worry about setting up new virtual hosts or modifying you hosts file!