Realm of Zod

Ajax - Too Much of a Good Thing

I’ve stated this many times, but working as a lead php developer at eroi has been both an adventure and educational. Each project brings new challenges, requirements, and the obligatory ‘experiments’. I’ve had the opportunity to deploy some pretty good size projects, at least what I would dub ‘enterprise’ scale websites with enough traffic to keep it humming and with that much traffic comes a good helping of feedback. One of my latest projects involved heavy use of ajax to provide eye candy and the majority of the site navigation. Some people may shriek as they read this but being powered mostly by user-driven content, SEO was not a priority. What I discovered through my own use of the site as well as overwhelming feedback from the community is that simply put… too much ajax can be detrimental to user perception. This is ironic considering this is what it was deployed to improve.

The keyword here ends up being perception. Depending on server and internet conditions, the time it takes to load an entire page is usually pretty consistent with how long an ajax request takes to respond. This means in the time it takes to populate a div with a paragraph of text, an entire page with images could have been built, rendered, and delivered. Wait…. wtf? Well let’s revisit my logic for deploying ajax so heavily:

1. Less data is transmitted so it should take less time

2. Less data is rendered so it should take less time

3. Less stuff changes on the page so there is a perceived seamlesslness

Ok now let’s explore why these are noble ideals but in practice don’t hold water.

1. The problem isn’t how much data gets downloaded unless you’re on a painfully slow connection. The average person has some form of broadband so this isn’t as critical as it used to be, although you still should make your best effort to reduce the footprint of your sites as it still matters. The problem tends to be the overhead it takes for the server to respond to a request, especially for larger enterprise style sites. Now I tend to write pretty hefty MVC sites with a lot of infrastructure in the bootstrap so I don’t have to write very much code in my controllers, (The efficiency of this is debatable but it allows me to pump out sites very quickly). This means that every minor ajax call which is intended to quickly grab a tidbit of information must invoke the entire machination of the app’s infrastructure, given the transient nature of php processes. That means apache forks, a php process is started,  the bootstrap code is executed, routes are built,  permissions are checked in the Acl, the controller is loaded and invoked, and finally a template is loaded and rendered. That’s a lot of stuff to happen in the 1 second or less that the ajax request is supposed to respond within. On a site where content is getting polled for updates on a frequent basis, you are dramatically increasing the number of requests to the server, meaning you are increasing the server load and as traffic increases, the lag between requests starts to get noticeable. What ends up happening is your user is watching your animated spinny gif for just as long as it would take for the page to reload, only its a little more annoying than the former because the user expects the content refresh to be near instantaneous.

2. It stands to reason that less content is quicker to render, but for all of the reasons why #1 doesn’t stick, #2 also fails the test.

3. This one is the double edged sword. It’s true that it is usually perceived to be snappier and more application-like when parts of pages update in response to clicked links and/or buttons rather than being forced to another page but this is only the case if it works well. We all hate to wait. Waiting for what should be a minor update is especially egregious and the user really notices because there is usually a spinner or throbber there taunting them about it. It’s like those annoying trivia commercials before a movie in the theater that no one is really interested in watching, but they have to because the show hasn’t started yet.

So let me put this all into perspective. I am not advocating using less ajax. On the contrary it’s become a critical component of modern websites, however experience is teaching me to use it only when you can get away with it. In other words, don’t make it obvious. If a user knows you are using ajax for a particular action, you are probably doing it wrong. Here are some rules of thumb that I’ve learned from my own mistakes:

Ajax calls should return very quickly and be like their namesake: Asynchronous. Blocking further action while an ajax request is being handled contributes to a negative perception about the site’s performance.

Ajax should not impede easy navigation. This means don’t break the back button. Additionally, everything that can be reached through ajax should be accessible through a permalink (ie. can be bookmarked).

Beware of queued requests. A good example of this hazard is screen name availability checking where an ajax call gets made when a text field is changed in order to query the database. As the user types, they can potentially trigger several ajax requests each performing the same operation. Make sure to cancel existing requests before making new ones otherwise the response that comes back could be stale and appear slightly shizophrenic as it updates content.

