Apart from a new post, I will be paying attention to an older article on this blog about module configuration in Zend Framework. It is still a hot subject, and I have gotten some good questions and remarks from many commenters. I will answer all these questions, show more source code as requested and maybe I’ll even listen to some suggestions.

The object I wanted to assign was an instance of Zend Form assigned to the view on the key ‘commentForm’. Of course without reading the documentation, this is what I put in the view script where I wanted to include the partial:

<?php echo $this->partial('blogpost/new-comment.phtml', $this->commentForm); ?>

This didn’t work, as I found out that the object contained in $this-commentForm was converted to array and assigned as properties to the view instance of the partial. This is done either by calling toArray() on the object if the method exists, or by using get_object_vars on the object.

This is not what I wanted. I wanted to have full use of my form object in my partial. When I finally did read the manual entry about partials, I found that there was actually a way to do this, but not a very practical way. You call the method setObjectKey(‘keyname’) on the partial helper like so:

<?php $this->partial()->setObjectKey('commentForm'); ?>

If you do this first and then assign an object to a partial as above, the object gets assigned to the view instance of the partial on the key we set with setObjectKey(). Thus, we have full use of the object in the partial.

There are a couple of drawbacks to this way of doing it. First, it is irritating that I have to call setObjectKey() every time I want to do this. Second, the view script becomes less readable if I have to include this kind of code. Third, but I have yet to test this, it seems to me that the object key is set for all partials when you use setObjectKey(). This may have some unwanted side effects if you are not careful.

Here is my solution to this ‘problem’. In my eyes, it makes setObjectKey obsolete. Why not just assign an array to the partial, containing my form object like this:

<?php echo $this->partial('blogpost/new-comment.phtml', array('commentForm' => $this->commentForm)); ?>

I know, it is too simple. So simple even, that I overlooked this possibility at first. And the manual doesn’t help. The result is that I have found many posts on blogs and forums about this problem and the usage of setObjectKey(). I hope this post will be helpful to some of them.

Usage Example

First we load the frontcontroller plugin Rexus_Controller_Plugin_RequestedModulePluginLoader in the main application.ini:

resources.frontController.plugins.pluginloader = Rexus_Controller_Plugin_RequestedModulePluginLoader;

Then we use the Zend_Application resource Rexus_Application_Resource_Moduleplugins in our config file to load the the authentication plugin only for our module.
If you use my ModuleSetup resource as described in module config, you can set the module plugin options in the module.ini for that module :

resources.moduleplugins.auth = "Rexus_Controller_Plugin_Authentication"

or, you can set the module plugins config in your application.ini normally, as described in the Zend Framework reference:

modulename.resources.moduleplugins.auth = "Rexus_Controller_Plugin_Authentication"

The result is that the frontcontroller plugin Rexus_Controller_Plugin_Authentication is only loaded if the module ‘modulename’ is requested.

Code

class Rexus_Controller_Plugin_RequestedModulePluginLoader 
    extends Zend_Controller_Plugin_Abstract
{
    protected $_modulePlugins = array();
 
    public function registerFrontControllerPlugin($module, $pluginName)
    {
        if (array_key_exists($module, $this->_modulePlugins) 
                        && is_array($this->_modulePlugins[$module])) {
 
            array_push($this->_modulePlugins[$module], $pluginName);
        } else {
            $this->_modulePlugins[$module] = array($pluginName);
        }
    }
 
    public function routeShutdown(Zend_Controller_Request_Abstract $request)
    {
        if (isset($this->_modulePlugins[$request->getModuleName()])) {
            $frontController = Zend_Controller_Front::getInstance();
            foreach ($this->_modulePlugins[$request->getModuleName()] as $pluginName) {
                $frontController->registerPlugin( new $pluginName);
            }
        }
    }
}

Just drop this class in your library and register the plugin with the frontcontroller as shown above to use it.

Note that this plugin does its work on routeShutdown. On routShutDown is the earliest hook in the dispatch loop where the request has been parsed and routed. This is important because all plugins we register with this plugin can subsequently only be registered with the frontcontroller as early as the next step after the one on which this plugin is executed.

