catacgc/juice-di-container

Small, fast, feature rich Dependency Injection for PHP 5.2

Juice - Fast DI Container for PHP >= 5.2

Features

• small and fast
• compatible with PHP 5.2
• lighter than most other PHP DI container implementations (Symfony2, ZF2)
• fluent service definition interface
• tag service definitions
• circular dependency resolver
• ArrayAccess implementation so it can be easily be mocked in tests with an array

Installing

The container is comprised of a single file, src/Container.php, _(*1)

For PHP 5.2 you can use curl / wget / git to download that file and simple require it, _(*2)

For PHP 5.3 on, you can use composer:, _(*3)

{
    "catacgc/juice-di-container": "dev-master"
}

After cloning the repo, you can run the tests with phpunit:, _(*4)

phpunit -c phpunit.xml.dist

Creating the container

require 'src/Container.php';
$container = new JuiceContainer();

Container values

The container stores parameters as key => value, but it's main benefit is the runtime wiring of services, _(*5)

The services are created using two special container values:, _(*6)

• JuiceDefinition instances
• valid php callbacks (including closures, from PHP 5.3 on) that receive the container instance as their only parameter to allow referencing of other parameters or services

Parameters

$container['mysql_host'] = 'localhost';
$container['mysql_user'] = 'username';
$container['mysql_pass'] = 'password';
$container['mysql_port'] = 3306;

echo $container['mysql_port'];

Service definitions

Because creating factory methods for every service is tedious, the container specially handles a JuiceDefinition type that is handy when creating complex services, _(*7)

You can reference other services or parameters in a definition using @service_id notation in all of JuiceDefinition method arguments, _(*8)

API

// simple class
$container['conn'] = new JuiceDefinition('Connection');   // => new Connection()

// or using the fluent interface to do the same
$container['conn'] = JuiceDefinition::create('Connection')

// replacing the class name
$container['conn'] = JuiceDefinition::create('Connection')->className('ChangedMyMindConnection')

// providing arguments
JuiceDefinition::create('Connection', array('username', 'password'))

// replacing arguments
JuiceDefinition::create('Connection')->arguments(array('username1', 'password1'))

// replacing specific argument
JuiceDefinition::create('Connection')->argument(0, 'new_username')

// calling methods
JuiceDefinition::create('Connection', array('user', 'pass'))
    ->call('setDb', array('db_name'))

Constructor injection:

$container['conn'] = new JuiceDefinition('MysqlConnection', array('@mysql_user', '@mysql_password'));
$container['dbal'] = new JuiceDefinition('Dbal', array('@conn'));

Now calling $dbal = $container['dbal'] is equivalent with calling, _(*9)

$connection = new MysqlConnection('username', 'password');
$dbal = new Dbal($connection);

Setter injection

$container['conn'] = new JuiceDefinition('Connection');
$container['dbal'] = JuiceDefinition::create('Dbal')->call('setConnection', array('@conn'))

Extending definitions

$container['conn'] = JuiceDefinition::create('MysqlConnection');

// now in another module, in its configuration 

$connDef = $container->raw('conn');
$connDef->className('MysqlWrapperConnection');

Adding services from callbacks

Every callable that is passed to the container will be called, when retrieved by the client, with the container instance as it's only parameter and the return value will represent the actual service / parameter for the associated id., _(*10)

$container['db'] = array('Factory', 'createDbConnection');
$pdoObject = $container['db']; //actually calls the factory method

where the factory will look like:, _(*11)

class Factory
{
    public static function createDbConnection($container) // <- note the container parameter
    {
        return new PDO(
            sprintf('mysql:host=%s;dbname=%s', $container['mysql_host'], $container['mysql_dbname']),
            $container['mysql_user'],
            $container['mysql_pass']
        );
    }
}

• Note: all callbacks receive the container as their only argument

Service aliasing

$container['mysql_default_connection'] = JuiceDefinition::create('MysqlConnection', array('@mysql_username', '@mysql_password'));
$container['connection'] = '@mysql_default_connection';

Now $container['connection'] and $container['mysql_default_connection'] will refer to the same service instance, _(*12)

Escaping callbacks and other special types

There are times when your intent is to actually add a callback as a real parameter, not creating a service definition, _(*13)

For this purpose there is a special wrapper type JuiceParam that you can use:, _(*14)

$container['invalid_callback'] = 'strpos';
echo $container['invalid_callback'];

Gives an error because for php strpos is a callable type and the container will try to call it with strpos($container) to retrieve the supposed service instance, _(*15)

$container['callback'] = new JuiceParam('strpos');
echo $container['callback']; //now echoes the expected 'strpos' string

Locking behaviour

After a parameter or a service is retrieved from the container, you will not be able to add, overwrite or extend services anymore. Eg:, _(*16)

$container['param'] = 1;
echo $container['param'];

$container['param'] = 2; //throws exception

This is done on purpose to enforce the configuration before usage and stable behaviour: once you used a service, you can count that you have the same service throughout the application., _(*17)

For testing purposes you can overwrite this behaviour by calling $container->unlock();, _(*18)

Creating new service instances

The default behaviour is to retrive the same service instance on each call., _(*19)

If you want to create new service instances on the fly use the build method:, _(*20)

$conn1 = $container->build($container->raw('conn'));
$conn2 = $container->build($container->raw('conn'));

Full example usage

/**
* Configuration
*/

$container = new JuiceContainer();

$container['cache_dir'] = '/tmp/cache';
$container['memcache_host'] = 'localhost';
$container['memcache_port'] = 11211;

$container['main_cache'] = JuiceDefinition::create('Memcache')
    ->call('connect', array('@memcache_host', '@memcache_port'));

$container['slow_cache'] = JuiceDefinition::create('FileCache')
    ->arguments(array('@cache_dir'));

$container['two_level_cache'] = JuiceDefinition::create('TwoLevelCache')
    ->arguments(array('@main_cache', '@slow_cache'));

$container['cache'] = '@two_level_cache';

/**
* Usage
*/

$cache = $container['cache'];

if ($data = $cache->load('expensive_operation_id')) {
    //cache hit
    return;
}

$cache->save('expensive_operation_id', do_expensive_operation(), 60);