So in a nutshell I discovered most of my use of ajax in site navigation is usually pretty gratuitous and this has had a negative impact when the server load is high. I have also noticed that overuse leads to considerably more complex code on both the server side and in the javascript. The final issue is one that is a no-brainer for veteran developers, is that ajax does not always degrade gracefully. I never considered this much of a problem since most everyone with an IQ above 100 is using a modern browser, however with introduction of mobile browsers, this has become a bugabear from the shadows of the past and is once again an issue. It’s better to keep the site simple and functional and add eye candy only when available. Veterans may read this and say ‘well duh’ to all of this but my teacher has always been experience.

Implement a Rest API with the Zend Framework

As a developer and I admit that I judge the utility of a website by the availability of an API so that I can leverage it in my own projects. Most popular web services offer an API of some sort such as Flickr, Blip.TV, Youtube, Twitter, Facebook, etc. The most popular way to implement an api that is accessible to all styles of developers is to implement it using REST. In a nutshell, REST is a method of utilizing the HTTP protocol to send and retrieve information. REST leverages the various request types that HTTP supports (GET,POST,PUT,DELETE) while web browsers typically only use GET and POST to fetch web pages and submit form information. I won’t go into the intricacies of REST other than to note that the primary idea behind REST is that web services are presented in an object oriented fashion. REST urls typically comprise of a reference to an object or service of some type and an action to perform on the object. Parameters that are required to perform the requested action are provided as post variables in the header rather than as part of the url.

An example of a typical REST url for retrieving a photo would be:

http://typical.webservice.com/rest/photo/1

When accessed using the GET method of the HTTP protocol, the assumption is that you want to retrieve this photo. The response might be the image itself, or more typically it will be a JSON or XML encoded response containing a url to the image stored on a CDN. Alternately, if this same url is accessed using a DELETE request, the photo would instead be deleted and an encoded status report would be returned.

Chances are if you’re reading this article you already know all of this and just want to know how to implement this using the Zend Framework. This example utilizes controllers in an MVC style application. The first thing to understand is that REST is not implemented in the controller itself, instead the controller simply serves as a broker for various classes we have for handling different types of REST requests. Most of the boilerplate functionality is handled by an instance of  Zend_Rest_Server so all we have to do is implement our service.

In keeping with the REST philosiphy you will want to visualize how your web service will be accessed in terms of objects and their associated actions. It might help to draw up some use cases, but in this case lets keep going with our photo example. Let’s assume we want to allow users to upload photos, retrieve them, delete them, etc. Using this example, the first place to start naturally would be a class that represents Photos. Before that however, make sure you have set up your MVC application how you like it. Make sure you have written an appropriate class to represent your photo models complete with your persistence layer implementation. If you have no idea what i’m talking about, take a look at my application skeleton examples.  For those who are ready, we can implement our REST handlers now.

I like to start with a base class that contains functionality that will need to be shared across all the REST handlers. Here is a simple base class that we can extend.

This class implements one method right: authenticate(). Most web services require some form of authentication and/or api key to prevent abuse so this application shouldn’t be any different. This method is obviously just a stub as your authentication method can be whatever you prefer.

Next lets implement a default REST handler that responds to generic requests.

