Getting started writing ZF2 modules

 

Getting started writing ZF2 modules

During ZendCon this year, we released 2.0.0beta1 of Zend Framework. The key story in the release is the creation of a new MVC layer, and to sweeten the story, the addition of a modular application architecture.

"Modular? What's that mean?" For ZF2, "modular" means that your application is built of one or more "modules". In a lexicon agreed upon during our IRC meetings, a module is a collection of code and other files that solves a specific atomic problem of the application or website.

As an example, consider a typical corporate website in a technical arena. You might have:

• A home page
• Product and other marketing pages
• Some forums
• A corporate blog
• A knowledge base/FAQ area
• Contact forms

These can be divided into discrete modules:

• A "pages" modules for the home page, product, and marketing pages
• A "forum" module
• A "blog" module
• An "faq" or "kb" module
• A "contact" module

Furthermore, if these are developed well and discretely, they can be re-used between different applications!

So, let's dive into ZF2 modules!

What is a module?

In ZF2, a module is simply a namespaced directory, with a single "Module" class under it; no more, and no less, is required.

So, as an example:

<span modules/
    FooBlog/
        Module.php
    FooPages/
        Module.php
</span>

The above shows two modules, "FooBlog" and "FooPages". The "Module.php" file under each contains a single "Module" class, namespaced per the module: FooBlog\Module andFooPages\Module, respectively.

This is the one and only requirement of modules; you can structure them however you want from here. However, we do have a recommended directory structure:

<span modules/
    SpinDoctor/
        Module.php
        configs/
            module.config.php
        public/
            images/
            css/
                spin-doctor.css
            js/
                spin-doctor.js
        src/
            SpinDoctor/
                Controller/
                    SpinDoctorController.php
                    DiscJockeyController.php
                Form/
                    Request.php
        tests/
            bootstrap.php
            phpunit.xml
            SpinDoctor/
                Controller/
                    SpinDoctorControllerTest.php
                    DiscJockeyControllerTest.php
</span>

The important bits from above:

• Configuration goes in a "configs" directory.
• Public assets, such as javascript, CSS, and images, go in a "public" directory.
• PHP source code goes in a "src" directory; code under that directory should follow PSR-0 standard structure.
• Unit tests should go in a "tests" directory, which should also contain your PHPUnit configuration and bootstrapping.

Again, the above is simply a recommendation. Modules in that structure clearly dileneate the purpose of each subtree, allowing developers to easily introspect them.

The Module class

Now that we've discussed the minimum requirements for creating a module and its structure, let's discuss the minimum requirement: the Module class.

The module class, as noted previously, should exist in the module's namespace. Usually this will be equivalent to the module's directory name. Beyond that, however, there are no real requirements, other than the constructor should not require any arguments.

<span <code lang="php">
namespace FooBlog;

class Module
{
}
</code></span>

So, what do module classes do, then?

The module manager (class Zend\Module\Manager) fulfills three key purposes:

• It aggregates the enabled modules (allowing you to loop over the classes manually).
• It aggregates configuration from each module.
• It triggers module initialization, if any.

I'm going to skip the first item and move directly to the configuration aspect.

Most applications require some sort of configuration. In an MVC application, this may include routing information, and likely some dependency injection configuration. In both cases, you likely don't want to configure anything until you have the full configuration available -- which means all modules must be loaded.

The module manager does this for you. It loops over all modules it knows about, and then merges their configuration into a single configuration object. To do this, it checks each Module class for a getConfig() method.

The getConfig() method simply needs to return an array or Traversable object. This data structure should have "environments" at the top level -- the "production", "staging", "testing", and "development" keys that you're used to with ZF1 and Zend_Config. Once returned, the module manager merges it with its master configuration so you can grab it again later.

Typically, you should provide the following in your configuration:

• Dependency Injection configuration
• Routing configuration
• If you have module-specific configuration that falls outside those, the module-specific configuration. We recommend namespacing these keys after the module name: foo_blog.apikey = "..."

The easiest way to provide configuration? Define it as an array, and return it from a PHP file -- usually your configs/module.config.php file. Then your getConfig() method can be quite simple:

