For starters, what is routing?

The fundamental principle of routing is to match incoming requests reaching an application and decide which fragment of code to execute. That could mean matching either an http request or a console requests (if you are interacting with a Command Line Interface application), and extracting the parameters that determine which snippet of code (IE which controller and then which action) to execute. The other basic principle is to assemble URLs and commands back. That is, from a set of parameters, to build the path of the route. In terms of an example, this means coming up with the /products/view/some_product URL starting from the controller = products, action = view, slug = some_product parameters*.

*I am aware this might not be the best possible example URL, but I hope it gets the message across in simple terms.

Why should we care about routing?

There are different reasons why routing is important. The simplest and most important one is that without routing your application won’t work Even in a working application, though, properly handling routing is important. That’s for different reasons, which can be summarized as follows:

- good URLs are easier to remember, type and share through word of mouth
- they also make it easier for search engines to properly index websites and web applications
- they allow for clean RESTful interfaces to be build
- they improve web application security, because they make it easier for parameters to be properly handled

Routing within the Zend Framework 2

Under the Hood

The basic unit of routing is a so called route, which is nothing but a PHP class implementing the following interface:

namespace Zend\Mvc\Router;

use zend\Stdlib\RequestInterface as Request;

interface RouteInterface
{
  public static function factory(array $options = array());
  public function match(Request $request);
  public function assemble(array $params = array(), array $options = array());
}

The RouteInterface includes the  static method factory, which is used to create new routes. Every route is constructed with arguments (usually fetched from specific project/module configuration file). The match method, in turn, accepts a new Request, and determines if the request matches current route. If true, it then returns a RouteMatch object, which is a container object, that includes the route name and most likely all route parameters and values. Last, we also have the assemble method, which takes options and parameters and builds the path of a route (usually an URL).

We will rarely need to worry about implementation details of these methods, though, because the framework will take care of passing the configuration and creating our routes according to our definitions in each module configuration directives (as we’ll shortly see).

Defining new routes

Routes for each module shall be defined within the module configuration file, which can be found in every module’s root folder. The default Zend Framework Skeleton app also has its own Module.php file in /config/modules.config.php:

The section dealing with routing is the one which goes under the router key; routes contains a list of our routes in array form:

return array(
  'router' => array(
    'routes' => array(
      'contact' => array(
        'type' => 'Literal',
        'options' => array(
          'route'    => '/contact',
          'defaults' => array(
            'controller' => 'Application\Controller\Contact',
            'action'     => 'index',
          ),
        ),
      ),
    ),
  ),
),

In the basic example above, we defined a route named “contact”, of type Literal (all different Route types will be covered in a forthcoming post). Basically we just told the framework to dispatch users requesting the ‘/contact’ URL to the Contact controller, and to have the IndexAction method to be executed.

What about route stacks

The ZF2 router is a collection of routes, based on a priority stack. As it was happening in Zend Framework 1, routes can be added to a route list; the last added route is the one tested first. The same now happens in ZF2; we can now also take advantage of the new priority attribute, though. This means that every route will have a priority value, and highest priorty route will be tested first. I’m sure this will make it easier to keep things organized without needing to worry much about route position within configuration files. This will also make it easier for custom configurations to be used to override third party default configurations.

Every router (there are different types, which we’ll take a look at shortly) implements this interface:

namespace Zend\Mvc\Router;

interface RouteStackInterface extends RouteInterface
{
  public function addRoute($name, $route, $priority = null);
  public function addRoutes(array $routes);
  public function removeRoute($name);
  public function setRoutes(array $routes);
}

All methods are self-explanatory, so I won’t go in further detail here. This is with the exception of the setRoutes method, which probably deserves some explanation. This method in fact replaces current routes in the stack with the new ones provided as an argument. So, it first removes current routes, then adding the new ones.

Router types

There are different implementations of the aforementioned Router base class:

• SimpleRouteStack: the most basic implementation, which we can use and extend to make our own router stack class.
• Http\TreeRouteStack: the most common kind of router, it is used to create a tree of routes to deal with http requests, using a B-tree algorithm to match routes (this ensures that evaluation is efficiently made, as we’ll shortly see).
• Console\SimpleRouteStack: used in the realm of CLI applications and use to take care of command line arguments. This kind of router will be processed when our application is run from a console terminal window.

Tree Routing

Zend Framework 2 introduces the Tree Routing concept as a big innovation. In fact, it’s very easy to use and its performance is great also: it’s much faster than its ZF1 counterpart. This is for multiple reasons: first off is the fact that the framework doesn’t try to match incoming requests with every single route anymore. This happens because every route can now have an unlimited number of children routes, which aren’t evaluated if parent route didn’t match the request first. Children routes are in fact only instantiated when the router matches or assembles their respective parent routes.

A Tree Route will consist of the following configuration:

• A base route, known as root route, which describes the base path (first part of an URL, for example);
• The may_terminate key, which is set to false by default, telling the router whether the route may terminate or not.
• The child_routes key, an array containing additional routes that stem from the base “route”. Each child route can itself be a Tree Route

Example:

