75 lines
3.2 KiB
Markdown
75 lines
3.2 KiB
Markdown
|
# 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`.
|