<span <code lang="php">
public function getConfig()
{
    return include __DIR__ . '/configs/module.config.php';
}
</code></span>

In the original bullet points covering the purpose of the module manager, the third bullet point was about module initialization. Quite often you may need to provide additional initialization once the full configuration is known and the application is bootstrapped -- meaning the router and locator are primed and ready. Some examples of things you might do:

• Setup event listeners. Often, these require configured objects, and thus need access to the locator.
• Configure plugins. Often, you may need to inject plugins with objects managed by the locator. As an example, the url() view helper needs a configured router in order to work.

The way to do these tasks is to subscribe to the bootstrap object's "bootstrap" event:

<span <code lang="php">
$events = StaticEventManager::getInstance();
$events->attach('bootstrap', 'bootstrap', array($this, 'doMoarInit'));
</code></span>

That event gets the application and module manager objects as parameters, which gives you access to everything you might possibly need.

The question is: where do I do this? The answer: the module manager will call a Module class's init() method if found. So, with that in hand, you'll have the following:

<span <code lang="php">
namespace FooBlog;

use Zend\EventManager\StaticEventManager,
    Zend\Module\Manager as ModuleManager

class Module
{
    public function init(ModuleManager $manager)
    {
        $events = StaticEventManager::getInstance();
        $events->attach('bootstrap', 'bootstrap', array($this, 'doMoarInit'));
    }
    
    public function doMoarInit($e)
    {
        $application = $e->getParam('application');
        $modules     = $e->getParam('modules');
        
        $locator = $application->getLocator();
        $router  = $application->getRouter();
        $config  = $modules->getMergedConfig();
        
        // do something with the above!
    }
}
</code></span>

As you can see, when the bootstrap event is triggered, you have access to theZend\Mvc\Application instance as well as the Zend\Module\Manager instance, giving you access to your configured locator and router, as well as merged configuration from all modules! Basically, you have everything you could possibly want to access right at your fingertips.

What else might you want to do during init()? One very, very important thing: setup autoloading for the PHP classes in your module!

ZF2 offers several different autoloaders to provide different strategies geared towards ease of development to production speed. For beta1, they were refactored slightly to make them even more useful. The primary change was to the AutoloaderFactory, to allow it to keep single instances of each autoloader it handles, and thus allow specifying additional configuration for each. As such, this means that if you use theAutoloaderFactory, you'll only ever have one instance of a ClassMapAutoloader orStandardAutoloader -- and this means each module can simply add to their configuration.

As such, here's a typical autoloading boilerplate:

<span <code lang="php">
namespace FooBlog;

use Zend\EventManager\StaticEventManager,
    Zend\Loader\AutoloaderFactory,
    Zend\Module\Manager as ModuleManager

class Module
{
    public function init(ModuleManager $manager)
    {
        $this->initializeAutoloader();
        // ...
    }
    
