Event Laravel Package

Getting Started

Install the package via Composer: composer require joomla/event "~3.0". Begin by creating a simple Dispatcher and registering a closure listener for an event like 'onUserLogin'. Dispatch the event and verify your listener executes. This minimal flow—dispatcher → listener → dispatch—demonstrates the core pattern. Start with docs/overview.md and the “Creating a Decorated Dispatcher” example for hands-on learning.

Implementation Patterns

• Event-driven architecture: Use the Dispatcher as a central bus in service containers or application kernels. Register subscribers (classes implementing SubscriberInterface) to decouple concerns (e.g., logging, caching, validation).
• Model/Service integration: Use DispatcherAwareTrait in domain models (e.g., UserModel, OrderService) to inject a dispatcher and dispatch onBefore{Action} and onAfter{Action} events transparently.
• Priority-based ordering: Leverage Priority::EARLY, HIGH, NORMAL, ABOVE_NORMAL, etc., to control execution order—e.g., security checks (HIGH) before UI rendering (NORMAL).
• Lazy loading for heavy services: Wrap expensive listeners in LazyServiceEventListener to defer instantiation until dispatch time, especially useful for listeners depending on DI containers or services with circular dependencies.

Gotchas and Tips

• Mutable vs. immutable events: Avoid accidental mutations—use EventImmutable for events whose arguments should be read-only by listeners (common in audit or validation scenarios).
• Subscriber method signatures: Ensure all subscriber methods accept exactly one EventInterface argument. PHP will throw a TypeError if the signature doesn’t match.
• triggerEvent() deprecation: Though still present in Dispatcher, use dispatch()—the legacy method is deprecated and removed in future versions.
• Listener removal pitfalls: removeListener() requires an exact match of listener (e.g., [$subscriber, 'method'] or closure identity). If you registered a closure inline, keep a reference to remove it later.
• Priority ambiguity: Listeners with identical priority execute in registration order. For reproducible behavior, explicitly set priorities instead of relying on defaults.
• Testing tip: Inject a mock DispatcherInterface into classes using DispatcherAwareTrait to isolate event behavior in unit tests.