return array(
  'router' => array(
    'routes' => array(
      'zf' => array(
      'type' => 'Literal',
      'options' => array(
        'route' => '/zf',
        'defaults' => array(
        '__NAMESPACE__' => 'Application\Controller',
        'controller'    => 'Article',
        'action'        => 'index',
      ),
    ),
    'may_terminate' => true,
    'child_routes' => array(
    'default' => array(
      'type'    => 'Segment',
      'options' => array(
        'route'    => '/:action',
        'constraints' => array(
          'action'     => '[a-zA-Z][a-zA-Z0-9_-]*',
        ),
      ),
    ),
  ),

Summary

In this first post about the Zend Framework 2 routing, I’ve introduced what’s a route, what’s routing, how the routing system works in the Zend Framework 2, and how it differs (especially from a performance point of view) from the ZF1 implementation. In my next post, I will be covering different HTTP route types we have at hand. Is there anything else you’d like to know? Just let me know with a comment below.

The problem: where assets should be placed?

The first problem to solve is: where my module’s assets should be placed to let me (the developer) forget about them? Because I should not care about assets provisioning, I would spend my time working on module itself! To simplify the problem, let me break it into two (not so) different use cases.

Shared assets

A module probably has many shared assets with other modules: javascript libraries, images, css files, etc. A common practice is to place all of them inside the project /public folder. Despite this is the simplest solution, it’s not the best. Copy/paste manually is never a good practice, besides copying all files inside the same folder will contribute to lose the explicit dependencies the module has with its assets.

Single module’s assets

In many cases a module has also some assets being used only by itself. We know that a module should focus on a single project functionality, so it should contain all the things that functionality needs to work well. The simplest answer now is probably the best: we should place all assets inside the module.

Some naive solutions

How should we make the web server aware that out modules have some assets that need to be visible inside our view scripts?

We could copy all assets (also those needed by a single module) inside public folder, every time one of them is added or updated. This is a bad practice, trust me!

We could use symlinks to let files be viewed inside another folder. Or we could do some apache htaccess tuning to let web server search files through all module folders. Luckily, there is a better way to handle things…

Welcome AssetManager module

AssetManager is a ZF2 module (https://github.com/RWOverdijk/AssetManager) aimed at managing assets, that resolve exactly our problem. It’s based on the Assetic asset management framework for PHP (https://github.com/kriswallsmith/assetic).

I don’t cover module provisioning and installation phases here because online there are straightforward and well organized articles about this (take a look on module’s wiki: https://github.com/RWOverdijk/AssetManager/wiki).

Instead, here I would like to explain how this module can be a real time (and headache) saver for all ZF2 developers.

After completing the install process, the module can take care of your assets through two simple steps:

1. Create a folder where assets should be placed. I typically suggest to use the /assets folder inside your module. Obviously you’re free to use whatever name you prefer. Sometimes you find assets inside a folder named /public, but this could be confused with the folder where the web server points to. So I suggest to choose a different name to make things clear. Use the folder you prefer, but keep in mind the rule of thumb: use always the same location inside all your modules, to make them more clear and readable.
2. Add the following rule to your module’s configuration file (/config/module.config.php – “assets” refers to the folder where your assets are placed):

'asset_manager' => array(
    'resolver_configs' => array(
        'paths' => array(
            __DIR__ . '/../assets',
        ),
    ),
),

With this two simple steps we are telling the AssetManager where the assets of our module are placed.

That’s it! Now when an asset is not found inside project /public folder, the AssetManager module’ll look inside our module /assets folder to find the requested file. From now you could link assets inside your views simply as follows:

<?php  echo $this->headLink()->prependStylesheet($this->basePath() . 
                                                '/css/aCssFile.css'); ?>

In this way, we don’t need to worry about where our css is physically located, just link it as if it was placed inside /public folder. So simple and so amazing! In this way you can place all module assets (both shared and exclusive) inside the module. So that module is now really reusable inside other projects, without hidden dependencies.

Pay only attention to avoid colliding file rules. It’s not uncommon to have modules containing files with the same name. In this case prefixing the asset path with the module’s name (or slug) could solve the issue (this can be done through the ‘map’ key inside configuration file; take a look on the code in the following paragraphs for an example).

This is the simplest use of AssetManager we could make, but this module has many more features that are worth an extra look. Let me define some terms the module uses (each of this maps to a key of module’s config file):

• Resolvers (resolver_configs key) allow to define where assets should be searched and how they are named / arranged. Many resolver types are available: MapResolver, CollectionResolver, PrioritizedPathsResolver and PathStackResolver (detailed infos and examples available here: https://github.com/RWOverdijk/AssetManager/wiki/Resolvers)
• Filters (filters key) allow make some processing on assets before serving them (eg. Minify minification, compiling of css files)
• Cache (caching key), as the name suggest, allows to choose which caching policy use to speed up assets serving time

An example

It’s a common practice to merge css files in order to limit the number of http requests (improving page serving speed). The AssetModule could help us to merge files automatically. Supposing our module has two css files (main.css and custom1.css), we could merge them together simply updating module’s config file as follows:

'asset_manager' => array(
    'resolver_configs' => array(
        'map' => array(
            'css/main.css' => __DIR__ . '/../assets/css/main.css',
            'css/custom1.css' => __DIR__ . '/../assets/css/custom1.css',
        ),
        'collections' => array(
            'css/merge.css' => array(
                'css/main.css',
                'css/custom1.css',
            ),
        ),
    ),
),

And the resulting view script is:

<?php echo $this->headLink()->prependStylesheet($this->basePath() . 
                                                '/css/merge.css'); ?>

More code samples can be found on official module wiki (https://github.com/RWOverdijk/AssetManager/wiki), that’s really well written and full of useful examples.

Conclusion

There are other ZF2 modules that provide asset management features. I personally like AssetManager because it’s really effective and simple to use. However is not important which module you decide to use, the important thing is that you should stop right now to manage assets manually. It’s a real boring and time wasting task, especially in the long run.

So now you’ve no excuses, this module requires no more than a few minutes to be installed and configured. Go and give it a try! And… after having configured your assets, don’t forget to enable AssetModule’s cache. That’s really a must to offer decent website performance and hence a good user experience.

For those who prefer a talk-like explanation, the extract of my Zend Framework Day presentation about this topic can be found here.

Image credit: http://www.flickr.com/photos/tracyleephoto/8322509672