README

Jiggle is a depency injection container for php 5.3+

By default every dependency is a singleton. If you assign an function to to the container it is considered as an singleton factory. So the function is only called once when the dependency is required the first time.

Methods

singleton($class)

Create a singleton factory for the given class

param string $class the class which should be instantiated
return callable

create($class)

Create an object of the given class

If the class constructor has arguments they are injected from the current jiggle instance.

param string $class the class to instantiate
return object the newly created instance

inject($callable, $overloadedDeps = array())

Executes the given callable

If the callable has arguments they are injected from the current jiggle instance.

param callable $callable the callable to invoke
param array $overloadedDeps optional additional or overloaded dependencies
return mixed return value of the invoked callable

replace($name, $value)

Replace an existing dependency

Usefull if one would like to mock some part of a bigger system or for clients to replace an unwanted implementation.

param string $name of the dependency to replace
param mixed $value replacement implementation

resolver($callable)

Let one provide a callable which is called if a dependency is not resolvable

If the provided resolver can resolve the dependency it should simply return it. If the dependency could not resolved the resolver needs to throw an exception, otherwise the dependency would be resolved to null.

param callable $callable the resolver callabe

Examples

Set and get dependencies

$jiggle = new Jiggle;
$jiggle->d1 = 42;
echo $jiggle->d1; // => 42

Lazy loading with factory functions

$jiggle = new Jiggle;
$jiggle->d1 = function() {
    return 42;
};
echo $jiggle->d1; // => 42

Basic wiring of dependencies

$jiggle = new Jiggle;
$jiggle->d1 = 42;
$jiggle->d2 = function() use($jiggle) {
    return $jiggle->d1;
};
echo $jiggle->d2; // => 42

Implicit injection of depencies into singleton factory functions

$jiggle = new Jiggle;
$jiggle->d1 = 42;
$jiggle->d2 = function($d1) {
    return $d1;
};
echo $jiggle->d2; // => 42

Explicit injection of depencies into any function

$jiggle = new Jiggle;
$jiggle->d1 = 40;
$jiggle->d2 = 2;
$result = $jiggle->inject(function($d1, $d2) {
    return $d1 + $d2;
});
echo $result; // => 42

Explicit injection with dependency overloading

$jiggle = new Jiggle;
$jiggle->d1 = 20;
$jiggle->d2 = 1000;
$result = $jiggle->inject(function($d1, $d2, $d3) {
    return $d1 + $d2 + $d3;
}, array('d2' => 20, 'd3' => 2));
echo $result; // => 42

Basic instantiation

$jiggle = new Jiggle;
$jiggle->d1 = 40;
$jiggle->d2 = 2;
$jiggle->d3 = function() use($jiggle) {
    return new D3($jiggle->d1, $jiggle->d2);
};
echo $jiggle->d3->sum(); // => 42

Instantiation with implicit constructor injection

$jiggle = new Jiggle;
$jiggle->d1 = 40;
$jiggle->d2 = 2;
$jiggle->d3 = function() use($jiggle) {
    return $jiggle->create('D3');
};
echo $jiggle->d3->sum(); // => 42

Short form of implicit constructor injection

$jiggle = new Jiggle;
$jiggle->d1 = 40;
$jiggle->d2 = 2;
$jiggle->d3 = $jiggle->singleton('D3');
echo $jiggle->d3->sum(); // => 42

Basic function dependency

$jiggle = new Jiggle;
$jiggle->d1 = function() {
    return function() {
        return 42;
    };
};
echo $jiggle->d1(); // => 42

Existing deps could not replaced by accident

$jiggle = new Jiggle;
$jiggle->a = true;
$jiggle->a = false; // <- throws an exception

Existing deps could be replaced implicitly

$jiggle = new Jiggle;
$jiggle->d1 = 21;
$jiggle->replace('d1', 42);
echo $jiggle->d1; // => 42

Isset support

$jiggle = new Jiggle;
$jiggle->d1 = 42;
$this->assertTrue(isset($jiggle->d1));
$this->assertFalse(isset($jiggle->d2));

Resolver is called for unresolvable deps

$jiggle = new Jiggle;
$jiggle->resolver(function($dependencyName) {
    if ($dependencyName == 'd2') {
        return 42;
    }
    throw new Exception("Could not resolve dependency: $dependencyName!");
});
$jiggle->d1 = function($d2) { return $d2; };
echo $jiggle->d1; // => 42

Composer

{
    "require": {
        "holgerk/jiggle": "*"
    }
}

License

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

holgerk / jiggle

Maintainers

Details