The PluginClassLoader

Overview

Resolving plugin names to class names is a common requirement within Zend Framework applications. The PluginClassLoader implements the interfaces PluginClassLocator, ShortNameLocator, and IteratorAggregate, providing a simple mechanism for aliasing plugin names to classnames for later retrieval.

While it can act as a standalone class, it is intended that developers will extend the class to provide a per-component plugin map. This allows seeding the map with the most often-used plugins, while simultaneously allowing the end-user to overwrite existing or register new plugins.

Additionally, PluginClassLoader provides the ability to statically seed all new instances of a given PluginClassLoader or one of its extensions (via Late Static Binding). If your application will always call for defining or overriding particular plugin maps on given PluginClassLoader extensions, this is a powerful capability.

Quick Start

Typical use cases involve simply instantiating a PluginClassLoader, seeding it with one or more plugin/class name associations, and then using it to retrieve the class name associated with a given plugin name.

use Zend\Http\HeaderLoader;

// Provide a global map, or override defaults:
HeaderLoader::addStaticMap(array(
    'xrequestedfor' => 'My\Http\Header\XRequestedFor',
));

// Instantiate the loader:
$loader = new Zend\Http\HeaderLoader();

// Register a new plugin:
$loader->registerPlugin('xForwardedFor', 'My\Http\Header\XForwardedFor');

// Load/retrieve the associated plugin class:
$class = $loader->load('xrequestedfor'); // 'My\Http\Header\XRequestedFor'

Note

Case Sensitivity

The PluginClassLoader is designed to do case-insensitive plugin name lookups. While the above example defines a “xForwardedFor” plugin name, internally, this will be stored as simply “xforwardedfor”. If another plugin is registered with simply a different word case, it will overwrite this entry.

Configuration Options

PluginClassLoader Options

$map

The constructor may take a single option, an array or Traversable object of key/value pairs corresponding to a plugin name and class name, respectively.

Available Methods

__construct

Instantiate and initialize the loader __construct($map = null)

__construct() The constructor is used to instantiate and initialize the plugin class loader. If passed a string, an array, or a Traversable object, it will pass this to the registerPlugins() method in order to seed (or overwrite) the plugin class map.

addStaticMap

Statically seed the plugin loader map addStaticMap($map)

addStaticMap() Static method for globally pre-seeding the loader with a class map. It accepts either an array or Traversable object of plugin name/class name pairs.

When using this method, be certain you understand the precedence in which maps will be merged; in decreasing order of preference:

• Manually registered plugin/class name pairs (e.g., via registerPlugin() or registerPlugins()).
• A map passed to the constructor .
• The static map.
• The map defined within the class itself.

Also, please note that calling the method will not affect any instances already created.

registerPlugin

Register a plugin/class association registerPlugin($shortName, $className)

registerPlugin() Defined by the PluginClassLocator interface. Expects two string arguments, the plugin $shortName, and the class $className which it represents.

registerPlugins

Register many plugin/class associations at once registerPlugins($map)

registerPlugins() Expects a string, an array or Traversable object of plugin name/class name pairs representing a plugin class map.

If a string argument is provided, registerPlugins() assumes this is a class name. If the class does not exist, an exception will be thrown. If it does, it then instantiates the class and checks to see whether or not it implements Traversable.

unregisterPlugin

Remove a plugin/class association from the map unregisterPlugin($shortName)

unregisterPlugin() Defined by the PluginClassLocator interface; remove a plugin/class association from the plugin class map.

getRegisteredPlugins

Return the complete plugin class map getRegisteredPlugins()

getRegisteredPlugins() Defined by the PluginClassLocator interface; return the entire plugin class map as an array.

isLoaded

Determine if a given plugin name resolves isLoaded($name)

isLoaded() Defined by the ShortNameLocator interface; determine if the given plugin has been resolved to a class name.

getClassName

Return the class name to which a plugin resolves getClassName($name)

getClassName() Defined by the ShortNameLocator interface; return the class name to which a plugin name resolves.

load

Resolve a plugin name load($name)

load() Defined by the ShortNameLocator interface; attempt to resolve a plugin name to a class name. If successful, returns the class name; otherwise, returns a boolean false.

getIterator

Return iterator capable of looping over plugin class map getIterator()

getIterator() Defined by the IteratorAggregate interface; allows iteration over the plugin class map. This can come in useful for using PluginClassLoader instances to other PluginClassLoader instances in order to merge maps.

Examples

Using Static Maps

It’s often convenient to provide global overrides or additions to the maps in a PluginClassLoader instance. This can be done using the addStaticMap() method:

use Zend\Loader\PluginClassLoader;

PluginClassLoader::addStaticMap(array(
    'xrequestedfor' => 'My\Http\Header\XRequestedFor',
));

Any later instances created will now have this map defined, allowing you to load that plugin.

use Zend\Loader\PluginClassLoader;

$loader = new PluginClassLoader();
$class = $loader->load('xrequestedfor'); // My\Http\Header\XRequestedFor

Creating a pre-loaded map

In many cases, you know exactly which plugins you may be drawing upon on a regular basis, and which classes they will refer to. In this case, simply extend the PluginClassLoader and define the map within the extending class.

namespace My\Plugins;

use Zend\Loader\PluginClassLoader;

class PluginLoader extends PluginClassLoader
{
    /**
     * @var array Plugin map
     */
    protected $plugins = array(
        'foo'    => 'My\Plugins\Foo',
        'bar'    => 'My\Plugins\Bar',
        'foobar' => 'My\Plugins\FooBar',
    );
}

At this point, you can simply instantiate the map and use it.

$loader = new My\Plugins\PluginLoader();
$class  = $loader->load('foobar'); // My\Plugins\FooBar

PluginClassLoader makes use of late static binding, allowing per-class static maps. If you want to allow defining a static map specific to this extending class, simply declare a protected static $staticMap property:

namespace My\Plugins;

use Zend\Loader\PluginClassLoader;

class PluginLoader extends PluginClassLoader
{
    protected static $staticMap = array();

    // ...
}

To inject the static map, use the extending class’ name to call the static addStaticMap() method.

PluginLoader::addStaticMap(array(
    'baz'    => 'My\Plugins\Baz',
));

Extending a plugin map using another plugin map

In some cases, a general map class may already exist; as an example, most components in Zend Framework that utilize a plugin broker have an associated PluginClassLoader extension defining the plugins available for that component within the framework. What if you want to define some additions to these? Where should that code go?

One possibility is to define the map in a configuration file, and then inject the configuration into an instance of the plugin loader. This is certainly trivial to implement, but removes the code defining the plugin map from the library.

An alternate solution is to define a new plugin map class. The class name or an instance of the class may then be passed to the constructor or registerPlugins().

namespace My\Plugins;

use Zend\Loader\PluginClassLoader;
use Zend\Http\HeaderLoader;

class PluginLoader extends PluginClassLoader
{
    /**
     * @var array Plugin map
     */
    protected $plugins = array(
        'foo'    => 'My\Plugins\Foo',
        'bar'    => 'My\Plugins\Bar',
        'foobar' => 'My\Plugins\FooBar',
    );
}

// Inject in constructor:
$loader = new HeaderLoader('My\Plugins\PluginLoader');
$loader = new HeaderLoader(new PluginLoader());

// Or via registerPlugins():
$loader->registerPlugins('My\Plugins\PluginLoader');
$loader->registerPlugins(new PluginLoader());