The ClassMapAutoloader

Overview

The ClassMapAutoloader is designed with performance in mind. The idea behind it is simple: when asked to load a class, see if it's in the map, and, if so, load the file associated with the class in the map. This avoids unnecessary filesystem operations, and can also ensure the autoloader "plays nice" with opcode caches and PHP's realpath cache.

In order to use the ClassMapAutoloader, you first need class maps. Zend Framework also provides a tool for generating these class maps; you can find it in bin/classmap_generator.php of the distribution. Full documentation of this too is provided in The Class Map Generator utility: bin/classmap_generator.php.

Quick Start

The first step is to generate a class map file. You may run this over any directory containing source code anywhere underneath it.

  1. php classmap_generator.php Some/Directory/

This will create a file named Some/Directory/autoload_classmap.php, which is a PHP file returning an associative array that represents the class map.

Within your code, you will now instantiate the ClassMapAutoloader, and provide it the location of the map.

  1. // This example assumes ZF is on your include_path.
  2. // You could also load the autoloader class from a path relative to the
  3. // current script, or via an absolute path.
  4. require_once 'Zend/Loader/ClassMapAutoloader.php';
  5. $loader = new Zend_Loader_ClassMapAutoloader();
  6.  
  7. // Register the class map:
  8. $loader->registerAutoloadMap('Some/Directory/autoload_classmap.php');
  9.  
  10. // Register with spl_autoload:
  11. $loader->register();

At this point, you may now use any classes referenced in your class map.

Configuration Options

The ClassMapAutoloader defines the following options.

ClassMapAutoloader Options

$options

The ClassMapAutoloader expects an array of options, where each option is either a filename referencing a class map, or an associative array of class name/filename pairs.

As an example:

  1. // Configuration defining both a file-based class map, and an array map
  2. $config = array(
  3.     __DIR__ . '/library/autoload_classmap.php', // file-based class map
  4.     array(                                      // array class map
  5.         'Application_Bootstrap' => __DIR__ . '/application/Bootstrap.php',
  6.         'Test_Bootstrap'        => __DIR__ . '/tests/Bootstrap.php',
  7.     ),
  8. );

Available Methods

Examples

Example #1 Using configuration to seed ClassMapAutoloader

Often, you will want to configure your ClassMapAutoloader. These values may come from a configuration file, a cache (such as ShMem or memcached), or a simple PHP array. The following is an example of a PHP array that could be used to configure the autoloader:

  1. // Configuration defining both a file-based class map, and an array map
  2. $config = array(
  3. APPLICATION_PATH . '/../library/autoload_classmap.php', // file-based class map
  4.     array(                              // array class map
  5.         'Application_Bootstrap' => APPLICATION_PATH . '/Bootstrap.php',
  6.         'Test_Bootstrap'        => APPLICATION_PATH . '/../tests/Bootstrap.php',
  7.     ),
  8. );

An eqivalent INI style configuration might look like this:

  1. classmap.library = APPLICATION_PATH "/../library/autoload_classmap.php"
  2. classmap.resources.Application_Bootstrap = APPLICATION_PATH "/Bootstrap.php"
  3. classmap.resources.Test_Bootstrap = APPLICATION_PATH "/../tests/Bootstrap.php"

Once you have your configuration, you can pass it either to the constructor of the ClassMapAutoloader, to its setOptions() method, or to registerAutoloadMaps().

  1. /* The following are all equivalent */
  2.  
  3. // To the constructor:
  4. $loader = new Zend_Loader_ClassMapAutoloader($config);
  5.  
  6. // To setOptions():
  7. $loader = new Zend_Loader_ClassMapAutoloader();
  8. $loader->setOptions($config);
  9.  
  10. // To registerAutoloadMaps():
  11. $loader = new Zend_Loader_ClassMapAutoloader();
  12. $loader->registerAutoloadMaps($config);
blog comments powered by Disqus