This class implements getVersion() which responds with the current version of the web service software. I call it the default handler because it will serve as a fallback handler when no context is specified in the REST url. The name of the method is important because that is the name of the action used in the url (Example: http://webservice.com/rest/getVersion).  This method takes two arguments ($userid and $apikey). You will notice that all REST methods will minimally require these arguments. The purpose of these arguments is so a developer implementing your API can provide their credentials. The names of these arguments map directly to the name of your request parameters (http://webservice.com/rest/getVersion?clientid=1&apikey=1234567890). These parameters can be provided as post variables as well.

All REST methods will always return an encoded response using a custom response generator Rest_Response.

The purpose of this class is to generate responses in a uniform and consistent structure. Each response regardless of the context or action should use the same structure which makes a developer implementing your API want to pull out his hair less than if each response required a completely different parser.  This class provides a static method Generate() which takes an associative array as its argument which it converts into xml. Optionally, Generate() takes a status argument which indicates whether the request Succeeded or failed. This is helpful in case the response parser needs to respond differently in the event of a failure.

So let’s make another REST handler that handles requests for photos.

This handler is a little more sophisticated. It responds to requests to upload photos, retrieve them and delete them. Just like the default handler, each method requires credentials and some take additional arguments. The upload method receives the file and generates a database record for the photo which has an id associated with it which can be returned in the response. The get() method takes an id for an argument that it uses to retrieve a database record for a photo and then returns the information associated with it. Similarly, delete() takes an idea and deletes the associated photo from the database and returns a status report.

So now we have handlers for our REST operations but we haven’t yet seen where the controller fits into all of this. As I said earlier, the controller doesn’t only acts as a broker for the REST requests. In this application we have a single controller RestController with a single method restAction()

restAction() looks pretty gnarly at first glance. Believe me when I was figuring out how to do this it started of pretty simple but rapidly evolved to handle various use cases as most code does. I’ll go over it step by step.

Obviously in order to satisfy all of the requirements of both the controller and our REST handlers we need some workable routes which directs REST requests to this action.

The first route allows us to make requests in the default context. This allows us to call http://webservice.com/rest/getVersion

The next route allows us to specify a context. For example: http://webservice.com/rest/photo/get?id=1

So first things first we need to disable the view and layout plugins since all we are interested in getting back from this action is either pure XML or JSON
. If we don’t disable the layout or view engines they will go looking for non-existant templates, or worse find some and wrap out XML or JSON in HTML.

Next we need to grab the request parameters. We strain out the parameters that get automatically appended by the controller infrastructure because they are not needed by the REST handlers.

Next we determine if there is a context in the request. This allows us to determine which REST handler we need to instantiate and invoke.

Now we instantiate a Zend_Rest_Server object and assign our custom handler. I’m sure this can be streamlined to be a little more dynamic.

And now we let the handler do its thing. If we fail to set returnResponse(), the REST server will ignore everything after this line and send its response back to the requester directly. By setting this to true, we ensure the handler will return its response to the controller so we can do some housekeeping.

In order to be truly flexible with the needs of other developers we really should offer a variety of response formats. Some developers prefer JSON while others need XML. It’s a good idea to accept a format parameter that allows the developer to specify the preferred format or assign a default format otherwise. Once we know what format to use, we need to set the Content-Type header and then send the response back to the requester.

There’s not much more to it than that, although as a footnote, I subclassed the default Zend_Rest_Server object because I wanted to to return custom XML in the event of an uncaught exception in the REST handlers.

It’s very important that you are diligent about catching exceptions and handling them properly otherwise the response can be ruined with garbage such as error messages outside of the XML or JSON, or worse, they could be blank. To use this simply instantiate this class instead of Zend_Rest_Server. So with this knowledge go forth and create. The web needs more clean and robust web services.

End of Life for Internet Explorer 6. Please.

So Microsoft has decided to begin the push of IE8 to all the unsuspecting windows users through their automatic update service and once again has done us a marginal favor out of their own necessity for relevance. With IE6 now two generations antiquated, many of the developers in the community are finding fewer reasons to humor the predominance of the broken application for any reason. Having dealt with huge corporate clients when developing web sites, even in 2009 I still get the excuse that IE6 must still be supported because it litters the workstations of their huge corporate networks, either from stubborn familiarity or a misguided cost savings attempt. I and many other developers have wasted endless hours that we will never get back tracking down bizarre css and javascript errors as well as tedious tactics to try and accommodate IE6 for not doing anything the way the rest of the world expects. With the release of version 8, IE6 has shown its age now entering its eighth year of existence which in regards to software is damn near ancient and given the dynamic nature of the web as it is intended, it really should have faded from mainstream use many years ago. But all of this, I’m certain, is serving to do nothing more than preach to the choir so forgive the rant.

The intention of this post is more or less to serve as a formal declaration of my intention as a web developer at a major digital agency that I intend to start an initiative to drop support for IE6. My personal strategy is start with the expectation that only standards compliant web browsers will be supported and additional browsers that require extreme hardship to support should be charged for accordingly. If I were running things I would make the costs prohibitive and down right punitive but I have only my opinion to sway others but I feel that it’s important to set the expectations out on the web from the onset.

I have started engaging in the tactics cited here by a sampling of norwegian web sites, by displaying annoying banners to IE6 users in order to raise awareness of their obsolescence. The problem is most people aren’t aware they are using broken software so it seems unfair to expect people to change when they see no problem. These banners are a perfect tool to participate in this campaign and do your part to rid the world of the scourge that is IE6. All of my blogs utilize this warning mechanism and I encourage everyone else involved with web development to do the same.

Asynchronous Image Loading with jQuery

I thought it would make for a good change of pace to switch gears from back end development to front end development. So far I’ve focused primarily on php development which makes sense since that is my job here at eROI. There are plenty of opportunities to get my hands dirty doing javascript development, and the folks here at eROI are not shy about their infatuation with jQuery. It’s an awesome framework for frontend development and I expect I’ll be posting more articles about it in the near future.

I recently built a media heavy site that involved loading lots of images on a page that were dynamic. Search results were displayed using thumbnails in a tile format that allowed for quick perusing, something that’s not uncommon at all. One of the annoyances I encounter often with sites that load images is that sometimes the load times for image assets can vary resulting in a broken page layout until the images finish loading.

For my latest project I had a goal to have the entire page layout to render completely and allow the images to flesh out at their leisure without having the page structure move.  The effect is pleasing to the eye with a certain ‘coolness’ factor, and by allowing images to load asynchronously using jquery, we can create callbacks to be executed by images that have finished loading. There are lots of cool things we can do with that. To make the whole process look even ‘cooler’, it would be nice to have some form kind of throbber show so that we know we are waiting for something to appear. But wait! That’s not all. One more feature we should have is to be able handle errors, for example if an image asset is missing or corrupt, rather than rely on the browser to show a broken asset indicator, (or worse: nothing at all), we should be able to show a fallback image that indicates a failure occured.

Let’s create a file called image-loader.js. At the top we need to specify a couple of variables to indicate where to pull default assets from:

The gLoadSpinnerUrl is the url of an image asset that will be shown while the real image is loading. This can be any manifestation of an ajax-ish throbber, spinner, progressbar, etc. The gFailImage is the url of the image asset to show if something bad happens and the real image becomes unavailable.

Next we create two functions that make the magic happen. The first function is LoadImage():

To this function we pass a jquery selector and an optional callback function. The selector can refer to any type of html element so long as that element has a ’src’ attribute which references the url of the real image we want to load. Typically I use a ‘div’ or an ‘a’ tag which serves as a container element for the img tag that will be dynamically created. Obviously neither of these tags has use for a ’src’ attribute so that leaves it open for us to assign an arbitrary url to it.

The LoadImage function grabs the specified element and immediately inserts an ‘img’ tag referencing our spinner image so that the end user has something to look at while it does its work. Next LoadThisImage() is called:

This function is passed the container element and the optional callback function. LoadThisImage extracts the ’src’ attribute from the container element and creates a brand new Image object in memory. The ’src’ is then assigned to our new Image and we create some callbacks on the Image by called error() load(), passing each an anonymous function to handle a possible error event and the desired load event.

In the event of an error, we change the ’src’ attribute of the image to show our failure image. If the load is successful, we begin processing any custom callbacks that are present. The first place the function checks in the container element itself. If the container element has an ‘onload’ attribute, it is assumed to have javascript assigned to it which is then evaluated. Next it checks to see if a callback function was passed to the function call manually which is also evaluated. Both callbacks are passed the image object so that they can manipulate the object after it has finished loading. This way we can do things like assign onclick events or alt tags or whatever you can think of.

For convenience we also provide a function called LoadAllImages():

This function takes no arguments. Instead it selects all elements with the class ‘.loadable-image’ and processes them the same way the container is processed in LoadImage. This can be called from a DOM ready function allowing all images on a page to be loaded asynchronously.

Here’s a real world example:

In this example we set up our container div with an image src and an inline callback. An img with the src ‘/images/example.jpg’ will be inserted into the div. When the image has downloaded, it will be passed to the javascript in the onload attribute. Since there is no function prototype to indicate parameters, we must access the passed in image dynamically with the arguments array. The callback binds a click handler to the image so that an alert appears when it is clicked. See, it’s simple.

Here’s a screenshot of a site that uses this technique to give you an idea of how it looks:

Here you can see how the page maintains it’s layout while the images are still loading. Spinners are showing for images that have not downloaded yet.

Loading your images this way adds a really cool ‘modern’ feel to the site and provides a workaround for the ugliness that can ensue as pages are rendered before they have finished downloading all of the page assets.

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.

Object Oriented GD

Sooner or later we all need to use the gd library whether it be for generating thumbnails, scaling images, cropping, or whatever. When compiled with gd support, PHP offers a massive arsenal of functions to accomplish all of the image related tasks you can think of. With the advent of object oriented frameworks such as the Zend Framework and others, it can get a little awkward mixing procedural code with with objects. Additionally code for processing images can get quite ugly with all of the variable juggling.

After a number of image heavy projects, I got tired of the cut’n'paste headache and decided that it would be much easier to maintain graphical applications that interacted with images in an object-oriented fashion. I developed a small tool chain for encapsulating images and mechanisms for processing them. I start with a simple class definition which allows me to treat an image as an object.

This class takes a file path or url as its constructor argument. Using some tricky http header sniffing we are able to determine if the provided url is actually a redirect and in turn we are able to get the real url of the image. This is a handy feature as it allows us to process remotely hosted images on the fly which gives us the option of using CDNs or clouds for image storage. Next a gd resource is created and stored internally.

The object exposes 3 properties (width, height, and image). The first two are obvious while the image property is a reference to the gd resource should we ever need to deal with it directly. The save method allows the image to be saved to a file in the format specified by the extension of the destination path. The stream function is useful for streaming the raw image data to a web browser when you need to link to a dynamically generated image. The object destructor frees the gd resource from memory.

So at first glance this class isn’t terribly useful aside from the fact that it handles the image format automatically. It’s true utility comes by extending it to encapsulate additional functionality. We can use this class as a rich base class that provides the mundane common functionality that all of the subclasses need. The simplest example would be probably the most common use of gd on the web: the generation of thumbnails

Generate Thumbnails

Here all we overload is the constructor. This class has the added bonus of being able to accept other objects that extend the FP_Image class as well as raw gd resources. The constructor takes this agnostic image as well as a width and height desired for the thumbnail. The class does all of the processing it needs and then stores the created thumbnail internally which we can then access using the methods provided by FP_Image.

Here is a quick example of how to generate dynamic thumbnails from a Zend Framework controller action using this class:

Scale Images

This class isn’t all that different, instead of scaling down both dimensions it scales either vertically or horizontally while preserving the aspect ratio.

Crop Images

This class takes another image and crops it to the specifications passed into the constructor.

Watermark an Image

This is a handy class for embedding a watermark into an image. This takes a base image and a secondary image and overlays it with alpha blending allowing for subtle semi-transparent watermarks.

Overlay True Type Text over Image

This one is fairly sophisticated compared to the others. In a nutshell it allows multiple lines of true type text to be overlayed ontop of an image. It takes a wide array of configuration option to specify things like font color, padding, justification, angle, etc. This class probably deserves a post all in itself so trust me when I say it excels in utility.

Because all of these classes all extend the same base class they can be used in elaborate combinations by overlaying text over a watermarked image that is then in turn scaled down. Also in this structure, these classes are completely generalized and are portable to any application that needs image processing.

Domain Model Programming With the Zend Framework

Each application I write tends to be an evolutionary successor to the previous and I suspect this is the case for most developers. With long term projects one tends to find things that work better than others, and methods that end up being a real pain in the ass and not as scalable as hoped once the code line count breaks a couple thousand or so. When I first got hired on at eROI I’ll admit my php was a bit rusty. I was fairly comfortable with it as I had developed a grab bag of small sites using procedural php and mysql, and I had a good understanding of the language as a language junky. It was fortunate that prior to working at eROI that I had delved head first into the world of Ruby on Rails and various python frameworks all of which allowed me to bask in the goodness that is MVC (Model-View-Controller architecture). As a result when I came on board with the charter of deploying large scale applications in php, my first goal was to figure out how to make php less painful and how to deploy the design patterns I had grown accustomed to.

The Zend Framework was the perfect toolkit for these ends as it provided all the abstracted functionality I could want. The first site I built using the framework was pretty cool but I’ll be the first to admit I’d sooner have a foot amputated than have someone look at the code. While I had experience with MVC, I was still pretty green and my controllers were embarrassingly bloated with logic and manual manipulation of model objects. Controllers had an unmaintainable knowledge of model objects and even minor edits proved to be disastrous as a fix in one block of code would break another somewhere else. Learning is fun. Fortunately, that website never saw the light of day. When the next major project landed on my desk, I was chomping at the bit to apply all of the lessons I had learned from the previous abortion of code. Like a good little programmer I took the logic out of the controllers and pushed it into the models resulting in a much more maintainable codebase. That website did get deployed and has been extended multiple times without much ado and has proved to be a delight to work with.

The following few projects, naturally, were built on evolutions of that same codebase, each one more abstracted and generalized than the one before. I’m a big fan of reusable code and have this vision of doubling my productivity every six months or so by applying the right technologies and re-purposing black box code whenever possible. I can’t say for certain if I’ve stayed true to the road map, but I have noticed that the projects get larger and more complex but development time is remaining the same so I must be doing something right. (I know I’m rambling on but bare with me, I’ll get to the topic in a moment). The last project I did was enormous. I started to see my coding methods strain under the pressure of the demands of the application and maintainability started to slip a bit. It was time for a major evolution.

Enter: Domain Model Programming. I’m a total newb to this design pattern so I won’t comment much on it and instead refer you to wikipedia’s description. In a nutshell the idea is to separate out the true business logic from the persistance layer implementation. I first encountered the concept here on the blog of a huge Zend Framework contributor, during a search for some annoying abstraction problem I was having and when I read Matthew’s article a light bulb went on. Introducing this method to my coding has had the effect of allowing me to break the sound barrier and accomplish the true abstraction that I have needed for real re-usable objects. So now I am going to introduce how I have implemented it using the Zend Framework.

So recently I decided to try out the Doctrine ORM library in place of the included Zend_Db module and in short I haven’t looked back. This made for a perfect opportunity to show how the database implementation can be made to be completely interchangable without having to recode the models or change any of the application specific logic. The point is the models, controllers and views have no concept of the persistance layer so it should be a breeze to swap out Zend_Db for Doctrine, and should that approach go south, it’s no effort to switch back, or replace both with something else entirely.

So first things first. Let me introduce everyone to a series of base classes that can be re-used in any project. These classes provide the base functionality that this design pattern needs leaving the models themselves free to only concern themselves with the application itself.

This is the class that all models extend. It’s purpose is to provide general CRUD functionality. The idea is that a model represents an object that has attributes and an interface to save itself. With that in mind, the base class manages an attribute array and an object that we refer to as a gateway. The gateway is the object that talks to the persistence layer so it acts as a broker for the model whenever the model needs to be saved or needs additional data from outside of itself.