- Installation
- Creating a container
- Primitive data
- Classes
- Factories
- Interfaces
- Functions and methods
- Singletons
- Wildcards
- Aliases
- Additional methods
- Extensions
composer require weew/container
The container has no additional dependencies, so a simple instantiation will do the trick.
$container = new Container();
Storing any type of data:
$container->set('foo', 'bar');
// returns bar
$container->get('foo');
Retrieving classes:
class Foo {}
// returns a new instance of Foo
$container->get(Foo::class);
Passing additional parameters:
class Foo {
public function __construct($x, $y = 2) {};
}
// parameters are matched by name
$container->get(Foo::class, ['x' => 1]);
Resolving constructor dependencies:
class Foo {
public function __construct(Bar $bar) {}
}
class Bar {}
// returns a new instance of Foo,
// Foo's constructor receives a new instance of Bar
$container->get(Foo::class);
Sharing a specific instance:
class Foo {}
$container->set(Foo::class, new Foo());
// or
$container->set(new Foo());
// everyone will get the same instance of Foo
$container->get(Foo::class);
Working with factories:
class Foo {
public $bar;
}
class Bar {}
// a factory method will get it's dependencies resolved too.
$container->set(Foo::class, function(Bar $bar) {
$foo = new Foo();
$foo->bar = $bar;
return $foo;
});
Accessing container from within a factory:
$container->set('foo', 1);
// a container can be injected the same way as any other dependency
$container->set('bar', function(IContainer $container) {
return $container->get('foo');
));
Container is not limited to closure factories, it supports class method and static method factories too:
class MyFactoryClass {
public function factoryMethod(AnotherDependency $dependency) {}
public function staticFactoryMethod(AnotherDependency $dependency) {}
}
$container->set(Foo::class, new MyFactoryClass(), 'factoryMethod');
$container->set(Foo::class, MyFactoryClass::class, 'factoryMethod');
$container->set(Foo::class, MyFactoryClass::class, 'staticFactoryMethod');
Traditional callable array syntax is also supported. It does exactly the same as the examples above, but with a slightly different syntax:
$container->set(Foo::class, [new MyFactoryClass(), 'factoryMethod']);
$container->set(Foo::class, [MyFactoryClass::class, 'factoryMethod']);
$container->set(Foo::class, [MyFactoryClass::class, 'staticFactoryMethod']);
All facotires benefit from dependency injection. Additionaly, if you let the container instantiate your factory, it will be resolved trough the container too.
Resolving interfaces:
interface IFoo {}
class Foo implements IFoo {}
$container->set(IFoo::class, Foo::class);
// will return an instance of Foo
$container->get(IFoo::class);
Sharing specific interface implementation:
interface IFoo {}
class Foo implements IFoo {}
$container->set(IFoo::class, new Foo());
// everyone will get the same instance of Foo
$container->get(IFoo::class);
Interfaces can have factories too:
interface IFoo {}
class Foo implements IFoo {}
$container->set(IFoo::class, function() {
return new Foo();
});
// will return a new instance of Foo
$container->get(IFoo::class);
Of course you can also type hint interfaces:
interface IFoo {}
class Foo implements IFoo {}
class Bar {
public function __construct(IFoo $foo) {}
}
$container->set(IFoo::class, Foo::class);
// returns an instance of Bar
// Bar receives an instance of Foo, which implements the interface IFoo
$container->get(Bar::class);
Functions can get resolved by the container:
class Bar {}
function foo(Bar $bar, $foo) {}
// method foo gets called and receives an instance of Bar
// as with the other container methods, you can always pass your own arguments
$container->callFunction('foo', ['foo' => 1]);
The same works for closures:
class Bar {}
// closure gets called and receives an instance of Bar
$container->callFunction(function(Bar $bar) {});
Invoking class methods is also strait forward:
class Foo {}
class Bar {
public function takeFoo(Foo $foo, $x) {}
}
$bar = new Bar();
// method takeFoo gets invoked and receives a new instance
// of Foo, as well as the custom arguments
$container->callMethod($bar, 'takeFoo', ['x' => 1]);
// you could also let the container create an instance
$container->callMethod(Bar::class, 'takeFoo', ['x' => 1]);
Invoking static methods:
class Foo {}
class Bar {
public static function takeFoo(Foo $foo, $x) {}
}
// method takeFoo gets invoked and receives a new instance
// of Foo, as well as the custom arguments
$container->callStaticMethod(Bar::class, 'takeFoo', ['x' => 1]);
It is possible to use PHP's traditional callable syntax for invocation of functions and methods:
// same as $container->callFunction($functionName, $args)
$container->call($functionName, $args);
// same as $container->callFunction($closure, $args)
$container->call($closure, $args);
// same as $container->callMethod($instance, $method, $args)
$container->call([$instance, $method], $args);
// same as $container->callMethod($className, $method, $args)
$container->call([$className, $method], $args);
// same as $container->callStaticMethod($className, $staticMethod, $args)
$container->call([$className, $staticMethod], $args);
Container values can be defined as singletons. A singleton definition will return the same value over and over again. Here is an example of a singleton interface definition:
interface IFoo {}
class Foo implements IFoo {}
$container->set(IFoo::class, Foo::class)->singleton();
The same works for classes:
class Foo {}
$container->set(Foo::class)->singleton();
And factories:
class Foo {}
$container->set(Foo::class, function() {
return new Foo();
})->singleton();
Sharing an instance always results in a singleton:
class Foo {}
$container->set(Foo::class, new Foo())->singleton();
// same as
$container->set(Foo::class, new Foo());
This one might be especially useful when working with factories. Lets take Doctrine for example. You can not simply instantiate a repository by yourself. But still, it would be great if you could have them resolved by the container. Unfortunately, this will throw an error, since the repository requires a special parameter that can and should not be resolved by the container:
class MyRepository {
public function __construct(SpecialUnresolvableValue $value) {}
}
$container->get(MyRepository::class);
However, you might use a wildcard factory. You can use any regex pattern as a mask. Right now, the only supported regex delimiters are /
and #
.
class MyRepository implements IRepository {
public function __construct(SpecialUnresolvableValue $value) {}
}
class YoursRepository implements IRepository {
public function __construct(SpecialUnresolvableValue $value) {}
}
$container->set('/Repository$/', function(RepositoryFactory $factory, $abstract) {
return $factory->createRepository($abstract);
});
$container->get(MyRepository::class);
$container->get(YourRepository::class);
As you see here, the actual class name MyRepository
was passed to the custom factory as the $abstract
parameter. From there, we call the RepositoryFactory
and tell it to create us a new instance of MyRepository
. Afterwards the same factory can be used to create an instance of YourRepository
.
Telling the container that all instances produced within this factory should be singletons is very simple:
$container->set('/Repository$/', function(RepositoryFactory $factory, $abstract) {
return $factory->createRepository($abstract);
})->singleton();
Wildcards are very powerful, however, they should be used with caution, since they could break your application if you configure them wrong. (for example: if the regex mask is not precise enough and matches unwanted classes). Thanks to regex, creating precise masks shouldn't be a big deal though.
Wildcards can also be used in combination of class names and instances. But I find the usecases for this very limited:
$container->set('/Repository$/', EntityRepository::class);
$container->set('/Repository$/', $instance);
If you need to create an alias for a definition, for example when you want to provide a factory for a class as well as for it's interface, and don't want to do it twice for each one, you could create a definition with an alias (or two, or ten). Just provide an array of identifiers. The first element in the array is considered as "the id" and the others are aliases.
$container->set([MyImplementation::class, IImplementation::class], function() {
return new MyImplementation('foo');
});
// both calls will return a value from the same factory
$container->get(MyImplementation::class);
$container->get(IImplementation::class);
The same would work with singletons, primitive values and so on.
Check if the container has a value:
$container->set('foo', 'bar');
// will return true
$container->has('foo');
Remove a value from the container:
$container->set('foo', 'bar');
$container->remove('foo');
// will return false
$container->has('foo');
There are additional extension available to make the container even more powerful.
The weew/container-doctrine-integration package makes doctrine repositories injectable.