README

Dependency injection.

Build status

Installation

stubbles/ioc is distributed as Composer package. To install it as a dependency of your package use the following command:

composer require "stubbles/ioc": "^12.0"

Requirements

stubbles/ioc requires at least PHP 8.3.

Inversion of Control

stubbles/ioc 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/ioc is modeled after Google Guice and makes use of type hinting annotations. 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/reflect.

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 {
    public function __construct(private Engine $engine, private Tire $tire, private Person $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, $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/ioc 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.

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

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

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

stubbles/ioc 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/ioc 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/ioc will never inject any dependencies via setter methods.

Further features

• Optional injection
• Implicit bindings
• Default implementations
• Inject instances
• Singletons
• Named parameters
• Constant values
• List bindings
• Map bindings
• Closure bindings
• Injection providers
• Create the whole application
• Application properties
• Runtime environment