README

Overview

liquidrazor/event-manager is a PHP 8.3 library for deterministic event infrastructure.

It provides:

• immutable event contracts
• kernel-state and process event family markers
• lockable event registries
• strict event validation and classification
• synchronous listener dispatch
• loader primitives for externally discovered classes

It does not provide:

• concrete kernel lifecycle events
• concrete process event catalogs
• filesystem scanning
• async or distributed event delivery
• framework-specific wiring

The package is designed to work alongside discovery tools such as liquidrazor/file-locator and liquidrazor/class-locator, while keeping event semantics outside this repository.

Documentation

• Overview
• Architecture
• Core Concepts
• Registry
• Dispatch
• Loading
• Validation
• Testing

Key Guarantees

• Concrete events must implement exactly one supported family: KernelStateEventInterface or ProcessEventInterface.
• Dispatch is synchronous and deterministic: listeners are ordered by priority, then by registration sequence.
• Registries are family-specific and lockable, and the process registry advertises additive-only behavior.
• Discovery remains external; this package validates and loads discovered metadata but does not scan the filesystem.

Implementation Notes

• StrictEventValidator performs both event family resolution and validation.
• DiscoveredEventLoader routes validated DiscoveredClass metadata into the correct registry.
• KernelEventRegistry and ProcessEventRegistry enforce family segregation, duplicate protection, and lock checks.
• OrderedListenerProvider and SynchronousEventDispatcher provide explicit, in-process listener execution.

Registry phase timing is architectural policy, not automatic runtime behavior in this package. The code provides locking primitives; the integrating application decides when registries are locked.