Extensions

Extensions is an alternative method of pluggable object creation (ala Chaos Tools plugins).

The key features of Extensions are:

• Extensions are always namespaced objects
• Extensions always extend the base Extension class
• Unlike Chaos Tools, extensions can be declared dynamically, and at run-time
• It is not necessary to load the Extension file to get information about it
• Extensions use factory classes for creation
• Extensions are organised into Collections, which are nominally a set of plugins with similar behaviour, but dont have to be

Basic usage

Extensions are a type of reusable class, so there are two ways you might commonly want to use them. Firstly, in accessing an Extension Collection to use the objects in it, and secondly to declare new extensions (it's not necessary to ever declare a collection, these are created dynamically).

Accessing a collection

// Get a full collection containing fully loaded extensions, as an array.
// This will return only extensions already declared.
$extensions = extensions_get_extensions($collection_name);

// Get only the settings for the collection, without creating objects, as an array.
// Again, this will only return extensions already declared.
$extensions = extensions_get_extensions_list($collection_name)

// Load and return extensions declared inside hook_extensions_declare() as well
// as any others already declared.
// This will also run the extension hook loader.
$extensions = extensions_load_extensions($collection_name)

Loading a single Extension

// Load a single extension
$extension = extensions_get_extension($collection, $extension_name);

Declaring extensions

Extensions must always be declared using extension_register_extension(), however when this happens is up to you. If there isn't a suitable place in your code, you can use he hook method.

The key parts of an extension declaration are:

1. The collection name
2. The extension name
3. A class name (this should be PSR-0 compatible, unless its loaded into scope some other way)

Theoretically, one extension could be registered against multiple collections, however normal usage would confine extensions to just one "type".

/**
 * Generic callback to help loading extension information.
 *
 * There are two ways to declare extensions. The first is to find a logical
 * point in your code to declare the extensions using
 * extensions_register_extension(). The second is to use one of these hooks,
 * then call extensions_parse_extensions() before accessing your extensions.
 *
 * This hook returns nothing, it is expected that you'll merely use it as a
 * wrapper for calling extensions_register_extension().
 */
function hook_extensions_declare() {

  extensions_register_extension('my_extension_collection', 'my_extension_name')
    ->properties(array('an_argument' => array()))
    ->className('\My\Class\Name');
}

/**
 * Generic callback to help loading extension information for a collection.
 *
 * This works the same way as hook_extensions_declare() except it only fires
 * when the COLLECTION_NAME component matches the extension collection
 * requested.
 *
 * It is preferable to use this over hook_extensions_declare, unless you don't
 * know the collection name at the time of calling extensions_parse_extensions().
 */
function hook_extensions_declare_COLLECTION_NAME() {

  extensions_register_extension('my_extension_collection', 'my_extension_name')
    ->properties(array('an_argument' => array()))
    ->className('\My\Class\Name');
}