    public function initializeAutoloader()
    {
        AutoloaderFactory::factory(array(
            'Zend\Loader\ClassMapAutoloader' => array(
                include __DIR__ .  '/autoload_classmap.php',
            ),
            'Zend\Loader\StandardAutoloader' => array(
                'namespaces' => array(
                    __NAMESPACE__ => __DIR__ . '/src/' .  __NAMESPACE__,
                ),
            ),
        ));
    }
</code></span>

During development, you can have autoload_classmap.php return an empty array, but then during production, you can generate it based on the classes in your module. By having the StandardAutoloader in place, you have a backup solution until the classmap is updated.

Now that you know how your module can provide configuration, and how it can tie into bootstrapping, I can finally cover the original point: the module manager aggregates enabled modules. This allows modules to "opt-in" to additional features of an application. As an example, you could make modules "ACL aware", and have a "security" module grab module-specific ACLs:

<span <code lang="php">
    public function initializeAcls($e)
    {
        $this->acl = new Acl;
        $modules   = $e->getParam('modules');
        foreach ($modules->getLoadedModules() as $module) {
            if (!method_exists($module, 'getAcl')) {
                continue;
            }
            $this->processModuleAcl($module->getAcl());
        }
    }
</code></span>

This is an immensely powerful technique, and I'm sure we'll see a lot of creative uses for it in the future!

Composing modules into your application

So, writing modules should be easy, right? Right?!?!?

The other trick, then, is telling the module manager about your modules. There's a reason I've used phrases like, "enabled modules" "modules it [the module manager] knows about," and such: the module manager is opt-in. You have to tell it what modules it will load.

Some may say, "Why? Isn't that against rapid application development?" Well, yes and no. Consider this: what if you discover a security issue in a module? You could remove it entirely from the repository, sure. Or you could simply update the module manager configuration so it doesn't load it, and then start testing and patching it in place; when done, all you need to do is re-enable it.

Loading modules is a two-stage process. First, the system needs to know where and how to locate module classes. Second, it needs to actually load them. We have two components surrounding this:

• Zend\Loader\ModuleAutoloader
• Zend\Module\Manager

The ModuleAutoloader takes a list of paths, or associations of module names to paths, and uses that information to resolve Module classes. Often, modules will live under a single directory, and configuration is as simple as this:

<span <code lang="php">
$loader = new Zend\Loader\ModuleAutoloader(array(
    __DIR__ . '/../modules',
));
$loader->register();
</code></span>

You can specify multiple paths, or explicit module:directory pairs:

<span <code lang="php">
$loader = new Zend\Loader\ModuleAutoloader(array(
    __DIR__ . '/../vendors',
    __DIR__ . '/../modules',
    'User' => __DIR__ . '/../vendors/EdpUser-0.1.0',
));
$loader->register();
</code></span>

In the above, the last will look for a User\Module class in the file vendors/EdpUser-0.1.0/Module.php, but expect that modules found in the other two directories specified will always have a 1:1 correlation between the directory name and module namespace.

Once you have your ModuleAutoloader in place, you can invoke the module manager, and inform it of what modules it should load. Let's say that we have the following modules:

<span modules/
    Application/
        Module.php
    Security/
        Module.php
vendors/
    FooBlog/
        Module.php
    SpinDoctor/
        Module.php
</span>

and we wanted to load the "Application", "Security", and "FooBlog" modules. Let's also assume we've configured the ModuleAutoloader correctly already. We can then do this:

<span <code lang="php">
$manager = new Zend\Module\Manager(array(
    'Application',
    'Security',
    'FooBlog',
));
$manager->loadModules();
</code></span>

We're done! If you were to do some profiling and introspection at this point, you'd see that the "SpinDoctor" module will not be represented -- only those modules we've configured.

To make the story easy and reduce boilerplate, the ZendSkeletonApplication repository provides a basic bootstrap for you in public/index.php. This file consumesconfigs/application.config.php, in which you specify two keys, "module_paths" and "modules":

<span <code lang="php">
return array(
    'module_paths' => array(
        realpath(__DIR__ . '/../modules'),
        realpath(__DIR__ . '/../vendors'),
    ),
    'modules' => array(
        'Application',
        'Security',
        'FooBlog',
    ),
);
</code></span>

It doesn't get much simpler at this point.

Tips and Tricks

One trick I've learned deals with how and when modules are loaded. In the previous section, I introduced the module manager and how it's notified of what modules we're composing in this application. One interesting thing is that modules are processed in the order in which they are provided in your configuration. This means that the configuration is merged in that order as well.

The trick then, is this: if you want to override configuration settings, don't do it in the modules; create a special module that loads last to do it!

So, consider this module class:

<span <code lang="php">
namespace Local;

class Module
{
    public function getConfig()
    {
        return include __DIR__ . '/configs/module.config.php';
    }
}
</code></span>

We then create a configuration file in configs/module.config.php, and specify any configuration overrides we want there!

<span <code lang="php">
return array(
    'production' => array(
        'di' => 'alias' => array(
            'view' => 'My\Custom\Renderer',
        ),
    ),
);
</code></span>

Then, in our configs/application.config.php, we simply enable this module as the last in our list:

<span <code lang="php">
return array(
    // ...
    'modules' => array(
        'Application',
        'Security',
        'FooBlog',
        'Local',
    ),
);
</code></span>

Done!