Controller plug-ins are an extension of Zend_Controller_Plugin_Abstract. They allow you to modify the request (or perform any other action) during any point in the Zend Framework request life-cycle. For more information about controller plug-ins themselves, visit the Zend Framework manual.

Lets start out with the controller plugin itself. The first thing we need to know is what point(s) of the request process lifecycle we should be operating on. In our case, we need to know what controller and action the end user is requesting, so all routing must have occurred. I chose to use preDispatch() because it ensures that an optimal amount of plugins have had their opportunity to make changes to the request, and gives us the highest chance of checking access to the final destination. We can also catch any forwards from our action controller by performing the check here.

<?php
/**
 * A front controller plugin to check the current user against an access control list.
 *
 * @author A.J. Brown
 * @category Examples
 * @package Application_Controller
 * @subpackage Plugin
 * @version $Id$
 *
 */
class Application_Controller_Plugin_CheckHasAccess
    extends Zend_Controller_Plugin_Abstract
{

    public function preDispatch( Zend_Controller_Request_Abstract $request )
    {
        $isLoggedIn = Zend_Auth::getInstance()->hasIdentity();

        // Save some cycles if we're already logged in
        if( $isLoggedIn ) {
             return;
        }

 	$config     = $this->_getConfig();
        $action     = $request->getParam( 'action' );
        $controller = $request->getParam( 'controller' );

        // Make sure we don't end up in a loop
        if( $controller == $config->loginController
            && $action == $config->loginAction )
        {
            return;
        }

        $secure = $this->_checkIsSecure(
			$request->getParam( 'action' )
			, $request->getParam( 'controller' )
		);

        if( $secure ) {
            $request->setParam( 'ref', $request->getPathInfo() );
            $request->setControllerName( $config->loginController );
            $request->setActionName( $config->loginController );
            $request->setDispatched( false );
        }
    }

    /**
     * Load the configuration.
     *
     * @return Zend_Config_Ini
     */
    protected function _getConfig()
    {
        static $config = null;
        if( null === $config ) {
            $config = new Zend_Config_Ini(
                APPLICATION_PATH . '/configs/access.ini' , 'global' );
        }
        return $config;
    }

    protected function _checkIsSecure( $action, $controller, $module = 'default' )
    {
        $config = $this->_getConfig();

        // If no match is found, what should be the default?
        $public = ( isset( $config->defaultAccess ) && $config->defaultAccess == 'public' );

        // Check the action level, then controller
        if( isset( $config->controllers->$controller->actions->$action->access ) ) {
            $public = ( $config->controllers->$controller->actions->$action->access == 'public' );
        } elseif( isset( $config->controllers->$controller->access ) ) {
            $public = ( $config->controllers->$controller->access == 'public' );
        }

        return !$public;
    }
}

As you can see, the plug-in makes use of an ini configuration file to determine if a given controller and action is public or not. If a setting for the action doesn't exist, we fall back to the controller's setting. If the controller doesn't have a setting, we use whatever the default is.

Lets take a look at the configuration file.

[global]

defaultAccess = "private"
loginController = "index"
loginAction = "login"

controllers.index.acccess = "public"
controllers.index.actions.profile.access = "private"

controllers.account.access = "private"
controllers.account.actions.confirm = "public"

In this configuration, all routes will be private unless they're specifically made private. All of our actions within the "index" controller will be public, except for the "profile" action. For the "account" controller, only the "confirm" action will be public.

The last step is making sure our plugin is registered with the front controller. If we forget this part, our plug-in will never have a chance to intercept the request. Registering can be done anywhere you want and at any point during the request process. In fact, your plug-ins can even register other plug-ins. The easiest and most common way is by adding an entry in our application.ini file for the FrontController resource.

resources.frontController.controllerDirectory = APPLICATION_PATH "/controllers"
resources.frontController.params.displayExceptions = 0
resources.frontController.plugins.CheckHasAcess = "Application_Controller_Plugin_CheckHasAccess"

Conclusion

The nice part about designing an access control system using Zend Framework's controller plug-in system is that our code is separated from our controller code. Using this system, a developer doesn't necessarily have to concern himself with modifying the system. Any new controllers that are added will automatically use the system without any additional code, and permissions can be changed quickly simply by modifying a configuration file.

Happy Coding!

After pulling my head out, I found the issue in the dispatcher. Around line 359 or so (I hacked up my dispatcher with additional comments while debugging) in cake/Dispatcher.php, you will find the following:

$output = call_user_func_array(array(&$controller, $params['action']), empty($params['pass'])? null: $params['pass']);

The problem is, call_user_func_array requires the 2nd parameter to be an array. As you can see, cake is passing 'null' if we have no additional parameters to pass to the controller action. To fix, just change 'null' to 'array()':

$output = call_user_func_array(array(&$controller, $params['action']), empty($params['pass'])? array(): $params['pass']);

Now everything should be working again.

Note that this particular application is using a very early version of Cake 1.2. This problem might be fixed in later versions.

For me, learning the areas that I've yet to master has been a huge motivation to keep pushing the envelope of my own knowledge. I consider myself a very capable developer, and I don't feel that my co-workers, clients, or associates would say otherwise. At the same time, I know I still have a lot to learn. In fact, anyone that says they're a master of every craft of web and software development probably hasn't learned enough to know what there is to know. This blog itself is a consequence of my desire to explore more technologies and techniques.

