Repository navigation
Essence
Essence is blink's dependency container. It holds bindings from an interface or abstract class to whatever should stand in for it, builds objects by reading their constructor signatures, and calls functions by reading theirs.
Route handlers, module attach() methods, console commands, middleware and event handlers are all invoked through it, so any of them can type-hint a service and receive it.
Bindings are declared in a module's define().
use Blink\Essence;
interface Mailer {
public function send(Message $message): void;
}
class SmtpMailer implements Mailer { ... }
Essence::bind(Mailer::class, SmtpMailer::class);The concrete side can be a class name, a closure that returns the instance, or an already-built object:
Essence::bind(Mailer::class, fn () => new SmtpMailer(env("SMTP_HOST")));
Essence::bind(Clock::class, new SystemClock());bindIf() binds only when nothing is bound yet, which is how a library module offers a default an application can replace.
A singleton is resolved once and the same instance is returned afterwards:
Essence::singleton(Mailer::class, SmtpMailer::class);
Essence::singletonIf(Mailer::class, SmtpMailer::class);Blink's own services (the middleware registry, the listener registry, the Trace writer and registries, the Lightrail coordinator) are singletons registered by Blink::registerCoreSingletons(), which the shutdown handler can also call, so they resolve even after a module failed halfway through boot.
Two classes may want different implementations of the same interface:
Essence::singleton(Mailer::class, SmtpMailer::class);
Essence::when(InvoiceNotifier::class)
-> needs(Mailer::class)
-> give(LoggingMailer::class)
-> singleton();The same mechanism injects primitives a constructor cannot type-hint:
Essence::when(RateLimiter::class)
-> needs("\$perMinute")
-> give(fn () => 120);
class RateLimiter {
public function __construct(int $perMinute = 60) {}
}$mailer = Essence::make(Mailer::class);
Essence::bound(Mailer::class); // truemake() builds any class, bound or not, resolving each constructor parameter in turn: a bound abstract from its binding, a concrete class by building it, a parameter with a default from the default. A cycle in constructor dependencies is detected from the constructor stack and reported as EssenceCircularDependency rather than a stack overflow.
Essence::call() accepts any PHP callable and fills its parameters the same way:
Essence::call(function (Mailer $mailer, Clock $clock) {
$mailer -> send(...);
});
Essence::call([ $controller, "show" ], args: array( "id" => 42 ));
Essence::call("App\\Controller\\Orders::show", binds: array( Request::class => $request ));args supplies named values for parameters by name; binds supplies instances for parameters by type, for the request scoped objects a route handler receives. A parameter that cannot be satisfied any of those ways, and has no default, raises EssenceCallMissingParam naming it.
- Bind in
define(), resolve inattach()or later. Resolving duringdefine()can reach a module that has not declared its bindings yet. - Bind interfaces, not classes, where a second implementation is plausible. A test or a console command can then swap one in with
Essence::bind()before the code under it runs. - An unbound interface raises
EssenceBindingNotDefined, and the error page's tip for it says whichEssence::bind()is missing. -
Essence::forgetSingleton()drops a built instance so the nextmake()builds a fresh one. The Ticker runner does not need it: it clears model instances and metrics between tasks but keeps services.
| Exception | Raised when |
|---|---|
EssenceBindingNotDefined |
An interface or abstract class is resolved with no binding |
EssenceInvalidConcrete |
A binding's concrete side is not a class, closure or object |
EssenceInvalidInstance |
A concrete object does not implement the abstract it was bound to |
EssenceCircularDependency |
Constructors depend on each other in a loop |
EssenceInvalidCallable |
call() was given something it cannot invoke |
EssenceCallMissingParam |
A parameter has no binding, no argument and no default |
EssenceCallMissingBind |
A binds entry names a type the callable does not take |
EssenceCallArgumentMismatch |
An args value does not fit the parameter's type |