talesoft / tale-di
A PSR-15 compatible HTTP utility library
Requires
- php: >=7.0.8
- psr/container: ^1.0@dev
README
Tale DI
What is Tale DI?
Tale DI is a lightweight implementation of the PSR-11 Dependency Injection spec will full auto-wiring support.
The API might still change here and there.
Installation
composer req talesoft/tale-di
Usage
ContainerBuilder
use Tale\Di\ContainerBuilder;
Using the ContainerBuilder, you can auto-wire a fully working DI container including full PSR-6 cache support.
The container returned will be a Tale\Di\Container
which is
explained below.
$cachePool = new RedisCachePool(); $builder = new ContainerBuilder($cachePool); $builder->add(ViewRenderer::class); $builder->add(ControllerDispatcher::class); $builder->addInstance(new PDO(...)); $container = $builder->build(); $pdo = $container->get(PDO::class);
Service Locators
use Tale\Di\ServiceLocator\FileServiceLocator;
use Tale\Di\ServiceLocator\DirectoryServiceLocator;
use Tale\Di\ServiceLocator\GlobServiceLocator;
If you don't want to add every single file manually, you can also use one of the three service Locators that come with Tale DI.
$builder->addLocator( new FileServiceLocator('src/Classes/MyClass.php') ); $builder->addLocator( new DirectoryServiceLocator('../src') ); $builder->addLocator( new GlobServiceLocator('../src/{Controller,Model}/**/*.php') ); $container = $builder->build();
Injections and philosophy
Tale DI, by design, only allows constructor injections. There
are no optional dependencies that are not covered in a constructor
and there are no XyzAware
interfaces and no possibility to do it.
This avoids a lot of magic and defensive null checks all over your code. If this is not what you like, Tale DI might not be what you're looking for. I suggest you give it a try anyways.
Injections happen simply by class name or an interface it implements:
class OrderProvider { public function __construct(OrderRepository $repository) } $orderProvider = $container->get(OrderProvider::class);
It doesn't matter if you ever added the dependency to the container, it will auto-wire any external (or internal) dependency that has a readable type (and even that can be handled). This is possible because Tale DI works solely based on PHPs existing class mechanisms, interfaces and reflection.
interface ViewRendererInterface { } class ViewRenderer implements ViewRendererInterface { } //... $renderer = $container->get(ViewRendererInterface::class); // $renderer is instanceof ViewRenderer
Optional dependencies work as expected and should be defaulted to default/null implementations so no defensive null checks are required.
class AvatarGenerator { /** * @var CacheInterface */ private $cache; public function __construct(CacheInterface $cache = null) { $this->cache = $cache ?? new RuntimeCache(); } }
Iterables and Arrays of interfaces
Tale DI has a notion of Tags specified through plain PHP interfaces. You can inject by using interfaces:
class EntityManager { public function __construct(DbalInterface $dbal) }
and through proper type-hinting in the doc-comment you can even inject all instances of a specific interface:
class Importer { /** * @param iterable<\App\Service\Importer\WorkerInterface> */ public function __construct(iterable $workers) { foreach ($workers as $worker) { $this->initializeWorker($worker); } } /** * @param array<\App\Service\Importer\WorkerInterface> */ public function __construct(array $workers) { $this->workers = array_filter($workers, fn($worker) => $worker->canImport()); } }
This will inject all known dependencies of type WorkerInterface
into the workers
argument.
Parameters
Tale DI can't only inject classes and instances, you can specify fixed parameters that are injected based on their names. Notice they should be serializable to make use of the caching mechanisms.
$builder->setParameter('someParameter', 'some value'); //Any class with a parameter 'someParameter' will get 'some value' injected as a string
The second parameter allows you to reduce the parameter to be used on a specific class or interface only.
This also allows creating instances of external types without requiring a specific factory for it:
class UserManager { public function __construct(PDO $pdo) { $this->pdo = $pdo; // Fully working PDO instance! } } $builder->setParameters([ // These are the parameter names PDO internally uses in its constructor! 'dsn' => 'mysql:host=localhost', 'username' => 'root', 'passwd' => '', 'options' => [PDO::ATTR_ERRMODE => PDO_ERRMODE_EXCEPTION] ], PDO::class); $builder->add(UserManager::class); $container = $builder->build(); $userManager = $container->get(UserManager::class); // PDO will be fully wired in UserManager
Manually construct container
The base setup of the container is pretty simple. Most of the stuff is
used for the auto-wiring mechanism, but you can also completely avoid
the ContainerBuilder
and use containers directly.
Tale DI brings three base containers with it that you can use for their specific purposes.
Container
use Tale\Container;
The Tale Container and the heart of the DI system is a container
that resolves values through specific Tale\Di\DependencyInterface
instances. This is how it works:
$dependencies = [ //Value Dependency is just a value. Can be any kind of value. 'test value' => new ValueDependency('some value'), //A reference dependency references another value in the container 'reference' => new ReferenceDependency('test value'), //A callback dependency only gets resolved when it's requested 'factory' => new CallbackDependency(function (ContainerInterface $container) { return new Something($container->get(SomethingElse::class)); }), //Same as CallbackDependency, but will cache the result between each ->get() call 'lazy factory' => new PersistentCallbackDependency(function () { return (new SomeHeavyWorker())->getResult(); }) ]; $container = new Container($dependencies); $container->get('test value'); //"some value" $container->get('reference'); //"some value" // etc.
You can always define own dependency types and how they are resolved
by implementing Tale\Di\DependencyInterface
:
final class PdoDependency implements DependencyInterface { private $pdo; public function __construct() { $this->pdo = new PDO(...); } public function get(ContainerInterface $container) { return $this->pdo; } } $container = new Container(['pdo' => new PdoDependency()]); $pdo = $container->get('pdo'); $stmt = $pdo->prepare(...);
ArrayContainer
use Tale\Di\Container\ArrayContainer;
Mostly useful for testing, this is a really basic implementation of PSR-11 that just maps fixed names to values
$container = new ArrayContainer([ SomeClass::class => new SomeClass(), 'test key' => 15 ]); $container->get(SomeClass::class); //SomeClass instance $container->get('test key'); //15
NullContainer
use Tale\Di\Container\NullContainer;
A Null Container that always returns false when calling ->has()
and
always throws a NotFoundException
when calling ->get()
.
This is mostly useful as a default container for classes that want to decorate containers as an optional dependency and require a default implementation to avoid defensive null checks.
final class AdapterFactory { public function __construct(ContainerInterface $container = null) { $this->container = $container ?? new NullContainer(); } public function createAdapter(): AdapterInterface { $adapter = null; if ($this->container->has(SomeAdapter::class)) { $adapter = $this->container->get(SomeAdapter::class); } else if ($this->container->has(SomeOtherAdapter::class)) { $adapter = $this->container->get(SomeOtherAdapter::class); } else { $adapter = new SomeDefaultAdapter(); } return $adapter; } }
Type Information
use Tale\Di\TypeInfoFactory\PersistentTypeInfoFactory;
Notice this will probably end up in an own library at some point.
$typeInfoFactory = new PersistentTypeInfoFactory(); $typeInfo = $typeInfoFactory->get('array<int>'); $typeInfo->isGeneric() //true $typeInfo->getGenericType()->getName() //array $typeInfo->getGenericTypeParameters()[0]->getName() //int
Parameter Reader
use Tale\Di\ParameterReader\DocCommentParameterReader;
A parameter reader that also takes into account
doc comment @param
-annotations
$typeInfoFactory = new PersistentTypeInfoFactory(); $paramReader = new DocCommentParameterReader($typeInfoFactory); $reflClass = new ReflectionClass(SomeClass::class); $params = $paramReader->read($reflClass->getMethod('__construct'); var_dump($params);