Skip to content

Modules

Belikhun edited this page Sep 15, 2026 · 2 revisions

🧩 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 );

A module

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

The lifecycle

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:apply included. 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.

Declarative lists

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.

Helpers

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.

The core module

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");

Where things live

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

Clone this wiki locally