silverstripe-framework/docs/en/reference/injector.md

# Injector

## Introduction

The `[api:Injector]` class is the central manager of inter-class dependencies
in the SilverStripe Framework. In its simplest form it can be considered as
a replacement for Object::create and singleton() calls, but also offers 
developers the ability to declare the dependencies a class type has, or
to change the nature of the dependencies defined by other developers. 

Some of the goals of dependency injection are

* Simplified instantiation of objects
* Providing a uniform way of declaring and managing inter-object dependencies
* Making class dependencies configurable
* Simplifying the process of overriding or replacing core behaviour
* Improve testability of code
* Promoting abstraction of logic

A key concept of the injector is whether the object should be managed 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.

These concepts will be discussed further below

## Some simple examples

The following sums up the simplest usage of the injector

Assuming no other configuration is specified

	:::php
	$object = Injector::inst()->create('ClassName');

Creates a new object of type ClassName

	:::php
	$object = Injector::inst()->create('ClassName');
	$object2 = Injector::inst()->create('ClassName');
	$object !== $object2;

Repeated calls to create() create a new class each time. To create a singleton
object instead, use **get()**

	:::php
	// sets up ClassName as a singleton
	$object = Injector::inst()->get('ClassName');
	$object2 = Injector::inst()->get('ClassName');
	$object === $object2;

The subsequent call returns the SAME object as the first call.

	:::php 
	class MyController extends Controller {
		// both of these properties will be automatically
		// set by the injector on object creation
		public $permissions;
		public $textProperty;
		
		static $dependencies = array(
			'textProperty'		=> 'a string value',
			'permissions'		=> '%$PermissionService',
		);
	}

	$object = Injector::inst()->get('MyController');
	
	// results in 
	$object->permissions instanceof PermissionService;
	$object->textProperty == 'a string value';

In this case, on creation of the MyController object, the injector will 
automatically instantiate the PermissionService object and set it as
the **permissions** property.

## Configuring objects managed by the dependency injector

The above declarative style of dependency management would cover a large
portion of usecases, but more complex dependency structures can be defined
via configuration files. 

Configuration can be specified for two areas of dependency management

* Defining dependency overrides for individual classes
* Injector managed 'services' 

### Factories

Some services require non-trivial construction which means they must be created by a factory class. To do this, create
a factory class which implements the `[api:SilverStripe\Framework\Injector\Factory]` interface. You can then specify
the `factory` key in the service definition, and the factory service will be used.

An example using the `MyFactory` service to create instances of the `MyService` service is shown below:

	:::yml
	Injector:
	  MyService:
	    factory: MyFactory
	  MyFactory:
	    class: MyFactoryImplementation

	:::php
	class MyFactoryImplementation implements SilverStripe\Framework\Injector\Factory {
		public function create($service, array $params = array()) {
			return new MyServiceImplementation();
		}
	}

	// Will use MyFactoryImplementation::create() to create the service instance.
	$instance = Injector::inst()->get('MyService');

### Dependency overrides

To override the **static $dependency;** declaration for a class, you could 
define the following configuration file (module/_config/MyController.yml)

	name: MyController
	---
	MyController:
	  dependencies:
		textProperty: a string value
		permissions: %$PermissionService

At runtime, the **dependencies** configuration would be read and used in 
place of that declared on the object.

### Managed objects

Simple dependencies can be specified by the **dependencies**, but more complex
configurations are possible by specifying constructor arguments, or by 
specifying more complex properties such as lists.

These more complex configurations are defined in 'Injector' configuration 
blocks and are read by the injector at runtime

Assuming a class structure such as

	:::php
	class RestrictivePermissionService {
		private $database;
		public function setDatabase($d) {	
			$this->database = $d;
		}
	}
	
	class MySQLDatabase {
		private $username;
		private $password;
		
		public function __construct($username, $password) {
			$this->username = $username;
			$this->password = $password;
		}
	}

and the following configuration

	name: MyController
	---
	MyController:
	  dependencies:
		permissions: %$PermissionService
    Injector:
      PermissionService:
        class: RestrictivePermissionService
        properties:
          database: %$MySQLDatabase
      MySQLDatabase
        constructor:
          0: 'dbusername'
          1: 'dbpassword'

calling 

	:::php
	// sets up ClassName as a singleton
	$controller = Injector::inst()->get('MyController');

would 

* Create an object of type MyController
* Look through the **dependencies** and call get('PermissionService')
* Load the configuration for PermissionService, and create an object of 
  type RestrictivePermissionService
* Look at the properties to be injected and look for the config for 
  MySQLDatabase
* Create a MySQLDatabase class, passing dbusername and dbpassword as the 
  parameters to the constructor

### Testing with Injector in a sandbox environment

In situations where injector states must be temporarily overridden, it is possible
to create nested Injector instances which may be later discarded, reverting the
application to the original state.

This is useful when writing test cases, as certain services may be necessary to
override for a single method call.

For instance, a temporary service can be registered and unregistered as below:

	:::php
	// Setup default service
	Injector::inst()->registerService(new LiveService(), 'ServiceName');

	// Test substitute service temporarily
	Injector::nest();
	Injector::inst()->registerService(new TestingService(), 'ServiceName');
	$service = Injector::inst()->get('ServiceName');
	// ... do something with $service
	Injector::unnest();

	// ... future requests for 'ServiceName' will return the LiveService instance


### What are Services?

Without diving too deep down the rabbit hole, the term 'Service' is commonly
used to describe a piece of code that acts as an interface between the 
controller layer and model layer of an MVC architecture. Rather than having
a controller action directly operate on data objects, a service layer provides
that logic abstraction, stopping controllers from implementing business logic, 
and keeping that logic packaged in a way that is easily reused from other
classes. 

By default, objects are managed like a singleton, in that there is only one
object instance used for a named service, and all references to that service
are returned the same object.