Marco Pivetta (Ocramius)

JS/CSS/Images with Zend Framework 2 and the Asset Manager Module

RWOverdijk's AssetManager

This blog post is about a module that I and Roberto Wesley Overdijk developed last month. It is called AssetManager and its aim is to simplify how you currently store and serve assets (JS/CSS/images/etc.) in your ZF2 applications.

ZF2 Module structure

When Matthew Weier O'Phinney blogged about Why Conventions Matter in ZF2 Modules, we were still defining the basic concepts of modules, and didn't really have a decent solution about how to serve assets. The idea is to ship assets with modules themselves, thus avoiding to copy files to your public/ directory each time you start with a new project (copying is almost never a good thing, you know that!).

AssetManager solves this problem and is a high quality and well tested module.

Let's get started

We will use a standard ZF2 skeleton application and Composer: 

~$ git clone git://github.com/zendframework/ZendSkeletonApplication.git
Cloning into 'ZendSkeletonApplication'...

~$ cd ZendSkeletonApplication

~$ ./composer.phar install
Loading composer repositories with package information
Installing dependencies
  - Installing zendframework/zendframework (2.0.0)
    Downloading: 100%

~$ ./composer.phar require rwoverdijk/assetmanager
Please provide a version constraint for the rwoverdijk/assetmanager requirement: *
composer.json has been updated
Loading composer repositories with package information
Updating dependencies
  - Installing kriswallsmith/assetic (v1.0.4)
    Downloading: 100%

  - Installing rwoverdijk/assetmanager (1.0.0)
    Downloading: 100%

Writing lock file
Generating autoload files

Don't forget to enable the module in your config/application.config.php!

<?php
return array(
    'modules' => array(
        'AssetManager',
        'Application',
    ),
    // ... other configs ...

Assets

To verify that everything works, we will add a simple asset that will just paint everything in our page as green (just to make things really really obvious). It will be our module/Application/public/test-asset.css (The public dir does not yet exist in the skeleton application, you will need to create it): 

* {color: green;}

We now need to teach the AssetManager where to look for our assets. To do so, we will edit our module's configuration. Now let's go to module/Application/config/module.config.php, we need to add following configuration: 

<?php
return array(
    'asset_manager' => array(
        'resolver_configs' => array(
            'paths' => array(
                'Application' => __DIR__ . '/../public',
            ),
        ),
    ),
);

This basically means that any request that couldn't be routed to a controller will check also within our module's public/ dir and eventually serve an asset from there.

Warning! By configuring your application this way, you're basically telling PHP to serve any content from within your module's public/ dir. This also means PHP sources (as text) if there are any in there. Keep it in mind!

Checking if it works

Once you've done all this, open your browser and go to http://localhost/path/to/ZendSkeletonApplication/public/test-asset.css. You should see the contents we wrote in the CSS file before.

That's it! You can now add your CSS file in your module/Application/view/layout/layout.phtml as following if you want: 

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

Enjoy! You can now build your modules to ship any images, js or generally assets!

This Asset Manager supports more kinds of resolver strategies, such as maps, asset collections (to get compiled JS/CSS), filters, caching, asset priorities and more. Most of all this is already implemented, but check the project page on github for more amazing features!

Tags: zf2, module, assets