The best gift I've been given recently is a true evaluation of my level of mastery. This particular evaluation came interview-style from a Zend developer and client support specialist (meaning their salary is paid by Zend Technologies). Before I entered the conversation, I knew it would be highly technical. After all, you're talking about the PHP company. I've been writing code in PHP for 7 years, am Zend Certified, ranked #3 on oDesk for the Advanced PHP Expert Rating test, placed top 10% in many other assessment tests on other freelance sites, yadda yadda yadda. While none of this equates to guru, it does equate to experience and track record with the language. Thus, I expected to be stumped occasionally, but stride through most of it as usual.

As you can imagine, that wasn't the case.

Overall, I did OK with the evaluation. The questions that I was truly stumped on were things that only the best of the best would know off-hand (and even my evaluator admitted to not knowing the answer until he started working at Zend). Then, of course, there were the middle-ground questions that I knew most of the answer to, but there was a small edge-case that I didn't think of, or that took me a bit of thinking to come up with. But what surprised me the most were the questions that I did know (or should have known) off hand because I encounter them every day, but have been numb to the rhyme-or-reason of them. I won't even mention getting a question wrong that I obviously knew the answer to, but was to worried about it being a trick question to think it all the way through.

I won't get into specifics of the questions that were asked, as I don't want to provide a cheat sheet for the next person. But, the point is this -- being able to academically and fluently explain something on the spot is the true test of how in-depth your knowledge is on a subject. Don't settle for just being able to do it well, but understand why you're doing it, how you did it, and what's the best way to do it. The Pragmatic Programmers would call this programming by confidence, not coincidence.

Thanks for making me study harder, Zend

1. Preparing Your Application
2. A Basic Example
3. Running Your Tests
4. Extending the Testing Functionality
   1. Disposable Testing Models
   2. Authentication Support
   3. Putting It All Together
5. Writing Our Controller Test
6. Conclusion

Automated testing for your web applications is an important step in having the confidence to make changes to your application, and still be confident you're delivering a quality, regression-free product. With Zend Framework's testing framework (built with PHPUnit), you can build a thorough suite of test cases for your web application with very little hassle.

Part 1 will give you all of the basic information you need to start writing automated tests for your Zend Framework applications. In Part 2, I'll provide more real-world example covering some other ways to write tests.

Lets get right to it.

