Events Laravel Package

Getting Started

This package provides a PSR-14-compliant event dispatcher for Spiral Framework applications. Begin by installing via Composer (composer require spiral/events) and enabling the Spiral\Events\Events bootstrapper in your app’s bootstrap chain (typically via app.php config). The first use case is dispatching domain events—e.g., after a user registers—by creating an event class (e.g., UserRegistered) and calling $dispatcher->dispatch(new UserRegistered($user)).

Implementation Patterns

• Event Classes: Define simple DTOs (e.g., class UserRegistered { public function __construct(public User $user) {} }). Use typed properties and avoid business logic in events.
• Event Listeners: Implement __invoke() methods (recommended) or handle() in listener classes, or use closures in newer PHP versions.
• Listener Registration: Register listeners via config/bootloaders.php (Spiral-specific) or bind them in App::boot() using Events::listen(new UserRegistered, UserRegisteredListener::class).
• Bulk Dispatching: Prefer dispatching a single event with multiple listeners over manual loops; this decouples concerns and improves testability.

Gotchas and Tips

• Listening Order: Listeners are executed in registration order unless you implement Spiral\Events\ListenerPriorityInterface—use getPriority() to control execution sequence.
• Circular Dependencies: Avoid dispatching new events from listeners if the listener itself may be triggered by that new event (causing recursion or infinite loops).
• Testing: Mock EventDispatcherInterface or use TestingEventDispatcher in unit tests; Spiral’s TestCase includes helper methods for event assertions.
• Framework Integration: When using Spiral’s Bootloader pattern, override boot() to register listeners programmatically instead of relying solely on config files.
• Performance: Avoid heavy work in listeners for high-frequency events; consider queuing (e.g., with spiral/jobs) for non-critical tasks to keep dispatch latency low.