Injector

A simple injection manager that manages creating objects and injecting dependencies between them. It borrows quite a lot from ideas taken from Spring's configuration, but is adapted to the stateless PHP way of doing things.

In its simplest form, the dependency injector can be used as a mechanism to instantiate objects. Simply call

Injector::inst()->get('ClassName')

and a new instance of ClassName will be created and returned to you.

Classes can have specific configuration defined for them to indicate dependencies that should be injected. This takes the form of a static variable $dependencies defined in the class (or configuration), which indicates the name of a property that should be set.

eg

class MyController extends Controller {

    public $permissions;
    public $defaultText;

    static $dependencies = array(
        'defaultText'       => 'Override in configuration',
        'permissions'       => '%$PermissionService',
    );
}

will result in an object of type MyController having the defaultText property set to 'Override in configuration', and an object identified as PermissionService set into the property called 'permissions'. The %$ syntax tells the injector to look the provided name up as an item to be created by the Injector itself.

A key concept of the injector is whether to manage the object as

• A pseudo-singleton, in that only one item will be created for a particular identifier (but the same class could be used for multiple identifiers)
• A prototype, where the same configuration is used, but a new object is created each time
• unmanaged, in which case a new object is created and injected, but no information about its state is managed.

Additional configuration of items managed by the injector can be done by providing configuration for the types, either by manually loading in an array describing the configuration, or by specifying the configuration for a type via SilverStripe's configuration mechanism.

Specify a configuration array of the format

array(
    array(
        'id'            => 'BeanId',                    // the name to be used if diff from the filename
        'priority'      => 1,                           // priority. If another bean is defined with the same ID,
                                                        // but has a lower priority, it is NOT overridden
        'class'         => 'ClassName',                 // the name of the PHP class
        'src'           => '/path/to/file'              // the location of the class
        'type'          => 'singleton|prototype'        // if you want prototype object generation, set it as the
                                                        // type
                                                        // By default, singleton is assumed

        'factory' => 'FactoryService'                   // A factory service to use to create instances.
        'construct'     => array(                       // properties to set at construction
            'scalar',
            '%$BeanId',
        )
        'properties'    => array(
            'name' => 'value'                           // scalar value
            'name' => '%$BeanId',                       // a reference to another bean
            'name' => array(
                'scalar',
                '%$BeanId'
            )
        )
    )
    // alternatively
    'MyBean'        => array(
        'class'         => 'ClassName',
    )
    // or simply
    'OtherBean'     => 'SomeClass',
)

In addition to specifying the bindings directly in the configuration, you can simply create a publicly accessible property on the target class which will automatically be injected if the autoScanProperties option is set to true. This means a class defined as

class MyController extends Controller {

    private $permissionService;

    public setPermissionService($p) {
        $this->permissionService = $p;
    }
}

will have setPermissionService called if

• Injector::inst()->setAutoScanProperties(true) is called and
• A service named 'PermissionService' has been configured