Introduce lifecycle hooks across boot, web runtime, console runtime, routing, and response flow

[armanist]

Summary

Introduce a defined lifecycle hook surface across framework execution, built on top of the enhanced Hook/Event mechanism and the staged runtime structure introduced for boot and adapter runtime pipelines.

This ticket should establish the actual lifecycle contract that Quantum exposes for:

• boot
• web runtime
• console runtime
• route dispatch
• response flow

Why

The prerequisite work provides the mechanism and structure:

• #536 strengthens the Hook/Event foundation and bootstrap-time registration model
• #537 introduces structured runtime pipelines for WebAppAdapter::start() and ConsoleAppAdapter::start()

This ticket should define where lifecycle hooks are emitted and which execution boundaries become part of the framework contract.

Goal

Define and wire the framework lifecycle hooks at meaningful execution boundaries, using the new staged boot/runtime structure rather than ad hoc method-level dispatch.

This ticket should establish which lifecycle points are officially exposed and where they are emitted.

Scope

This ticket should cover lifecycle hook points for:

• boot stage boundaries
• web runtime stage boundaries
• console runtime stage boundaries
• route dispatch boundaries
• response send boundaries

It should not yet handle debugbar specifically. Debugbar integration should be implemented in a follow-up ticket once the lifecycle surface exists.

Proposed Direction

Boot lifecycle

Use stage-owned BEFORE / AFTER hook points for boot stages and dispatch them through the boot pipeline.

Web runtime lifecycle

Use stage-owned BEFORE / AFTER hook points for the new web runtime pipeline introduced in #537.

This should expose lifecycle points around stages such as:

• preflight handling
• route resolution
• route-not-found handling
• request preparation
• request dispatch
• response sending
• request cleanup

Console runtime lifecycle

Use stage-owned BEFORE / AFTER hook points for the new console runtime pipeline introduced in #537.

This should expose lifecycle points around stages such as:

• core command registration
• app command registration
• command validation
• command execution

Route lifecycle

Add route-specific lifecycle hooks at the route dispatch layer, separate from pipeline stages.

This should cover meaningful boundaries such as:

• before route dispatch
• after route dispatch

Response lifecycle

Add response-specific lifecycle hooks around response sending.

This should cover meaningful boundaries such as:

• before response send
• after response send

Example Direction

Boot stage example:

final class LoadModulesStage implements BootStageInterface
{
    public const BEFORE = 'boot.modules.before';
    public const AFTER = 'boot.modules.after';

    public function process(AppContext $context): void
    {
        // existing logic
    }
}

Runtime stage example:

final class DispatchRequestStage implements RequestStageInterface
{
    public const BEFORE = 'web.dispatch.before';
    public const AFTER = 'web.dispatch.after';

    public function process(RequestContext $context): void
    {
        // cached response lookup, route dispatch, middleware execution
    }
}

Route lifecycle example:

event()->dispatch('route.dispatch.before', [
    'request' => $request,
    'matchedRoute' => $matched,
]);

$response = // existing dispatch logic

event()->dispatch('route.dispatch.after', [
    'request' => $request,
    'matchedRoute' => $matched,
    'response' => $response,
]);

Response lifecycle example:

event()->dispatch('response.send.before', [
    'request' => request(),
    'response' => $response,
]);

$response->send();

event()->dispatch('response.send.after', [
    'request' => request(),
    'response' => $response,
]);

Listener example:

event()->listen(DispatchRequestStage::AFTER, function (array $payload): void {
    $context = $payload['context'];
    // integration logic
});

Architectural Constraint

The lifecycle model introduced here must remain extensible for future event sources beyond the initial staged flow, including:

• request/response extensions
• route-level extensions
• console-level extensions
• user-defined business/domain events

The lifecycle contract should build on the staged structure, but must not be limited to stage-only use cases forever.

Acceptance Criteria

• boot lifecycle hooks are defined and dispatched through boot stages
• web runtime lifecycle hooks are defined and dispatched through runtime stages
• console runtime lifecycle hooks are defined and dispatched through runtime stages
• route lifecycle hooks are defined at the route dispatch layer
• response lifecycle hooks are defined around response sending
• lifecycle hook semantics are documented clearly enough for framework integrations and application code to rely on them
• debugbar-specific behavior is not hardcoded as part of this ticket
• tests cover lifecycle dispatch across boot, web runtime, console runtime, routing, and response flow

Notes

Relevant code:

• src/App/BootPipeline.php
• src/App/Adapters/WebAppAdapter.php
• src/App/Adapters/ConsoleAppAdapter.php
• src/App/Traits/WebAppTrait.php
• src/Router/RouteDispatcher.php
• src/Middleware/MiddlewareManager.php

Depends on:

• #536
• #537