Event Laravel Package

Getting Started

Start by installing the package via Composer:

composer require league/event

Since it implements PSR-14 (psr/event-dispatcher), you’ll use it via an event dispatcher. First, instantiate an Emitter (the package’s main class), then attach listeners and dispatch events:

use League\Event\Emitter;

$emitter = new Emitter();

$emitter->addListener('user.registered', function ($event) {
    echo "User {$event->getName()} registered!";
});

$emitter->emit(new UserRegisteredEvent('Alice'));

The simplest first use case is decoupling domain logic—e.g., sending a welcome email when a user registers—by attaching side-effect listeners without hard dependencies.

Implementation Patterns

• Domain-Centric Events: Use value-object events (UserRegisteredEvent, OrderShippedEvent) to represent domain happenings. Keep them immutable and stateful (with getters like getUser()).
• PSR-14 Compliance: Leverage the Emitter as a drop-in replacement for any PSR-14 dispatcher (e.g., Symfony’s or Laravel’s EventDispatcher replacements). Integrate with frameworks by injecting Emitter as the dispatcher implementation.
• Listener Priorities: Attach listeners with priorities to control order (higher = runs first):

  $emitter->addListener('user.registered', $handler, 100); // high priority
  $emitter->addListener('user.registered', $logger, -10); // low priority
  

• Wildcard Listeners: Use * in listener names to match multiple events (e.g., user.*), useful for logging or auditing.
• Middleware Pattern: Wrap listeners with custom logic (e.g., exception handling) using Emitter::pipe() for cross-cutting concerns.

Gotchas and Tips

• No Event Cancellation: Unlike some event systems, league/event does not support stopPropagation() or cancellation—listeners always run (though exceptions may halt flow). Design around this by using exceptions for truly exceptional cases, not flow control.
• Event Name Consistency: Use namespacing (e.g., App\Events\User.Registered) to avoid collisions. Consider naming events in past tense (user.created, not user.create).
• Tight Coupling via Strings: Event names are string-based—refactor carefully. Consider defining constants (e.g., class UserEvents { const REGISTERED = 'user.registered'; }) to avoid typos.
• Testing Tip: The Emitter is easy to mock or spy on in tests. For integration tests, attach a mock listener that captures emitted events to assert side effects occurred.
• Extensibility: Extend Emitter to add domain-specific behavior (e.g., a TransactionalEmitter that only emits events after a DB transaction commits).
• Performance: For high-throughput systems, be cautious with wildcard listeners—they’re powerful but can become expensive if overused. Prefer explicit event names in hot paths.