Next we need the code for the Zend_Application resource Rexus_Application_Resource_Moduleplugins:

class Rexus_Application_Resource_Moduleplugins 
    extends Zend_Application_Resource_ResourceAbstract
{
    public function init()
    {
        $bootstrap = $this->getBootstrap();
        $bootstrap->bootstrap('frontcontroller');
        $front = $bootstrap->getResource('frontcontroller');
        $pluginLoader = $front->getPlugin('Rexus_Controller_Plugin_RequestedModulePluginLoader');
        $options = $this->getOptions();
 
        foreach ($options as $pluginName) {
            $pluginLoader->registerFrontControllerPlugin(
                strtolower($this->getBootstrap()->getModuleName()), $pluginName);
        } 
    }
}

Of course I didn’t expect this. So I had a look at the apache logs and found entries like this:

[Wed Jul 22 16:00:26 2009] [debug] core.c(3052): [client 192.168.0.7] redirected from r->uri = /data/virtualhosts/dev/...

After some googling, I found out this has something to do with having apache rewrite rules in combination with dynamic virtualhosts. Then I had a look at an older ZF project on the same server and found a small but significant difference:

Standard .htaccess created by Zend_Tool:

SetEnv APPLICATION_ENV development
 
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} -s [OR]
RewriteCond %{REQUEST_FILENAME} -l [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^.*$ - [NC,L]
RewriteRule ^.*$ index.php [NC,L]

And here is the last line of the older .htaccess, the rest is identical:

RewriteRule ^.*$ /index.php [NC,L]

Notice the difference? There is a forward slash before index.php in the working .htaccess.
I simply added the forward slash in the non-working htaccess, and everything worked fine!

Note: this may not work for you, as I have seen articles where REMOVING the forward slash was the solution. It is entirely dependent on your specific apache config and more importantly, your apache version. This is because there have been changes in how apache matches redirects in recent releases.

Usage example

Default layout settings in application.ini:

resources.layout.layout = "default"
resources.layout.layoutPath = APPLICATION_PATH "/views/layouts"

Then, if you use my ModuleSetup resource as described in module config, you can set the module layout options in the module.ini for that module:

resources.layout.layout = "modulename_default"
 
; this layoutpath is relative to the directory of the module itself
; in this case: application/modules/modulename/views/layouts
resources.layout.layoutPath = "views/layouts"

or, you can set the module config in your application.ini normally, as described in the Zend Framework reference:

modulename.resources.layout.layout = "modulename_default"
 
; this layoutpath is relative to the directory of the module itself
; in this case: application/modules/modulename/views/layouts
modulename.resources.layout.layoutPath = "views/layouts"

* note: you can set all options for module layouts sources the same way as for the application layout resource. If you don’t specify a different layoutPath, the standard path is used

The result is that when the module ‘modulename’ is requested, the layout ‘modulename_default.phtml’ in the directory ‘application/modules/modulename/views/layouts’ is used. Otherwise, the main layout is used.

Code

class Rexus_Controller_Plugin_RequestedModuleLayoutLoader
    extends Zend_Controller_plugin_Abstract
{
    public function preDispatch(Zend_Controller_Request_Abstract $request)
    {
        $config     = Zend_Controller_Front::getInstance()
                            ->getParam('bootstrap')->getOptions();
        $moduleName = $request->getModuleName();
 
        if (isset($config[$moduleName]['resources']['layout']['layout'])) {
            $layoutScript = $config[$moduleName]['resources']['layout']['layout'];
            Zend_Layout::getMvcInstance()->setLayout($layoutScript);
        }
 
        if (isset($config[$moduleName]['resources']['layout']['layoutPath'])) {
            $layoutPath = $config[$moduleName]['resources']['layout']['layoutPath'];
            $moduleDir = Zend_Controller_Front::getInstance()->getModuleDirectory();
            Zend_Layout::getMvcInstance()->setLayoutPath(
                $moduleDir. DIRECTORY_SEPARATOR .$layoutPath
            );
        }
    }
}

To use this, drop the class above in your library and set the following in your application.ini:

resources.frontController.plugins.layoutloader = Rexus_Controller_Plugin_RequestedModuleLayoutLoader

If you want to know more about handling other types of resources with modules, check my post about module translation sources

The standard zend application resource Zend_Application_Resource_Translate doesn’t support this. If you use that resource and include translate settings in your module.ini, a separate Zend_Translate instance will be added to the resource container for that module. By default, the resource also sets the registry key ‘Zend_Translate’ to the new instance every time the resource is called in the bootstrap process. Because you don’t know the module load order, you don’t know what instance the registry will contain.

This has an important drawback: the stock translate view helper, Zend_Form and other Zend_Translate aware ZF components automatically check for a Zend_Translate instance in the registry under the key ‘Zend_Translate’. This will lead to unexpected results.

There are workarounds, but they are not convenient in my opinion. Another example: to get at the translations for your module from your controller, you would have to do this:

$moduleTranslate = $this->getInvokeArg('bootstrap')->getResource('modules')
        ->offsetGet('modulenamehere')->getResource('translate');

to get to the main translate instance:

$mainTranslate = $this->getInvokeArg('bootstrap')->getResource('translate');

And the shortest version could not be used, because you wouldn’t know which instance it contains!

$unknownTranslate = Zend_Registry::get('Zend_Translate');

My solution was building a slightly different version of Zend_Application_Resource_Translate. It checks if the registry key is already set first. If not, it creates a new instance of Zend_Translate and assigns it to the registry. If there already is a registry key, the resource fetches the existing instance and calls addTranslation on it. This way, all your translation sources are neatly merged.

Usage example

Default translate settings in application.ini:

resources.translate.data = APPLICATION_PATH "/languages"
resources.translate.adapter = "Array"
resources.translate.options.scan = "filename"

Then, if you use my ModuleSetup resource as described in module config, you can set the module translation options in the module.ini for that module:

resources.translate.data = APPLICATION_PATH "/modules/modulename/languages"

or, you can set the module config in your application.ini, as described in the Zend Framework reference:

modulename.resources.translate.data = APPLICATION_PATH "/modules/modulename/languages"

* note: you can set all options for module translation sources the same way as for the application translate resource, except ‘adapter’. This is because Zend_Translate::addTranslation doesn’t support it.

application/languages/nl.php:

return array(
	'application' => 'applicatie',
);

application/modules/modulename/languages/nl.php:

return array(
	'module example' => 'module voorbeeld',
);

After bootstrap, Zend_Registry::get(‘Zend_Translate’) contains the merged tranlation sources. A var_dump of Zend_Registry::get(‘Zend_Translate’)->getMessages() will show:

array
    'application' => string 'applicatie' (length=10)
    'module example' => string 'module voorbeeld' (length=16)

Code

class Rexus_Application_Resource_Translate extends Zend_Application_Resource_ResourceAbstract
{
    const DEFAULT_REGISTRY_KEY = 'Zend_Translate';
 
    /**
     * @var Zend_Translate
     */
    protected $_translate;
 
    /**
     * Defined by Zend_Application_Resource_Resource
     *
     * @return Zend_Translate
     */
    public function init()
    {
        /*
         * The translate settings for the application.ini should be loaded first
         * to set all necessary defaults, most importantly the adapter to use
         *
         * Since we can't know the load order of modules and/or application bootstrap
         * we set the application translate as dependecy if we are not the main Bootstrap
         */
        if ('Bootstrap' !== get_class($this->getBootstrap())) {
            $this->getBootstrap()->getApplication()->bootstrap('translate');
        }
        return $this->getTranslate();
    }
 
    /**
     * Retrieve translate object
     *
     * @return Zend_Translate
     */
    public function getTranslate()
    {
        $options = $this->getOptions();
 
        if (!isset($options['data'])) {
            throw new Zend_Application_Resource_Exception(
                'No translation source data provided in the ini file for: '
                . get_class($this->getBootstrap()).'.'
            );
        }
 
        $adapter = isset($options['adapter']) ? $options['adapter'] : Zend_Translate::AN_ARRAY;
        $locale = isset($options['locale']) ? $options['locale'] : null;
        $translateOptions = isset($options['options']) ? $options['options'] : array();
 
        $key = ( isset ($options['registry_key']) && !is_numeric($options['registry_key']))
             ? $options['registry_key']
             : self::DEFAULT_REGISTRY_KEY;
 
        // If no translate object was set in the registry we create it.
        if (!Zend_Registry::isRegistered($key)) {
            $this->_createTranslation($adapter, $options['data'], $locale, $translateOptions);
 
        // if there is, we should add a translation source to the existing translate object
        } elseif (Zend_Registry::isRegistered($key)) {
            $this->_translate = Zend_Registry::get($key);
            $this->_addTranslation($options['data'], $locale, $translateOptions);
        }
 
        Zend_Registry::set($key, $this->_translate);
 
        return $this->_translate;
    }
 
    protected function _createTranslation($adapter, $data, $locale, $options)
    {
        $this->_translate = new Zend_Translate(
            $adapter, $data, $locale, $options
        );
    }
 
    protected function _addTranslation($data, $locale, $options)
    {
        $this->_translate->addTranslation(
            $data, $locale, $options
        );
    }
}

To use this resource instead of the stock one, just drop it into your library. It will automatically be chosen over the stock one, because it has the same name. Of course, this only works correctly if you set the prefix and path for your resources in your application.ini like this:

pluginPaths.Rexus_Application_Resource = "Rexus/Application/Resource"

Improvements and comments are always welcome.

Now that there is Zend Application with the Modules Resource, that is almost possible. There is one problem. The module specific config still has to be put in application.ini. On the Zend Framework mailinglists, many people are clamoring for module specific configuration files. In this article I will explain how to set up modules with their own config files.

Of course as a good developer should, I first started searching for a solution by someone else. I found lots of complaints, but no solutions, until I happened upon Jeroen Keppens’ blog. He has been busy creating a solution to this problem as can be read in this post.

In a nutshell, his solution is this: he has extended Zend_Application_Module_Bootstrap to automatically register and execute a bootstrap resource called Moduleconfig, that searches for ini files in the configs directory of the module. These ini settings are then used as the options for the module bootstrap. This way, a module can set up its own resources.

This is a valid approach and it works, but I had a few problems with it.

• I found it impossible to load a frontcontroller plugin in the module config. The frontcontroller resource would get called by the module bootstrap, but the frontcontroller bootstrap resource looks at the application options for plugins and ignores module options so it would do nothing.
• A nitpick: the settings from the module ini files don’t become part of the main application options. This makes them harder to get at in your controllers. Instead of

  $this->getInvokeArg('bootstrap')->getOptions();

  you need to do this:

  $this->getInvokeArg('bootstrap')->getResource('modules')
          ->offsetGet('modulenamehere')->getOptions();

I have come up with a solution that is strongly based on Jeroen’s solution, but with an important difference. Instead of letting each module bootstrap get its own config when it is bootstrapped, I chose to create a resource for the main bootstrap that looks for config files in all module config directories and merges them with the application options. This way, the application options array looks the same as if you would have put the ini settings directly in the application.ini.

First, I will show you how to use this solution. Then I’ll share my code with you so you can use it for yourself.

Usage

In your application.ini, you set the resources to be loaded. Note that the resources are loaded in the order you provide them. The Bootstrap resource that is going to do the module setup for us is called Modulesetup. It needs to be loaded as the very first resource, so put it at the top of you [production] segment:

resources.modulesetup[] =

Directly after that I set the modules resource, so that all module-specific resources are loaded first:

resources.modules[] =

Then we create a module.ini in /path/to/application/modules/modulename/configs/module.ini. In that file you can set anything you want, just as if you set it in application.ini. There is one difference: in application.ini you would set it like so:

modulename.resources.frontcontroller.plugins.foo = bar

In your module.ini, you don’t have to set the module prefix, this is done for you:

resources.frontcontroller.plugins.foo = bar

You can now get at your module specific settings in the following ways:

$this->getInvokeArg('bootstrap')->getOption('modulenamehere');

the same but longer:

$this->getInvokeArg('bootstrap')->getResource('modules')
       ->offsetGet('modulenamehere')->getOptions();

And to get your module specific loaded resources:

$this->getInvokeArg('bootstrap')->getResource('modules')
        ->offsetGet('modulenamehere')->getResource('resourcenamehere');

Code

All you need is the following class:

class Rexus_Application_Resource_Modulesetup
    extends Zend_Application_Resource_ResourceAbstract
{
    public function init()
    {
        $this->_getModuleSetup();
    }
 
    /**
     * Load the module's ini files
     *
     * @return void
     */
    protected function _getModuleSetup()
    {
        $bootstrap = $this->getBootstrap();
 
        if (!($bootstrap instanceof Zend_Application_Bootstrap_Bootstrap)) {
            throw new Zend_Application_Exception('Invalid bootstrap class');
        }
 
        $bootstrap->bootstrap('frontcontroller');
        $front = $bootstrap->getResource('frontcontroller');
        $modules = $front->getControllerDirectory();
 
        foreach (array_keys($modules) as $module) {
            $configPath  = $front->getModuleDirectory($module) 
                         . DIRECTORY_SEPARATOR . 'configs';
            if (file_exists($configPath)) {
                $cfgdir = new DirectoryIterator($configPath);
                $appOptions = $this->getBootstrap()->getOptions();
 
                foreach ($cfgdir as $file) {
                    if ($file->isFile()) {
                        $filename = $file->getFilename();
                        $options = $this->_loadOptions($configPath 
                                 . DIRECTORY_SEPARATOR . $filename);
                        if (($len = strpos($filename, '.')) !== false) {
                            $cfgtype = substr($filename, 0, $len);
                        } else {
                            $cfgtype = $filename;
                        }
 
                        if (strtolower($cfgtype) == 'module') {
                            if (array_key_exists($module, $appOptions)) {
                                if (is_array($appOptions[$module])) {
                                    $appOptions[$module] =
                                        array_merge($appOptions[$module], $options);
                                } else {
                                    $appOptions[$module] = $options;
                                }
                            } else {
                                $appOptions[$module] = $options;
                            }
                        } else {
                            $appOptions[$module]['resources'][$cfgtype] = $options;
                        }
                    }
                }
                $this->getBootstrap()->setOptions($appOptions);
            } else {
                continue;
            }
        }
    }
 
    /**
     * Load the config file
     *
     * @param string $fullpath
     * @return array
     */
    protected function _loadOptions($fullpath)
    {
        if (file_exists($fullpath)) {
            switch(substr(trim(strtolower($fullpath)), -3))
            {
                case 'ini':
                    $cfg = new Zend_Config_Ini($fullpath, $this->getBootstrap()
                                                    ->getEnvironment());
                    break;
                case 'xml':
                    $cfg = new Zend_Config_Xml($fullpath, $this->getBootstrap()
                                                    ->getEnvironment());
                    break;
                default:
                    throw new Zend_Config_Exception('Invalid format for config file');
                    break;
            }
        } else {
            throw new Zend_Application_Resource_Exception('File does not exist');
        }
        return $cfg->toArray();
    }
}

Put it in your library directory and don’t forget to set the prefix for your own resources in your application.ini like so:

pluginPaths.Rexus_Application_Resource = "Rexus/Application/Resource"

I use Rexus as the prefix for all my own stuff, but you can change this of course.

I am curious what you think.

edit: comment from Michel: changed the way the module directory is determined from hardcoded to dynamic

Let’s get started right away: I have started finetuning a generic grid component for Zend Framework that I have been using for my own projects for a while now. In my experience it severely cuts development time of web applications; because as we all know, web applications are at their core nothing more than lists and CRUD. There is a limitation that many people will regret: it can’t do everything. I will post the first draft with documentation soon.