Apps binding modules

Apps

Stubbles IoC provides a way to construct the whole object graph for the application in a simple manner. The stubbles\ioc\App class provides support for this. You can use it by creating an own application class which extends stubbles\ioc\App which drastically reduces bootstrap code required to run an application. The bootstrap code then looks like this:

example\MyApplication::create($pathToProject)
                     ->run();

The example\MyApplication class has to look like this:

namespace example;
use stubbles\ioc\App;
class MyApplication extends App
{
    /**
     * returns a list of binding modules used to wire the object graph
     *
     * @param   string  $projectPath
     * @return  array
     */
    public static function __bindings($projectPath)
    {
        return array(self::createModeBindingModule(),
                     new example\StuffRequiredForApplicationBindingModule(),
                     'example\other\MoreStuffBindingModule'
        );
    }

    protected $controller;

    /**
     * @Inject
     */
    public function __construct(Controller $controller)
    {
        $this->controller = $controller;
    }

    public function run()
    {
        // application running logic here, for instance calling the controller
    }
}

Important point is the __bindings() method only: it has to return a list of binding modules which define all bindings required to run this application. Constructor and run method are only example-wise to show that an instance of this class is created, dependencies are injected and that any further application logic is then triggered via the run() method. Your own application class may look different, important is only that it needs to have the __bindings() method in order to use YourAppClass::create(). The create() method is provided by stubbles\ioc\App which uses late static binding to detect the correct application class to instantiate.

The list returned from __bindings() can contain both full qualified class names of binding module implementations as well as binding module instances.

Binding modules

Binding modules are meant to group bindings which logically belong together. This helps to group your bindings so that you don't need to have them all in the same place. A binding module is a very simple class implementing the stubbles\ioc\module\BindingModule interface:

namespace example;
use stubbles\ioc\module\BindingModule;
class MyApplicationBindingModule implements BindingModule
{
    /**
     * configure the binder
     *
     * @param  Binder  $binder
     */
    public function configure(Binder $binder)
    {
        $binder->bind('example\\SomeInterface')
               ->to('example\\SomeImplementation');

        ... more bindings which might make sense here ...
    }
}

Please note that binding modules itself are not subject to dependency injection. It should not be required in this place. If you need configurable bindings, the binding module implementation may provide methods to set the configuration, and should be called in your __bindings() method:

namespace example;
use stubbles\ioc\App;
class MyApplication extends App
{
    /**
     * returns a list of binding modules used to wire the object graph
     *
     * @return  array
     */
    public static function __bindings($projectPath)
    {
        return array(self::createModeBindingModule(),
                     example\ExampleBindingModule::newInstance()
                                                 ->withCoolStuff()
                                                 ->addAwesomeness(),
                     'example\other\MoreStuffBindingModule'
        );
    }

    ...  other methods here ...
}

If done as in the example the configuration methods need to return the binding module instance of course.

Provided binding modules

Stubbles IoC already provides a stubbles\ioc\module\ModeBindingModule which binds an instance of stubbles\lang\Mode (see Runtime modes). It also ensures that error and exception handlers for this mode are registered. The required mode can be given to the constructor, if none is given it falls back to production mode from stubbles\lang\DefaultMode::prod().

If you need different runtime modes it is advised to extend the mode binding module and overwrite its protected function getFallbackMode() method which should provide the mode depending on your requirements and enviroments.

stubbles\ioc\App already provides a static method createModeBindingModule() which can be used to create the mode binding module.

Dynamic bindings

Available since release 2.1.0

Sometimes it is helpful to define some bindings on the fly in the __bindings() method without having to resort to create a separate binding module implementation. Instead of returning a binding module instance or class name, a closure can be returned as well:

namespace example;
use stubbles\ioc\App;
use stubbles\ioc\Binder;
class MyApplication extends App
{
    /**
     * returns a list of binding modules used to wire the object graph
     *
     * @param   string  $projectPath
     * @return  array
     */
    public static function __bindings($projectPath)
    {
        return array(self::createModeBindingModule(),
                     new example\StuffRequiredForApplicationBindingModule(),
                     'example\other\MoreStuffBindingModule',
                     function(Binder $binder)
                     {
                         $binder->bindConstant('answer')->to(42);
                     }
        );
    }
}

The closure retrieves an instance of stubbles\ioc\Binder as parameter and can add any kind of binding it likes. This can help in situations where you require one or more bindings for a single app only. There is no limitation on how many closures the array to return can contain.