For the examples below, I will be using an actual controller from one of my projects. This controller handles account activies, such as logins, logouts, registrations, and confirmations. We'll be using a test database with a schema that clones our production database, and Doctrine to manage ORM (Sorry Zend_Db ). I'll assume that you're using the prescribed Zend Framework (1.6+) project layout, and that you're somewhat familiar with Zend_Config and using an Initializer controller plugin (created by default if you're using Zend Studio for Eclipse 6.1).

Preparing Your Application

The first step to setting up automated testing is to prepare your application's environment and settings appropriately. Depending no your setup, this can involve setting global variables, changing database connections, or reconfiguring paths. Fortunately for us, this capability is easy using Zend_Config and an Initializer controller plugin.

Zend_Config allows you to specify "sections", which can inherit from another section. This allows you to modify configuration for different environments without duplicating settings across different files (and thereby helping us ensure we don't forget to set something!). In our example project, we'll need only to modify our database connection string, so we're using the test database.

< ?xml version="1.0" encoding="UTF-8"?>
<config>

<production>
  <db>
	<dsn>mysql://dbowner:password@localhost/maindb</dsn>
	<attributes>
		<model_loading>conservative</model_loading>
	</attributes>
  </db>
</production>
<test extends="production">
  <db>
	<dsn>mysql://dbowner:password@localhost/maindb_test</dsn>
  </db>
</test>
</config>

^{Notice how we can even inherit child attributes: Even though we specified a a node, we didn't have to specify everything below the node}

Now that we have our configurations in order, we need something to manage this configuration for us, and switch off based on the environment we're running in. That's the role of our Initializer plugin, which accepts the environment to initialize as a constructor parameter. Showing the source of an Initializer is outside the scope of this article, but here's a pastie for the curious.

A Basic Example

Lets start with the basic framework of a controller test. If you're using Zend Studio for Eclipse, you can easily create this structure by right-clicking on your controller in PHP Explorer and selectingNew > Zend Framework Item, and then selectingZend Controller Test Case. Then, simply make sure the controller you want to test is chosen, and click finish.

require_once 'Zend/Test/PHPUnit/ControllerTestCase.php';
require_once 'application/Initializer.php';
require_once 'application/default/controllers/IndexController.php';

class AccountControllerTest extends Zend_Test_PHPUnit_ControllerTestCase {

	/**
	 * Prepares the environment before running a test.
	 */
	protected function setUp() {
		$this->bootstrap = array ($this, 'appBootstrap' );
		parent::setUp ();
		// TODO Auto-generated FooControllerTest::setUp()
	}

	/**
	 * Prepares the environment before running a test.
	 */
	public function appBootstrap() {
		$this->frontController->registerPlugin ( new Initializer( 'test' ) );
	}

	/**
	 * Cleans up the environment after running a test.
	 */
	protected function tearDown() {
		// TODO Auto-generated FooControllerTest::tearDown()
		parent::tearDown ();
	}

	/**
	 * Constructs the test case.
	 */
	public function __construct() {
		// TODO Auto-generated constructor
	}

	/**
	 * Tests FooController->barAction()
	 */
	public function testIndexAction() {
		// TODO Auto-generated FooControllerTest->testBarAction()
		$this->dispatch ( '/index/index' );
		$this->assertController ( 'index' );
		$this->assertAction ( 'index' );
	}
}

You'll see on line 20 where we're using our initializer to setup the test environment before we run the tests. Before each test metod is run, PHPUnit will call oursetup() method, which has been programmed to call our appBootstrap method. This ensures us that we're using a clean configuration and environment before each test, as if each test was a separate process. When each test case is done, thetearDown() method is called.tearDown() is the place to put any code for removing resources or resetting any persistable changes that tests might make. We'll make use of this in our advanced examples later.

Line 41 contains a bare-bones test case, which will ensure that dispatching to '/index/index' results in the controller named 'index' and an action called 'index' are the last to be executed. This might seem trivial, but it helps detect errors with your controllers. If an uncaught exception is thrown, the controller assertion will fail, since your controller will be the last executed.

Running Your Tests

To keep this article focused, I've decided to remove this section and cover only writing the tests. If you need help creating Test Suites and running tests from the command line, check out PHPUnit Documentation, specifically the sections on the Command Line Test Runner and Organizing Test Suites. If you have any specific questions, feel free to shoot me an email.

Extending the Testing Functionality

Now that we covered the basics, lets get to fully testing our Accounts controllers. There are a couple of "outside the box" requirements we have for testing our accounts controller. First off, we need a way to test the full account creation process, as if a user was actually registering. When we're done with a test, we want to get rid of that data whenever possible, so we can run tests as many times as we want and not worry about growing our test database. Secondly, We need a way to simulate an authenticated user, as well as checking for whether a user has been authenticated or not.

Because these operations are pretty general and an opportunity for reuse exists, Lets put our supporting logic in a parent class and let our test cases inherit them.

Disposable Testing Models

There are two ways to ensure the data you're creating during a test is deleted once a test is complete. Some choose to create the database on the fly using seed data. Since I'm using Doctrine for my projects and working directly with models (no raw queries) in the tests, I decided that just deleting the data was the best approach. To do this, all we need to do is "schedule" our model for deletion after it has been created (or loaded).

protected function _setDisposable( Doctrine_Record $model )
{
    $this->_disposables[] = $model;
}

This function simply takes a reference to a model, and stores it in array, which will be handled by our tearDown() function later:

	protected function tearDown()

	{
	    parent::tearDown();

	    foreach ( $this->_disposables as $model ) {
	        if ( $model instanceof Doctrine_Record ) {
	            $model->delete();
	        }
	        unset( $model );
	    }
	}

We simply loop through all of our "scheduled" models and delete them. This must be done in tearDown() and not inside of any test method because it's the only way to ensure it happens. Once an assertion fails or an unexpected exception occurs in a test, that method stops executing. IF we were to try to dispose our models after an assertion, it may never happen¹. Similarly, we obviously can't dispose of a model before an assertion if that model is needed for the assertion (and why would it exist if you didn't need it?).

Authentication Support

There are 3 things we must be able to do in order to fully test authentication.

• Create a fake identity
• Set our environment to a state equivalent to a user being logged in.
• Assert whether the environment has been changed to a logged in state.

Our example controller uses a database adapter for authentication and identity retrieval², so generating a fake identity for us means creating (or loading) a record in our accounts table, and returning the identity data we would normally get.

/**
 * Generates a fake identity, usefull for simulating a logged in user
 *
 * @return StdClass an identity
 */
protected function _generateFakeIdentity()
{
	$identity = new stdClass();

        $account = new Account();
        $account->username     = 'AutoTest' . time();
        $account->emailAddress = 'autotest@example.org';
        $account->password     = md5( 'password' );
        $account->confirmed    = true;
        $account->enabled      = true;
        $account->save();
        $this->_setDisposable( $account );

	foreach( $account->toArray() as $key => $val ) {
	        $identity->$key = $val;
	}
	unset( $identity->password );

	return $identity;
}

Account is our model, aDoctrine_Record type. We're just simply creating a random account, and returning it's data as our idenity. Notice that we're also scheduling this model for disposal (as we covered above.) Now, we just need a way to set our environment to the "logged in state" as this fake user.

/**
 * Sets the current state as if there is a logged in user
 *
 * @param object $identity the idenity to use, otherwise one is generated
 * @return void
 */
protected  function _doLogin( $identity = null )
{
    if ( $identity === null ) {
        $identity = $this->_generateFakeIdentity();
    }
    Zend_Auth::getInstance()->getStorage()->write( $identity );
}

In our example application, if Zend_Auth has an identity, a user must be logged in. Therefore, all we have to do is store an identity in Zend_Auth's storage adapter, and call ourselves logged in. That makes asserting login as simple as checking for an identity.

public function assertNotLoggedIn()
{
    $this->assertFalse( Zend_Auth::getInstance()->hasIdentity(), 'Login assertion failed' );
}

public function assertLoggedIn()
{
    $this->assertTrue( Zend_Auth::getInstance()->hasIdentity(), 'Login assertion failed' );
}

These simple assertions ³ ensure that we're logged in (or not logged in)

Putting It All Together

Putting it all together, we now have a base class which provides all of our test cases with the functionality we need.

< ?php

require_once 'Zend/Test/PHPUnit/ControllerTestCase.php';

class BaseControllerTest extends Zend_Test_PHPUnit_ControllerTestCase
{

    /**
     * Contains models which should be destroyed on tear down
     *
     * @var array
     */
    protected $_disposables = array();

	protected function tearDown()
	{
	    parent::tearDown();

	    foreach ( $this->_disposables as $model ) {
	        if ( $model instanceof Doctrine_Record ) {
	            $model->delete();
	        }
	        unset( $model );
	    }
	}

	/**
	 * Sets a model as disposable, so teardown automatically deletes it
	 *
	 * @param Doctrine_record $model
	 */
	protected function _setDisposable( Doctrine_record $model )
	{
	    $this->_disposables[] = $model;
	}

	/**
	 * Sets the current state as if there is a logged in user
	 *
	 * @param object $identity the idenity to use, otherwise one is generated
	 * @return void
	 */
	protected function _doLogin( $identity = null )
	{
	    if ( $identity === null ) {
	        $identity = $this->_generateFakeIdentity();
	    }

	    Zend_Auth::getInstance()->getStorage()->write( $identity );
	}

	/**
	 * Generates a fake identity, usefull for simulating a logged in user
	 *
	 * @param boolean $unique
	 * @return StdClass an identity
	 */
	protected function _generateFakeIdentity( $unique = false )
	{
		$identity = new stdClass();

		$account = new Account();
	        $account->username     = 'AutoTest' . time();
	        $account->emailAddress = 'autotest' . time() . '@example.org';
	        $account->password     = md5( 'password' );
	        $account->confirmed    = true;
	        $account->enabled      = true;
	        $account->save();
	        $this->_setDisposable( $account );

	    	foreach( $account->toArray() as $key => $val ) {
	        	$identity->$key = $val;
	    	}
	    	unset( $identity->password );

	    	return $identity;
	}

	public function assertNotLoggedIn()
	{
	    $this->assertFalse( Zend_Auth::getInstance()->hasIdentity(), 'Login assertion failed' );
	}

	public function assertLoggedIn()
	{
	    $this->assertTrue( Zend_Auth::getInstance()->hasIdentity(), 'Login assertion failed' );
	}

}

Writing Our Controller Test

Now that our groundwork has been laid, we can finally start writing our controller test.

Our first set of test cases cover the requirement"when a user registers, they must confirm their email address before they can access their account". To do this, we need to simulate a user posting their valid registration details to our controller, and verify that the account created is not set as confirmed. We then need to test that submitting login information for a non-confirmed account to our login action does not result in an authenticated user.

public function testRegisterCreatesNewUnconfirmedAccount()
{
    $email = 'autotest' . time() . '@example.org';
    $data = array(
        'emailAddress'    => $email,
        'password'		  => 'testpassw0rd',
        'passwordconfirm' => 'testpassw0rd'
    );

    $_POST = $data;

    $this->dispatch( '/account/register' );
    //try to find the account record
    $table = Doctrine_Table::create( 'Account' ) ;
    $account = $table->findOneByEmailAddress( $email );
    $this->_setDisposable( $account );
    $this->assertNotNull( $account );
    $this->assertFalse( $account->confirmed, 'Account was not marked as unconfirmed' );
}

/**
 * Asserts that a user that hasn't been confirmed cannot login
 *
 */
public function testUnconfirmedUserCannotLogin()
{
    $email = 'autotest' . time() . '@example.org';

    $account = new Account();
    $account->username     = $email;
    $account->password     = md5( 'password' );
    $account->emailAddress = $email;
    $account->confirmed    = false;
    $account->enabled      = true;
    $account->save();

    $this->_setDisposable( $account );

    $_POST['username'] = $email;
    $_POST['password'] = 'password';

    $this->dispatch( '/account/login' );
    $this->assertFalse( Zend_Auth::getInstance()->hasIdentity() );
    $this->assertNotRedirect();
}

Our first test simply uses the $_POST global variable to simulate submitting our registration form with some test data. After dispatch(), we use Doctrine_Table to find the model created by AccountController::registerAction(), then assert that the record was found and that it was not marked as confirmed.

The second test works by manually inserting a record that's not confirmed, and making sure no user is authorized when attempting to login with that user's account information. As an added bonus, we also useassertNotRedirect() to make sure our controller didn't redirect. Our controller should only redirect if login was successful, otherwise it would be confusing to a user.

Conclusion

Automated testing of your controllers is relatively simple using the combined power of PHPUnit and Zend Framework's Zend_Test component. We can add additional functionality to allow our tests to simulate authentication, create fake identities, and even clean up our database after our tests have run. I showed you how you can put this all together to test a registration and confirmation process in your controllers.

In part 2, I'll cover more areas of testing in our AccountsController, including testing our actions that require an authorized user in order to access them.

In PHP, an auto loader is a set of code that's responsible for "loading" a class that is needed for some piece of code (if it has not already been loaded). Typically it uses some formula or pre-determined list to figure out what file needs to be included in order for the class to be defined. In most applications the filename is determined by examining the class name.

Why Auto Load instead of using includes?

Although adding some overhead to your application, using an autoloader instead of directly requiring files will increase the flexibility of your application. With an autoloader, you can move files around in your project as you please, without breaking dependent code. It's also much more convenient for the developer, who no longer needs to know the exact location (or version) of a needed file.

Using an autoloader instead of directly requiring files will help keep your code decoupled. This is especially useful for writing unit-testable code by allowing you to mock dependent objects, and prevent unnecessary code from being run.

Our Class File Mapping Package

The class file map factory is responsible for scanning the files of a specified directory, indexing the classes and interfaces contained within those files, and generating a ClassFileMap object to represent the index. Each ClassFileMap is then used by a ClassFileMapAutloader to lookup the needed class.

To load the files we want to index, we're using SPL'sRecursiveDirectoryIterator andRecursiveIteratorIterator. Explaining those classes is outside the scope of this article.

The auto loader I wrote uses thetokenizer'stoken_get_all, which returns an array of tokens within a given source string. Tokens describe the relevance of a sequence of characters in PHP source, such as `whitespace`, `class`, `function`, `bracket`, etc. Once our file has been tokenized, we just look for all `class` and `interface` tokens, and look at the next non-whitespace token to select the class name.

Class File Map Factory

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

/**
 * Class to handle generating the class file map, and loading of classes
 *
 * @author A.J. Brown
 * @package com.hypermuttlabs
 * @subpackage packaging
 */
abstract class ClassFileMapFactory
{
 
 /**
  * Generates a class file map instance for the specified class path
  *
  * @param string $sClassPath the path to analyze
  * @param string $sName      the name for this class file map
  * @return ClassFileMap
  */
 public static function generate( $sClassPath, $sName = null )
 {
  $aClassMap = self::_getClassFileMapArray( $sClassPath, true );
  $oClassfileMap =  new ClassFileMap( $sName );
  $oClassfileMap->setClassPath( $aClassMap );
  return $oClassfileMap;
 }
 
 /**
  * Generates a class file map for the specified directory
  *
  * @return array
  */
 private static function _getClassFileMapArray( $sDirectory, $bRecursive = true )
 {
 
  if ( !is_dir( $sDirectory ) )
  {
   throw new AppException(
    'The specified location is not a directory' );
  }
 
  if ( !is_readable( $sDirectory ) )
  {
   throw new AppException(
    'The path `' . $sDirectory . '` is not readable' );
  }
 
  $sPath = realpath( $sDirectory );
 
  $oFiles = new RecursiveIteratorIterator(
   new RecursiveDirectoryIterator( $sPath ),
   $bRecursive ? RecursiveIteratorIterator::SELF_FIRST : null
  );
 
  $sHiddenFiles = '/\/\.\w+/';
 
  //------------------------------------------
  // Load the list of files in the directory
  //------------------------------------------
  foreach( $oFiles as $sName => $aFile )
  {
   if( !preg_match( $sHiddenFiles, $sName ) && !$aFile->isDir() )
   {
    $oFile = $aFile->openFile();
 
    $sContents = null;
    while( !$oFile->eof() )
    {
     $sContents .= $oFile->fgets();
    }
 
    //----------------------------------------
    // Tokenize the source and grab the classes
    // and interfaces
    //----------------------------------------
    $aTokens = token_get_all( $sContents );
    $iNumtokens = count( $aTokens );
    for( $i = 0; $i < $iNumtokens; $i++ )
    {
 
     switch( $aTokens[ $i ][ 0 ]  )
     {
      case T_CLASS:
      case T_INTERFACE:
       $i += 2; //skip the whitespace token
       $aDeclarations[ $aTokens[ $i ][ 1 ] ] = $sName;
       break;
     }
    }
   }
  }
 
  return $aDeclarations;
 }
}

You'll notice we're using a regex to check the directory name of our files before processing them. This prevents hidden folders (such as .svn) from being processed, which will both reduce overhead, and prevent diff and history files from being scanned.

Class File Map Autoloader

The ClassFileMapAutoloader is used by PHP to locate classes which have not yet been defined. It must be added to the autoload stack usingspl_autoload_register by calling it's registerAutload() method. Once registered, it will use all attached ClassFileMaps to lookup class names and require their files.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

/**
 * Autoloads classes using class file maps
 *
 * @author A.J. Brown
 * @package com.hypermuttlabs
 * @subpackage packaging
 *
 */
class ClassFileMapAutoloader
{
 private $_aClassFileMaps = array();
 
 /**
  * Adds a class file map for use by this autoloader.  ClassFileMaps are grouped
  * by their name if the second parameter is true, resulting in a second
  * class file with the same name overwriting the first.
  *
  * @param ClassFileMap $oClassFileMap
  * @param bool $bUseName use the value of {@link ClassFileMap::getName()}
  *  as the key
  *
  * @return void
  */
 public function addClassFileMap( ClassFileMap $oClassFileMap, $bUseName = true )
 {
  if( $bUseName )
  {
   $this->_aClassFileMaps[ $oClassFileMap->getName() ] = $oClassFileMap;
  }
  else
  {
   $this->_aClassFileMaps[] = $oClassFileMap;
  }
 }
 
 /**
  * Registers this class with the spl autloader stack.
  *
  * @return bool
  */
 public function registerAutoload()
 {
  return spl_autoload_register( array( &$this, 'autoload' ) );
 }
 
 /**
  * Autloads classes, if they can be found in the class file maps associated
  * with this autoloader.
  *
  * @param string $sClass
  * @return string the class name if found, otherwise false
  */
 public function autoload( $sClass )
 {
  if( class_exists( $sClass, false ) || interface_exists( $sClass ) )
  {
   return false;
  }
 
  $sPath = $this->_doLookup( $sClass );
  if ( $sPath !== null )
  {
   require_once $sPath;
  }
 
  return true;
 }
 
 /**
  * Loop through class files maps untill a match is found
  *
  * @param string $sClassName
  * @return string the path of the class, or null if not found
  */
 private function _doLookup( $sClassName )
 {
  foreach( $this->_aClassFileMaps as $oClassFileMap )
  {
   $sPath = $oClassFileMap->lookup( $sClassName );
   if ( !is_null( $sPath ) )
   return $sPath;
  }
 
  return null;
 }
}

Class File Map

The ClassFileMap represents an index of php files of a specific location, allowing the ClassFileMapAutoloader to determine a filename from a class name.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

/**
 * Manages a map of class names to their paths
 *
 * @author A.J. Brown
 * @package com.hypermuttlabs
 * @subpackage packaging
 *
 */
class ClassFileMap
{
 
 /**
  * @var array
  */
 private $_aClassMap;
 
 /**
  * Stores a name for this class file map.  For user usage.
  * @var string
  */
 private $_sName;
 
 /**
  * Stores the timestamp of this class file map's creation.
  * @var int
  */
 private $_iCreated;
 
 /**
  * Constructor
  *
  * @param string $sName an optional name to give this class file map.
  */
 function __construct ( $sName = null )
 {
  $this->_iCreated = time();
  $this->_sName = $sName;
 }
 
 /**
  * Maps the specified class to the specified path. If the first argument
  * is an array, it is expected that the array contains name-value pairs
  * of class names and thier paths.
  *
  * @param string|array  $mClassName the class name to map
  * @param string   $sPath the path to map to
  *
  * @return void
  */
 public function setClassPath( $mClassName, $sPath = null )
 {
  if( is_array( $mClassName ) )
  {
   foreach( $mClassName as $sClassName => $sPath )
   {
    $this->setClassPath( $sClassName, $sPath );
   }
 
   return;
  }
 
  $this->_aClassMap[ $mClassName ] = $sPath;
 }
 
 /**
  * Retreives the name of this class
  *
  * @return string
  */
 public function getName(  )
 {
  return $this->_sName;
 }
 
 /**
  * Determine if a class is mapped
  *
  * @param string $sClassName
  * @return boolean true if the class is mapped
  */
 public function isMapped( $sClassName )
 {
  return !empty( $this->_aClassMap[ $sClassName ] );
 }
 
 /**
  * Returns the path of the file if mapped, otherwise null
  *
  * @param  string  $sClassName the class to lookup
  * @return  string the full path to the file containing the class
  */
 public function lookup( $sClassName )
 {
  if ( !$this->isMapped( $sClassName ) ) return null;
 
  return $this->_aClassMap[ $sClassName ];
 }
 
 /**
  * Returns an array of classes which exist within a given file path
  *
  * @param unknown_type $sFileName
  * @return unknown
  */
 public function getClassesInFile( $sFileName )
 {
  return array_keys( $this->_aClassMap, $sFileName );
 }
 
 /**
  * Retreives the entire class-file map as an array with class names as keys
  * and their paths as values
  *
  */
 public function getClassMap()
 {
                return $this->_aClassMap
 }
}

Usage Example

//build a class file map for our applications classes
$oAppClassFileMap = ClassFileMapFactory::generate('/path/to/class/files');
 
//instanciate a new auto loader
$this->_oAutoLoader = new ClassFileMapAutoloader();
 
//add the class file map to the autoloader
$this->_oAutoLoader->addClassFileMap( $oAppClassFileMap );
 
//register the autoloader
$this->_oAutoLoader->registerAutoload();

And that's all there is to it. Once this code has been executed in your application, no further requires will be needed. We do add a slight overhead to the application, but the increased flexibility and modularity is well worth it, especially for larger applications.

Feel free to use the autoloader in this article in your own projects.

One of the things that makes a useful website useful is openness and usefulness of information. Whenever you provide some sort of interesting or unique information, anyone who wants it is going to get it. If you don't make it easy for them, they'll either go somewhere else or find a way to get it. Imagine if everyone who wanted a stock ticker on their site had to write their own screen scraper? Do I even have to tell you why RSS/Atom feeds are a good thing?

The Problem

My new project will most definitely benefit from open data through a web service. Since I felt this was high on the prioritized features list, I wanted to make sure I had an architecturally sound mechanism to handle all types of requests.

In my case, I wanted almost any page which interacts with data to be accessible in RDF format. Additionally, I wanted it to be easy to add new formats at the view level, without having to do anything to the code (for a true MVC architecture). This means the controller itself should only be concerned with which set of views to push data to, not how to translate the data into any particular format.

My first attempt was rather complicated. I created a router which used one set of routes to strip values from a path, and then a second to do the actual routing. On top of that, the routes had to be confusing in order to get it to work. It wasn't very innovative, but it worked. You can see that attempt here: Zend Framework: Using Transparent Routes.

The Solution: Content Type Filtering

After sleeping on it, I decided to keep it simple. Instead of writing complicated regex routes to do all of the work for me, why not just have a router that knows how to detect the content type specification, and strip it? That's true transparency: don't pass any information to anything that doesn't need it.

To revisit, here are my needs:

• User-specific content type through the URI. Receiving the same data in a different format is as simple as changing the content-type part of the uri.
• The content-type does not have to be specified. In that case, the content type will default to html
• Only content-types I wish to support will be caught through the detection mechanism. For example /foo/bar.html will work, but /foo/bar.bazml will not result in 'bazml' being detected as a content type.
• I do not want to break the default parameterization mechanism

With those requirements in mind, I went to work. The first step is to create a router which is aware of the 'content type' concept. It would allow a user to specify a list of content types which it will attempt to detect, and the regex patterns to use in order to detect this patterns. Once it's done it's job of detecting the content types, it will strip that portion of the URI, and pass it back to the request object.

The Routing Schema

After some deliberation, I decided to change my "route schema". At first, I wanted the content type to be specified using an extension:

/<controller>/<action>.<contentType>

For example, the following calls AuthorsController::browseAction() and displays the results in RDF format:

/authors/browse.rdf/page/1

The problem with this is simply the way the URIs look. I'm not sure of any implications other than it annoying me. So, I went with my original route schema:

/<contentType>/<controller>/<action>

However, pretend I never said anything. For the purposes of this post, we'll be using the first routing schema. That schema points out some extra efforts that are needed to make this work universally, and provides the best demonstration.

The configuration

1
2
3
4
5

<routing>
       <contentTypes>html,xml</contentTypes>
        <contentTypePattern>\w+\.(#)</contentTypePattern>
        <contentTypeReplacePattern>\.(#)</contentTypeReplacePattern>
</routing>

So this will tell our controller that our router than we're only looking for xml and html. We'll use contentTypePattern to detect the pattern, and contentTypeReplacePattern to strip the pattern from the the path before routing.

Whoa, what's up with the #?. Simple, the # characters will be replaced with a list of content types from our configuration. This allows us to abstract the list of content types we want to detect from the pattern used to find them. Here's what the regex will look like after the str_replace is done to insert the content types:

\w+\.(html|rdf|xml)

That makes sense, but why do we need a detection pattern and a stripping pattern? This is exactly why the .extension content type schema makes a better demonstration. Lets say we're trying to determine the content type of a request to `controller/action.xml`. What we want is the 'xml' part. If we write a regex to match the 'xml' part, and use that same pattern to strip it out, we'll end up passing 'controller/action.' as the request path. Obviously, we don't want that stray dot.

Enter the replacement pattern. If we tell our router the entire string that we want to remove, we can also match the dot, and pass 'controller/action' as the request path. This adds much more flexibility to our routes.

The Router

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

class ContentTypeRouter extends Zend_Controller_Router_Rewrite
{
 
 protected $_aContentTypes      = array();
 protected $_aContentTypeRegex    = array();
 protected $_sDefaultContentType   = 'html';
 
 public function addContentType( $sContentType )
 {
  assert( is_string( $sContentType ) );
 
  $sContentType = strtolower( $sContentType );
 
  if ( !in_array( $sContentType, $this->_aContentTypes ) )
  {
   $this->_aContentTypes[] = $sContentType;
  }
 }
 
 public function setDefaultContentType( $sContentType )
 {
  $this->_sContentType = $sContentType;
 }
 
 public function addFilterRegex( $sRegex, $sReplacePattern, array $aMap = array()  )
 {
 
  $this->_aContentTypeRegex[]  = array(
   'regex'  => $sRegex,
   'replace'=> $sReplacePattern,
   'map'    => $aMap );
 }
 
 /**
  * @see Zend_Controller_Router_Rewrite
  *
  * @param Zend_Controller_Request_Abstract $oRequest
  * @return Zend_Controller_Request_Abstract
  */
 public function route( Zend_Controller_Request_Abstract $oRequest )
 {
 
  $sContentType = $this->_sDefaultContentType;
 
  $sContentTypes = join( '|', $this->_aContentTypes );
  $sPath = $this->_getPathInfo( $oRequest );
 
  foreach( $this->_aContentTypeRegex as $aRegex )
  {
   $sRegex = str_replace(
    '#',
    $sContentTypes,
    $aRegex['regex'] );
 
 
   $aMatch = array();
   $sRegex = "/$sRegex/";
 
   //die ($sPath);
 
   if ( 1 === preg_match( $sRegex, $sPath, $aMatch ) )
   {
 
    //grab the content type from the match
    $sContentType = $aMatch[ 1 ];
 
    //---------------------------------------
    //- replace the content type in the route
    //---------------------------------------
 
    $sRegex = str_replace( '#', $sContentTypes, $aRegex['replace'] );
    $sPath = preg_replace( "/$sRegex/", '', $sPath );
 
    break;
   }
  }
 
  $oRequest->setPathInfo( $sPath );
  $oRequest->setParam( 'requestedContentType', $sContentType );
 
  $oRequest = parent::route( $oRequest );
 
  return $oRequest;
 
 }
 
 private function _getPathInfo( Zend_Controller_Request_Abstract $oRequest )
 {
   if (!method_exists($oRequest, 'getVersion') || $oRequest->getVersion() == 1) {
                return $oRequest->getPathInfo();
            } else {
                return $oRequest;
            }
 }
}

One thing you will notice about the route is that you can stack filters. This means we can support more than one routing schema, and the first one to match will be applied. Now, when I decide to switch back to the `<controller>/<action>.<contentType>` schema, I can do so without breaking existing URLs. My users will love me.

Usage Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

$oRouter = new ContentTypeRouter();
 
// load supported content types from config
$aContentTypes = $this->getMainConfiguration()->routing->contentTypes;
$sPattern = $this->getMainConfiguration()->routing->contentTypePattern;
$aContentTypes = split( ',', $aContentTypes );
 
// add our regex filters
$oRouter->addFilterRegex(
 $this->getMainConfiguration()->routing->contentTypePattern,
 $this->getMainConfiguration()->routing->contentTypeReplacePattern );
 
 
// add each supported content type to the router
foreach ( $aContentTypes as $sContentType )
{
 $oRouter->addContentType( $sContentType );
}
 
// make use of the router before dispatch
$oController = Zend_Controller_Front::getInstance();
$oController->setRouter( $oRouter );

Routing with Zend Framework takes on the best of both worlds: It's very simple in it's default form, but tools are provided that allow you to take on as much complexity as you desire. Even if the shipped classes aren't enough for you, you can easily write your own route types, or even your own router.

The Problem

For my current project, I wanted my routes to work like the default routes, with a slight twist. The first part of the URL needed to be a content type to return to the user, and the following string be the controller, action, and parameters. So, for example,

/xml/auth/login
     controller: auth
     action: login
     requestedContentType: xml

/html/auth/login
     controller: auth
     action: login
     requestedContentType: html

This is rather simple using a standard route in zend framework:

$oRouter = $oController->getRouter();
$oRoute = new Zend_Controller_Router_Route(
  ':/requestedContentType/:controller/:action/*
);
$oRouter->addRoute( 'awesomeRoute', $oRoute );
$oController->setRouter( $oRouter );

Perfect. The accomplishes everything we need, and is very simple. But then I had to go and throw a wrench in the works. In addition to having a URI supplied requestedContentType, I wanted to:

• Make sure that only supported content types were parsed in this manner.
• Be able to not specify a content type, and have it default to html.
• Not break Zend Framework's default parameterization behavior.

Example parsed routes:

/xml/content/books
     controller: content
     action: books
     requestedContentType: xml

/html/content/books
     controller: content
     action: books
     requestedContentType: html

/content/books
     controller: content
     action: books
     requestedContentType: html

/rss/content/books/page/1
     controller: content
     action: books
     requestedContentType: rss
     page: 1

/content/books/foo/bar
     controller: content
     action: books
     requestedContentType: html
     foo: bar

By now, you may have guessed it -- A custom is in order. Unfortunately, I messed around with chaining routes of different types for hours before coming to this conclusion. This was mosty out of fear, though.

The Solution

The approach I took was slightly different than the built-in routing flow. As shipped, Zend's routers will loop through the routes you pass to it to it until it finds the first one to match (in the order of which they were supplied). Once the route matches, the parameters extracted through that route are assigned to the request, and control is returned to the dispatcher.

I decided to rework this a little bit to meet my needs. I essentially wanted to pass in a set of filters which could extract parameters from a URI before the actual routing takes place. This would allow me to extract the content type from the URI if it existed, but allow other routes to actually handle the routing itself. I called these routes 'Transparent Routes', since they are applied the same way as Zend's routes, however they do not actually invoke routing.

Here is my flow:

1. Setup Your Routes
2. Assign Transparent Routes
3. Assign Routes
4. When route() is invoked, the transparent routes are applied, which extracts parameters from the URI
5. The standard routing mechanism is triggered. When a route is matched, only parameters which are also extracted from this route will be applied.

This completely solved my immediate issue, and allowed opportunties for much more down the road. Almost any parameter can be generated this way.

The TransparencyRouter Class

/**
 * Extended router which allows applying transparent routes which
 * only serve to extract paramters.  Once transparent routes
 * have been applied, controll is returned to the standard
 * Zend_Controller_Router_Rewrite.
 *
 * @author A.J. Brown
 * @version 1.0
 *
 */
class TransparencyRouter extends Zend_Controller_Router_Rewrite
{
 protected $_transparentRoutes = array();
 
 /**
  * Adds a route which will be used for extracting parameters only.
  *
  * @param string $sName the name for this route
  * @param Zend_Controller_Router_Route_Abstract $oRoute
  * @return TransparencyRouter
  */
 public function addTransparentRoute(
  $sName,
  Zend_Controller_Router_Route_Abstract $oRoute
 )
 {
        if (method_exists($oRoute, 'setRequest')) {
            $oRoute->setRequest($this->getFrontController()->getRequest());
        }
 
        $this->_transparentRoutes[$sName] = $oRoute;
 
        return $this;
 }
 
 /**
  * @see Zend_Controller_Router_Rewrite
  *
  * @param Zend_Controller_Request_Abstract $oRequest
  * @return Zend_Controller_Request_Abstract
  */
 public function route( Zend_Controller_Request_Abstract $oRequest )
 {
 
  foreach (array_reverse($this->_transparentRoutes) as $name => $route) {
 
      if (!method_exists($route, 'getVersion') || $route->getVersion() == 1) {
                $match = $oRequest->getPathInfo();
            } else {
                $match = $request;
            }
 
      if ($params = $route->match( $match ) ) {
                $this->_setRequestParams($oRequest, $params);
                $iMatched++;
            }
  }
 
  return parent::route( $oRequest );
 }
}

Example Usage

//--------------------------
// Configure routes
//--------------------------
 
$oRouter = new TransparencyRouter();
 
$oInterpreterRoute = new Zend_Controller_Router_Route(
 ':controller/:action/*' );
 
$oNonContentTypeRoute = new Zend_Controller_Router_Route_Regex(
 '(\w+)/(\w+)(\/.*)?',
 array(
  'requestedContentType' => 'html'),
 array(
  1 => 'controller',
  2 => 'action' )
);
 
$oContentTypeRoute = new Zend_Controller_Router_Route_Regex(
 // TODO the content types themselves should be
        // pulled in from a config file.
        '(html|xml)\/(\w+)\/(\w+)(\/.*)?',
 array(),
 array(
  1 => 'requestedContentType',
  2 => 'controller',
  3 => 'action' )
);
 
$oRouter->addTransparentRoute( 'nonContentType', $oNonContentTypeRoute  );
$oRouter->addFilteringRoute( 'contentType', $oContentTypeRoute );
$oRouter->addRoute( 'generic', $oInterpreterRoute );
$oRouter->addRoute( 'contentType', $oContentTypeRoute );
 
//-------------------------
// Setup controller
//-------------------------
$oController = Zend_Controller_Front::getInstance();
$oController->setRouter( $oRouter );