Introduction

Inversion of Control

Stubbles provides a very simple-to-use but still powerful inversion of control container, which supports constructor and setter based dependency injection. The IoC container of Stubbles is modeled after Google Guice and makes use of type hinting and Stubbles' annotation features. If you've never heard of type hinting or annotations, you should at first read the sections on these two topics:

• Section on 'type hinting' in the PHP manual
• Annotations Section on annotations in the Stubbles Core manual

Note: starting with release 6.0.0 it is not required any more to mark constructors of classes with @Inject.

The example code

Imagine, you are building a car configurator. To follow the rules of good design, you define interfaces for all components of a car and provide several classes that implement these components.

The interfaces in you application include:

interface Car {
    public function moveForward($miles);
}
interface Person {
    public function sayHello();
}
interface Tire {
    public function rotate();
}
interface Engine {
    public function start();
}

The implementations are:

class BMW implements Car {
    protected $driver;
    protected $engine;
    protected $tire;

    public function __construct(Engine $engine, Tire $tire) {
        $this->engine = $engine;
        $this->tire = $tire;
    }
    public function setDriver(Person $driver) {
        $this->driver = $driver;
    }
    public function moveForward($miles) {
        $this->driver->sayHello();
        $this->engine->start();
        $this->tire->rotate();
    }
}

class Schst implements Person {
    public function sayHello() {
        echo "My name is Stephan\n";
    }
}

class Goodyear implements Tire {
    public function rotate() {
        echo "Rotating Goodyear tire\n";
    }
}

class TwoLitresEngine implements Engine {
    public function start() {
        echo "Starting 2l engine\n";
    }
}

Without the dependency injection framework

To create a new instance of an implementation of Car the following code is required:

$tire   = new Goodyear();
$engine = new TwoLitresEngine();
$schst  = new Schst();

$bmw    = new BMW($engine, $tire);
$bmw->setDriver($schst);

$bmw->moveForward(50);

Creating objects manually like this has several drawbacks:

• Your application is bound to the concrete implementations instead of the interfaces
• Changing the implementation means changing existing code, which might break it
• The creation of objects is scattered throughout your application

Of course, real applications have a lot more classes, so things only get worse then.

Enter 'Inversion of Control'

Stubbles tries to solve these problems by providing functionality to handle all dependency injections for you. This keeps your application clean of boilerplate code.

Furthermore, it allows you to centralize and/or modularize the definition of the concrete implementations for your interfaces or abstract types.

A simple example

To define the concrete implementations is done using an instance of stubbles\ioc\Binder:

$binder = new stubbles\ioc\Binder();
$binder->bind('Car')->to('BMW');
$binder->bind('Tire')->to('Goodyear');
$binder->bind('Person')->to('Schst');
$binder->bind('Engine')->to('TwoLitresEngine');

In this short code snippet, you bound the interfaces from the example above to their concrete implementations.

If you now need an instance of the engine, you use the binder to create a stubbles\ioc\Injector, which can be used to create the desired Engine:

$injector = $binder->getInjector();
$engine = $injector->getInstance('Engine');
var_dump($engine);

This code snippet will now display:

object(TwoLitresEngine)#48 (0) {
}

As desired, it created an instance of the concrete implementation, that you bound to the interface.

Adding dependency injection

Next, you probably want to get an instance of Car using the same approach:

$injector = $binder->getInjector();
$car = $injector->getInstance('Car');
var_dump($car);

This will result in the following error:

Catchable fatal error: Argument 1 passed to BMW::__construct() must implement interface Engine, none given in path/to/code.php on line 13

This had to happen, because the constructor of the BMW class requires you to pass an instance of Tire and Engine and Stubbles does not know, that it should do this. But it is very easy to tell Stubbles, that it should inject dependencies into the constructor, by just adding an @Inject annotation. You only need to modify the source code for the class BMW a little bit:

class BMW implements Car {
    protected $driver;
    protected $engine;
    protected $tire;

    /**
     * @Inject
     */
    public function __construct(Engine $engine, Tire $tire) {
        $this->engine = $engine;
        $this->tire = $tire;
    }
    public function setDriver(Person $driver) {
        $this->driver = $driver;
    }
    public function moveForward($miles) {
        $this->driver->sayHello();
        $this->engine->start();
        $this->tire->rotate();
    }
}

After you modified the class, just run the example again and you get the following output:

object(BMW)#33 (3) {
  ["driver:protected"]=>
  NULL
  ["engine:protected"]=>
  object(TwoLitresEngine)#37 (0) {
  }
  ["tire:protected"]=>
  object(Goodyear)#40 (0) {
  }
}

Stubbles created a new instance of BMW, as you bound it to Car, and as the constructor of BMW requires a Tire and an Engine instance, it created these instances as well. To determine the concrete classes to use, Stubbles used the bindings you defined in the stubbles\ioc\Binder instance.

What you also can see is, that Stubbles did not inject an object into the $driver property, although you specified a binding for Person. Stubbles will never inject any dependencies, unless you annotate the constructor or setter method with @Inject. All that you need to do to inject a driver is to annotate the setDriver() method:

class BMW implements Car {
    protected $driver;
    protected $engine;
    protected $tire;

    /**
     * @Inject
     */
    public function __construct(Engine $engine, Tire $tire) {
        $this->engine = $engine;
        $this->tire = $tire;
    }
    /**
     * @Inject
     */
    public function setDriver(Person $driver) {
        $this->driver = $driver;
    }
    public function moveForward($miles) {
        $this->driver->sayHello();
        $this->engine->start();
        $this->tire->rotate();
    }
}

If you re-run this example, all properties will be set according to your bindings.