Skip to content

Essence

Belikhun edited this page Sep 15, 2026 · 1 revision

🧬 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.

Binding

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.

Singletons

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.

Contextual binding

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) {}
}

Resolving

$mailer = Essence::make(Mailer::class);
Essence::bound(Mailer::class); // true

make() 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.

Calling

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.

Rules of thumb

  • Bind in define(), resolve in attach() or later. Resolving during define() 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 which Essence::bind() is missing.
  • Essence::forgetSingleton() drops a built instance so the next make() builds a fresh one. The Ticker runner does not need it: it clears model instances and metrics between tasks but keeps services.

Exceptions

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

Clone this wiki locally