Beacon Specification (SPECS)

Overview

Beacon is a high-performance, PSR-14 compliant event management system. It is designed to be decoupled, utilizing BeaconContracts for interfaces and providing an enterprise-grade engine with middleware support, attribute-based discovery, and telemetry.

1. Core Interfaces (BeaconContracts)

The foundation of Beacon must be defined in getphred/beacon-contracts.

EventDispatcherInterface: Extends Psr\EventDispatcher\EventDispatcherInterface.
ListenerProviderInterface: Extends Psr\EventDispatcher\ListenerProviderInterface.
SubscriberInterface: Defines getSubscribedEvents(): array.
StoppableEventInterface: Extends Psr\EventDispatcher\StoppableEventInterface.
DispatchMiddlewareInterface: Defines handle(object $event, callable $next): object.

2. Event Dispatcher (The Engine)

The primary implementation of the dispatcher.

PSR-14 Compliance: Must correctly handle event objects and return them.
Middleware Support: Implements an "Onion" style pipeline.
- Global middleware can intercept every dispatch.
- Middleware can modify the event or stop propagation.
Resiliency Modes:
- FAIL_FAST: Stops execution on the first listener exception.
- CONTINUE: Logs the error, dispatches a DispatchFailed internal event, and moves to the next listener.
Telemetry: Internal tracking of listener execution time and memory usage.

3. Listener Provider & Resolution

The logic for finding who cares about an event.

Priority Handling: Listeners are sorted by priority (higher integer runs first).
Inheritance Resolution:
- Automatically resolves listeners for the event class, its parents, and its interfaces.
- Must include a performance toggle to disable interface scanning.
Wildcard Support:
- Support dot-notation wildcards (e.g., user.*, *.created).
- Pattern matching converted to optimized regex with internal caching.
Lazy Loading: Integration with a PSR-11 container to instantiate listeners only when they are about to be called.

4. Discovery & Registration

Mechanisms to register listeners without manual configuration.

Attribute Discovery:
- Support #[AsEventListener(event: string, priority: int)].
- Support #[AsSubscriber].
Listener Discovery Service:
- Scans directories for classes with Beacon attributes.
- Integrates with PSR-16 cache to avoid scanning on every request.
Manual Registration:
- addListener(string $event, callable $listener, int $priority = 0)
- addSubscriber(SubscriberInterface $subscriber)

5. Event Objects & Context

Enhancing the standard event pattern.

Event Envelope:
- A wrapper to carry immutable metadata (e.g., request_id, user_id, timestamp).
- Uses a ContextMap for type-safe metadata access.
Stoppable Trait: Provide CanStopPropagation trait for easy implementation of StoppableEventInterface.

6. Testing Utilities

EventCollector: A listener that gathers all dispatched events for assertions.
PHPUnit Assertions: Traits for assertEventDispatched, assertEventNotDispatched, and assertListenerCalled.

3.2 KiB Raw Blame History