Modular Zend Framework Skeleton 2009

So the application skeleton series proved to be more popular than I was expecting. Unfortunately after a couple of server migrations, the source code examples that were linked to those articles did not survive the trip. I’ve gotten a lot of comments to restore those examples so I decided to write a new article to illustrate the latest version of the application skeleton I’ve been using for my applications.  Since I’ve gone over much of the design philosiphy in the previous articles I won’t go into too much detail about other than to demonstrate a solid way to design MVC applications using the Zend Framework.

For those who have no clue what I’m talking about, you can review the archives here:

http://blog.realmofzod.com/2008/03/19/modular-zend-framework-application-skeleton-part-1-folder-structure/

http://blog.realmofzod.com/2008/03/19/modular-zend-framework-application-skeleton-part-2-crud/

http://blog.realmofzod.com/2008/06/06/modular-zend-framework-skeleton-part-3-modules/

The only major deviation I have made from the past versions of the skeleton is the migration from Zend_Db to Doctrine and the use of domain model programming which only affects the module model folders. For more on this, see my recent article about it.

First of all the folder structure hasn’t changed much from my previous incarnations:

• app/
  • default/
• config/config.xml
• lib/
  • Zend/
  • FP/
  • Doctrine/
  • bootstrap.php
  • cache.php
  • config.php
  • database.php
  • Doctrine.php
  • init.php
  • locale.php
  • logger.php
  • mail.php
  • modules.php
  • view.php
• log/
• plugins/
• public/
  • assets/
  • .htaccess
  • index.php
• tmp/

The public folder serves as the document root for the entire application and is the only folder that can be accessed from the web. It’s purpose should be to only house client-side assets, the .htaccess file and the front controller which is the only php file in that folder.

.htaccess

DirectoryIndex index.php

RewriteEngine on

RewriteBase /

RewriteCond %{REQUEST_URI} !assets\/.*
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule .* index.php [QSA,NC,L]

All we are doing here is redirecting any requests that do not directly access files in the assets folder to be processed by the front controller in index.php. This will pass along any query strings and paramters to the php.

index.php

The front controller routes all requests to the appropriate controller. This file includes the bootstrap file which initializes the application platform and is then configured to handle all thrown exceptions by the error controller plugin simply by passing false to throwExceptions().

The core of the platform is still housed in the lib folder which breaks up the bootstrap process into individual files, each handling a particular subsystem (logging, database, locale, etc). Additionally, any third party libraries that are required by your application can be housed here (I usually have Zend, PHPTAL, and Doctrine living here). My general philosiphy regarding lib files is that they are 100% application agnostic and for no reason should they ever be edited to accomodate a particular application (Unless you are performing upgrades which can carry over to your next project). These files are all tied together and included in bootstrap.php. The guts of the platform is designed to be a black box that can be used in any situation.

bootstrap.php

As you can see this file serves only to configure the base include paths, initialize the autoloader and to require all the necessary subsystem files. This allows us to keep the front controller file simple by only having to require one file. I’ve seen alot of examples that extend the front controller in a custom bootstrap class but I find that this approach makes it difficult to break out different functionality into independent files.

Each file in the lib folder, as I’ve said, manages a particular piece of the platform. As each file is included,  all the necessary Zend classes are created and configured, pulling their configurations from the platform configuration xml file located in config.

config.xml

The xml is layed out in a way that implements staging, allowing the developer to switch between debug and production modes that allow for subsystems to behave differently in each state simply by changing the value in mode. Within each staging node, subsystem configs are broken out into individual nodes. Most subsystems can be toggled on and off with the ‘enabled’ value. For the sake of performance this file gets cached regardless of the staging mode so changes will only be reflected once the cached files have been cleared.

cache.php

This file sets up everything we need to perform caching on objects and html. It defines a number of functions globally which can be used any in our application and will perform automatic serialization and key hashing. Cache files are stored centrally in the tmp folder and can be cleared simply by being deleted.

config.php

This file loads the platform configuration from the xml file and stores the config object in the Registry for other systems to access it. First the mode node is read to determine which staging configuration to load and then the appropriate configuration is loaded.

locale.php

Next the locale settings are applied. This probably deserves a topic all on its own but in a nutshell it sets the application locale default and if the locale config specifies the presence of translation files, a Zend_Translate object is initialized and loaded into the registry for the views to use.

logger.php

If logging is enabled, a logger object is instantiated and placed in the registry. The default logger simply writes timestamped messages to a file in the log folder, otherwise a null log writer is created allowing logged messages to go into limbo if logging is not desired or increased performance is needed.

database.php

This file creates and tests the database connection manager.

mail.php

This file configures the default mail transport adapter. By default, it relies on the built in sendmail functionality that Zend_Mail uses to defer to the server’s mail transport. Alternatively, it can be configured to use a configured smtp transport.

view.php

