Download the PHP package tholabs/creator without Composer

creator

creator is a simple PHP dependency injection that works with typehints and Reflection classes

• Installation
• Testing
• Basic Usage
• PSR-11 Container Usage
• Injected Instances
• Invoke Closures / Callables
• Factories
• Uninstantiable Classes
• Registering Resources
• Exceptions

Installation

via composer `

Testing

via phpunit `

Basic Usage

With class constant

``

With recursive dependencies

assuming our MyClass looks like this: `` Creator will walk up the dependency tree and resolve any class which has no known instance yet.

PSR-11 Container usage

Creator supports the PSR-11 psr/container standard.

The $container->has() will return true if:

• a primitive resource with given $identifier has been registered using $creator->registerPrimitiveResource()
• a class resource with given $identifier has been registered using $creator->registerClassResource()
• a class resource factory for $identifier has been registered using $creator->registerFactory()
• $identifier is an interface or abstract class that can be fulfilled (because another instance implementing or inheriting has been registered earlier)

It will not return true if a given $identifier might be instantiable.

Injected Instances

Creator is able to use an independent resource registry for a single creation process. `` Any other dependency of MyClass is being resolved the usual way (i.e. looked up via the ResourceRegistry and, if there is no instance yet, it's being created with the same injected resources.) Creator collects dependency signatures and thus only re-creates instances that really require an injected dependency.

Invoke Closures / Callables

Creator is able to resolve parameters of closures and callables (invokables). It supports closures and method-context array callables with the object at index 0 (using the class name at index 0 is currently not supported and will cause Creator to throw an Unresolvable exception).

Injecting instances is supported as well. ``

Factories

If you have resources that can not be created without additional logic, but also should only be created once another component depends them, you can register a factory for this factory. A factory can be a callable, an instance of Creator\Interfaces\Factory or a class string of a Factory (see lazy bound factories) and can be registered for any class resource, i.e. interfaces, abstracts or normal classes.

Global Factories

`` This comes in especially handy for stuff like database connections where you only want to create a connection if a component really depends on it.

Injected Factories

Of course, you can also register a factory as injection: `` Injected factories overrule globally registered factories and even globally registered resources. However, they do not overrule injected resources. (Creation order routine is: Injected Instance -> Injected Factory -> Global Instance -> Global Factory -> Create Instance)

Self Factories

To avoid the need of a global factory, classes can also implement the Creator\Interfaces\SelfFactory interface. All classes implementing this interface will not be built using their constructor; instead, they have to return a factory closure:

It is worth nothing here that not returning an instance of the class will throw an InvalidFactoryResult exception.

Lazy Bound Factories

If you have factories that should not be created until they are required, you can register a lazy factory by using it's class name:

``

All lazy bound factories are stored to and read from the ResourceRegistry that defined them: ``

Factory Result Caching

All factory results are registered to their corresponding ResourceRegistry, i.e. a injected factory will store it's result to the injected registry and thereby make it's created resource available during this creation process only. The only exception is a lazy bound factory with an injected dependency; in that case, the result of the factory is cached in the injection registry.

` In the example above, the instances ofArbitraryClassWithSimpleClassDependencywill not be the same. Creator detects thatSimpleClassis a dependency of the registered factory and therefore create a new instance ofArbitraryFactorywith the injectedSimpleClass`. This new factory instance is stored to the injected registry and will not affect other creations.

Uninstantiable Classes

Singletons

Singletons can be resolved if they implement the Creator\Interfaces\Singleton interface.

Abstracts, Interfaces

If Creator stumbles upon an interface or an abstract class, it will try to look up the resource registry if any resource implements the interface / abstract class. First one is being served.

Registering Resources

Classes

If you want creator to use a certain instance of a class, you can register any object to Creator. It will then use this instance for any upcoming creation - a more "persistent" injection. ` The optional second parameter$classResourceKeyof the methodregisterClassResource` bypasses a get_class determination of the object. This might break code completion and type hinting, so use it wisely.

Primitive (scalar) Resources

Creator supports registering scalar values by variable name.

``

In previous versions of Creator, there was a method to register primitive resources in the global registry. This has been removed as it might cause unexpected behaviour and hinder future development.

However, if you really need it (but don't say nobody told you it's a bad idea), you can still achieve this by registering the scalar value to a ResourceRegistry and pass this registry while constructing your Creator\Creator instance. See the tests for example code.

Primitive resource specifics

• If an argument has a default value and Creator can not find a matching scalar value, it will use the default value.
• Registering an object with Creation::with() will always result in a class resource registration, i.e. registering $creation->with($myInstance, 'foo'); will only register $myInstance as class foo, but never as primitive resource.

Exceptions

All exceptions derive from Creator\Exceptions\CreatorException. Use this class in your catch block to catch all Creator-related exceptions.

Additionally, there are more specific exceptions:

• If Creator is unable to resolve a dependency, it will throw Creator\Exceptions\Unresolvable.
• If you are registering a factory which is not a callable or an instance of / a class name of a class that implements Creator\Interfaces\Factory, it will throw Creator\Exceptions\InvalidFactory.
• If a self-factory returns a class which is not an instance of self, it will throw Creator\Exceptions\InvalidFactoryResult.