README

liquidrazor/kernel-state-events is a provider-only PHP library that supplies the concrete immutable kernel lifecycle event implementations used by the LiquidRazor Framework.

It provides implementations only. Event contracts, event taxonomy, and event infrastructure remain owned by liquidrazor/event-manager.

Documentation

• Lifecycle Reference

What This Package Is

• A library of concrete immutable kernel lifecycle event classes
• A small supporting model around those events
• KernelState enum
• KernelIdentity value object
• A provider package that implements EventManager contracts without redefining them

What This Package Is Not

This repository does not:

• declare event contracts
• define event taxonomy
• dispatch events
• register listeners
• provide request, response, child, worker, or other process/runtime events
• provide plugin or application event extension systems

If you need event contracts or dispatching, use liquidrazor/event-manager. If you need runtime or process events, they belong in a separate package, not here.

Contract Ownership

All event contracts are imported from liquidrazor/event-manager.

This includes:

• LiquidRazor\EventManager\Contracts\KernelStateEventInterface
• LiquidRazor\EventManager\Contracts\ImmutableEventInterface

This package does not declare local replacements or wrapper contracts. EventManager owns contracts and taxonomy; KernelStateEvents provides the concrete kernel lifecycle implementations only.

Canonical Lifecycle

The kernel lifecycle represented by this package is intentionally explicit:

Booting -> Booted -> Compiling -> Compiled -> ContainerLoading -> ContainerLoaded -> Warming -> Warmed -> Ready -> ShuttingDown -> Shutdown

Compile, container load, and warm are distinct lifecycle phases. That separation is architectural and must not be collapsed into one vague startup state.

Canonical Event Catalog

This package provides exactly these concrete events:

• KernelBootingEvent
• KernelBootedEvent
• KernelCompilingEvent
• KernelCompiledEvent
• KernelContainerLoadingEvent
• KernelContainerLoadedEvent
• KernelWarmingEvent
• KernelWarmedEvent
• KernelReadyEvent
• KernelShuttingDownEvent
• KernelShutdownEvent

See the Lifecycle Reference for the full class-to-state mapping and phase semantics.

Public Package Surface

Concrete events live under LiquidRazor\KernelStateEvents\Event\*.

Supporting types:

• LiquidRazor\KernelStateEvents\Enum\KernelState
• LiquidRazor\KernelStateEvents\Value\KernelIdentity

Each concrete event currently accepts a KernelIdentity in its constructor and exposes:

• kernelIdentity(): KernelIdentity
• state(): KernelState

LiquidRazor\KernelStateEvents\Internal\Event\AbstractKernelStateEvent exists as shared implementation logic in the internal namespace. It is not the package's contract layer.

Project Structure

The repository follows the standard LiquidRazor library layout:

include/
  Enum/
  Value/

lib/
  Event/

src/
  Event/

Responsibilities:

• include/ contains public supporting definitions owned by this package
• lib/ contains reusable implementation logic
• src/ contains concrete event implementations

Dependency direction remains:

include <- lib <- src

No event contracts are defined in any of these directories.

Installation

Requirements:

• PHP 8.3+
• liquidrazor/event-manager ^0.1

Install with Composer:

composer require liquidrazor/kernel-state-events:^0.1

Minimal Usage

<?php

declare(strict_types=1);

use LiquidRazor\KernelStateEvents\Event\KernelBootingEvent;
use LiquidRazor\KernelStateEvents\Value\KernelIdentity;

$event = new KernelBootingEvent(new KernelIdentity('kernel.main'));

$event->kernelIdentity(); // KernelIdentity('kernel.main')
$event->state(); // KernelState::Booting

Dispatching, listener registration, and event classification are handled outside this package by liquidrazor/event-manager and the integrating framework code.

Scope Boundary

This package is intentionally small. It should stay limited to concrete immutable kernel lifecycle events and the minimal support types required to implement them.