Two Phases, Two APIs

Mike Georgeff — Tue, 09 Jun 2026 03:01:24 +0000

Most applications have no enforced lifecycle boundaries. Services get resolved at arbitrary times, configs mutate mid-request, init logic bleeds into request handling. The result is an application that is difficult to reason about because its state is never truly settled.

The Two Phases

Boot: The period before the application handles any work. The sole purpose of the boot phase is construction, registering service definitions, merging configuration, wiring dependencies, and running initialization logic. When boot ends, the service layer is immutable, nothing new can be registered, nothing can be reconfigured.

Run: The application transforms inputs into outputs using the fully constructed service layer. No reconfiguration, no new definitions, no structural mutations, only pure transformation.

The hard boundary between boot and run is not a convention, it is a constraint.

Why the Boundary Matters

Predictability: if the service layer is immutable after boot you always know what you are working with during a request
Testability: an immutable service graph is easy to inspect and reproduce in tests
Debuggability: boot-time errors fail loud and early, they do not surface as mysterious runtime behavior
Security: a service layer that cannot be mutated at runtime prevents the injection of rogue providers or configuration overrides, shrinking the attack surface

Boot is boot, run is run, this should be enforced, not suggested.

The Two APIs

The package georgeff/kernel enforces this at the type level.

When correctly composed, kernel definitions are registered before boot is called, and the fully initialized container is available after.

$kernel = new Kernel();

$kernel->addDefinition(MyClass::class, fn() => new MyClass());
$kernel->boot();
$container = $kernel->getContainer();

$container->get(MyClass::class);

When addDefinition is called after boot, a KernelException will be thrown because the service layer is immutable.

$kernel = new Kernel();

$kernel->boot();
$kernel->addDefinition(MyClass::class, fn() => new MyClass());

If the container is accessed before boot, a KernelException will be thrown because the container has not yet been initialized.

$kernel = new Kernel();

$container = $kernel->getContainer();

$kernel->boot();

Run begins the moment boot() returns, after the kernel is a resolved, immutable service graph. The handoff from construction to transformation is complete.

Modules as Boot-Time Citizens

In the georgeff/kernel package, modules enforce the phase separation by design. ModuleInterface::register() is a boot-time method, whose purpose is to register service definitions, tags, and decorators. BootableModuleInterface::boot() is called at the tail end of the boot cycle, providing access to the built container for initialization work. New definitions cannot be registered at this stage since the service graph is already sealed. Neither has any role in run, making it structurally impossible to blur the line.

Phases as Architecture

The boot/run distinction is not a pattern unique to this kernel, it is a general principle that most applications implement accidentally and inconsistently. Making it explicit, enforcing it with hard constraints, and designing your application around it produces software that is honest about its own state.

Related: Natural Aristoi — the philosophy behind the design decisions in this package.

Natural Aristoi

Mike Georgeff — Wed, 03 Jun 2026 05:08:40 +0000

Frameworks should earn their place in your application through demonstrated merit -- not convention, not network effect, not being the path of least resistance.

The Concept

Natural Aristoi is a concept championed by Thomas Jefferson describing a governing class defined by virtue and talent, not birth or privilege. Jefferson believed in small government, states' rights over federal, power closest to the people it governs -- local, visible, accountable. Distrust of centralized authority that accumulates complexity, imposes its will and becomes impossible to remove once entrenched.

Small codebase. Components over monolith. Architecture closest to the problem it solves -- visible, intentional, accountable in its behavior. Distrust of the monolithic framework that grows, mandates, and makes decisions on your behalf whether you asked it or not.

The Problem with Full Frameworks

Frameworks force an all-or-nothing decision. Opinions are baked into every layer. This leads to abstractions that you did not ask for that hide what is actually happening. When your needs diverge, you're fighting the framework instead of engineering the solution.

Ultimately engineering comes in second, the framework's conventions come first.

The Composability Alternative

Compose only what your application needs -- nothing more, nothing less. Each component earns its place by doing precisely one thing. Shared standards serve as the contract layer -- components speak to each other through interfaces, not implementations. In PHP, PSR standards serve this exact role -- defining interfaces that components agree on without mandating how any of them are implemented. The result is small, purposeful, replaceable pieces that assemble into something cohesive.

The engineer decides the architecture, not the framework.

Principles

Define hard boundaries -- boot is boot, run is run, this should be enforced, not suggested.
Immutability as a constraint -- the service layer freezes at boot, making predictability a guarantee.
Explicit over implicit -- dependencies are declared, not located; registration is separated from resolution.
Pure transformation -- the system transforms inputs, it does not reconfigure itself.
Restraint as a signal -- 165 lines for a DI container, because that's all it needs to be.

Why this Matters

Applications built this way are predictable, testable, and honest about their own state. Implementation changes do not cause a snowball effect, they are centralized and isolated. Good software earns its place, flawed software is easily removed.

Engineers who understand their stack make better decisions.

DEV Community: Mike Georgeff