Repository navigation
Modules
A module is the unit of application wiring. Everything an application adds to blink is declared by one: bindings, routes, middleware, commands, observers, recurring work and schema layers. List your modules in CONFIG::$MODULES and blink boots them in that order, after its own CoreModule.
// config.php
CONFIG::$MODULES = array( App\AppModule::class );namespace App;
use App\Console\ImportOrders;
use App\Contract\Mailer;
use App\Model\User;
use App\Observer\OrderObserver;
use App\Service\SmtpMailer;
use App\Task\RebuildReports;
use Blink\Essence;
use Blink\Ether;
use Blink\Module;
use Blink\Ticker\Orbit;
class AppModule extends Module {
public function define(): void {
Essence::singleton(Mailer::class, SmtpMailer::class);
\Blink::useUserClass(User::class);
$this -> layers(BASE_PATH . "/db/terra");
}
public function attach(): void {
Ether::use(Middleware\RequireWorkspace::class, "workspace", 150);
$this -> routes(BASE_PATH . "/routes/admin");
}
public function orbits(Orbit $orbit): void {
$orbit -> task(RebuildReports::class) -> everyDay("02:00") -> alone();
}
public function commands(): array {
return array( ImportOrders::class );
}
public function observers(): array {
return array( OrderObserver::class );
}
}Blink boots modules in two passes. Every module goes through the first before any goes through the second.
| Phase | When | What belongs here |
|---|---|---|
config() |
Before anything else, on every module | Config classes the module ships, registered and filled from the environment. |
define() |
First, on every module | Essence bindings, the user class, layer directories. Only declarations. |
| schema | Between the phases, web requests only | Terra raises any pending layer, so every module's tables exist before attach(). |
attach() |
Second, on every module, through Essence::call()
|
Routes, middleware, listeners, anything that needs the bindings every module declared. |
detach() |
From the shutdown handler, in reverse order | Releasing what attach() claimed. The response has already gone out. |
Two rules follow from the ordering:
-
define()only binds. Resolving a binding there can reach a module that has not had its turn yet, and a query would run against a schema that has not been raised. Bind with a class name or a closure and let resolution happen later. -
attach()must not query the database. It runs on every request and every console command,terra:applyincluded. A query against a table that does not exist yet would break the very command that creates it.
attach() is invoked through Essence, so it can type-hint the services it wires against:
public function attach(LevelRegistry $levels, ListenerRegistry $listeners): void {
$levels -> register(45, "security", "app.trace.level.security", "red");
}A module that throws during either phase is recorded as [class, phase] for the error page's Modules context and the exception is rethrown unchanged, so the failure is reported where it happened rather than as a later symptom.
commands() and observers() return class lists rather than registering anything, because two things need to re-read them without re-running attach(): the console when it lists commands, and the Lightrail registry when it rebuilds its cache. Both lists also feed the cache version, so adding a command or observer invalidates what depends on it.
orbits() is imperative because entries take arguments, but it is called once a minute by ticker:tick and must stay cheap: build the entries and return. Whether an entry is due is decided afterwards.
| Method | Does |
|---|---|
$this -> routes($directory) |
Loads every route file in a directory. Call it from attach(). |
$this -> layers($directory) |
Adds a directory of Terra layers to the stack. Call it from define(): discovery happens before any module attaches. |
Blink\Module\CoreModule is always first. It registers the default middleware stack (auth, setupEnv and cors, with auth and setupEnv grouped as router), the /error routes, every built-in command, the ModelAuditObserver, and the recurring lightrail:flush --stale and trace:purge entries.
Your module can lean on those aliases:
Router::GET("/public/status", fn () => "ok") -> withoutMiddleware("auth");site/
index.php require_once "core/setup.php";
config.define.php class CONFIG extends CoreConfig {}
config.php values
classes/ App\ namespace, resolved through CONFIG::$AUTOLOAD
routes/ route files, loaded from CONFIG::$ROUTES_ROOT
db/terra/ the application's schema layers
data/ caches, error reports, files; ignored by git
core/ blink