The view subsystem configures Zend’s view module with the plugin of our choice. Our configuration implements a PHPTAL view plugin but it can easily be swapped out with something like Smarty or even left to the default phtml implemenation. View plugin specific configuration options are passed into the getViewEngine function which is globally accessible, allowing different application modules within our application to utilize different view engines. An example of why this is useful is having our main web application use PHPTAL for displaying templates, however, perhaps we have an enhanced mail module which utilizes Smarty to render email templates. In addition to configuring the view engine, this file also sets various defaults for some of the view helpers such as the default doctype, and additional view helper paths. I store highly reusable view helpers in the lib folder also, so we include that folder in our view helpers path as well to make them available globally.

modules.php

This subsystem is the heart of the platform. In a nutshell the purpose of this file is to scan the app folder for application modules and load them. Loading them implies extending our include path to make module lib files available as well as module specific models. The easiest way for me to explain what the module loader is doing is to break it down into steps.

1. Scan app folder

2. For each subfolder in the app folder, call registerModule on the module broker, passing in the name of the module folder and pass by reference the global config object.

3. If the module has not already been loaded, look for the module’s config xml file located in ‘app/$modulefolder/config/config.xml’. Load the appropriate staging config for that module and merge it into the global config object. This allows us to access the configuration for any application module using the same config object.

4. Determine if this module has dependencies it requires before it can load. This means some app modules might require classes defined by other app modules. If the dependency module has not been loaded yet, the current module load can be deferred until the necessary dependencies are in place. If the load is deferred, registerModule() simply returns. Otherwise, we continue.

5. Include the module’s models folder in the include path.

6. Add the module’s lib folder in the include path. Inside that folder, we expect to find a file called module.php which contains the application module class we need to load. Every valid module should have this file and the appropriate class defined inside. The module class name is constructed using the module folder name. If the module folder is ‘blog’, then the module class name is ‘BlogModule’. Alternately, if the module folder is ‘news_feed’, then the module class name is ‘NewsFeedModule’. It will always follow this convention.

7. Once we have the module class name we then instantiate the class. If all goes well, we should have a module object now that we can query for information we need about the module. Specifically we want to know what routes the module provides. All modules must implement the interface defined in our modules.php file which enforces the implementation of two critical module methods: getRoutes() and init(). The getRoutes() method returns an array of Zend_Controller_Router_Route objects which are registered with the front controller.

8. Call init() on the module. Since application modules get cached to boost performance, init gets called to initialize transient variables that cannot carry over between requests.

9. Scan list of deferred modules that are still waiting for dependencies to load. If all dependencies for a deferred moule are in place, call registerModule() again for that module.

This happens for each folder in the app folder, the only special case being the ‘default’ folder which always gets called last. the default module is our custom application and it gets loaded last because it will always depend on the other modules to be loaded first.  After all the modules have been loaded, we do one more sweep and call postInit() on any modules that offer the method. This is a great way to do processing on all of the modules once they are all loaded. It might help to understand this better once I demonstrate an example of an application module. See below for the example.

The last file to get parsed in the bootstrap is init.php

init.php

This file is more or less a spill over for bootstrap operations that either don’t go any where else or rely on all the subsystems being loaded already. As you can see I use it for assigning a boat load of convenience varialbe to the registry for use throughout the application.

So now I want to demonstrate the structure of a real world application module. I’ll demonstrate my ACL module I recently wrote to handle security for most of my applications. It’s purpose is to generate Access Control Lists to manage access to secure resources, roles, users, and permissions. Here is it’s folder structure:

• app/
  • acl/
    • config/config.xml
    • controllers/
    • lib/
      • module.php
    • models/
    • views/
      • helpers/
      • layouts/
      • templates/
  • default/
  • …

config and lib are technically the only folders required for a functional module but usually you will need controllers and views as well. Each module is comprised of it’s module class, a config.xml file, some controllers, some models, and view components which are usually templates, helpers, and layouts. They are arranged heirarchichly like those so they can be simply dumped into the app folder drag’n'drop like. Application modules act very much like plugins for your main web application. They can provide a variety of functionality such as providing forum features, blog features, content management, etc, whatever you can imagine.

The heart of a module is the module class defined in ‘lib/module.php’

acl/lib/module.php

I have snipped out much of the implementation to remain in scope of the article so you can see the methods that comply with the FP_Application_Module interface. These are the minimum methods needed to be loaded by the module loader.

app/acl/config/config.xml

The specifics of the configuration info specified in this file isn’t so important as it is completely arbitrary and tailored to what the individual module expects to find there. The key is to make sure that the configuration is contained within a node that shares the name of the module folder, ‘acl’ in this case so it can be properly merged into the global config object and be readily accessed by name.

So there’s a number of classes I covered in the archived post but not in this one and that’s only because of the sheer volume of code and I didn’t want this post to become too overwhelming. The older posts were intended to be an introduction to Zend Framework MVC methodologies whereas this post is mainly a refresher on the latest methods I use and should build on those topics. To fill in the gaps, i’ve made the code available for a skeleton app available here so everyone can review the code and re-use it for their own projects.