League Event Laravel Package

Getting Started

Begin by installing the package via Composer (composer require spiral-packages/league-event) and enabling the provider in app/src/Kernel.php (typically via Spiral\Packages\Event\EventBootloader). Once registered, the dispatcher is available in the DI container as League\Event\EventDispatcherInterface. Your first use case is dispatching a simple domain event (e.g., UserRegistered) and wiring up a listener to send a welcome email — no manual handler instantiation needed.

Implementation Patterns

• Listener Registration: Use attribute-based auto-discovery via #[Listener] on handler methods or configure listeners in config/event.php (e.g., mapping event classes to handler services).
• Event Classes: Define immutable event objects (e.g., class OrderShipped { public $orderId; }); type-hint the event in listener signatures for strict binding.
• Dispatching: Inject EventDispatcherInterface into services/controllers and call $dispatcher->dispatch(new UserRegistered($user));.
• Middleware Integration: Use event listeners to decouple cross-cutting concerns (e.g., logging, metrics) from controller logic.
• Testing: Mock EventDispatcherInterface or assert dispatched events using event collectors in unit tests.

Gotchas and Tips

• Listener Resolution: Ensure handlers are registered as services in the container (e.g., via Spiral\Core\Interceptor\InterceptorInterface support) — class names alone won’t be resolved automatically.
• Event Name Conflicts: League\Event uses fully-qualified class names (FQCN) as event identifiers — avoid duplicate event class names across namespaces to prevent unintended listener triggering.
• Middleware/Filter Hooks: If leveraging the FilterEvent or ListenerFilter, remember to register filters before listeners in config to avoid early termination.
• Performance Tip: For high-volume event streams, prefer named listeners over class-string-based listeners for minor performance gains, and consider batching events where appropriate.
• Debugging: Enable Spiral’s debug mode to trace dispatched events in the toolbar; inspect the event section in /debug for listener chain execution.
• Legacy Hook: The package doesn’t auto-register Symfony-style event names — always rely on FQCN to match events to listeners.