Zend\Loader

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.

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.

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.

__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:

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()
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.

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.

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().