Event Dispatcher Contracts Laravel Package

Getting Started

Start by installing the package via Composer: composer require symfony/event-dispatcher-contracts. This package itself provides only interfaces—no concrete implementation—so it’s meant to be used alongside an actual event dispatcher (e.g., symfony/event-dispatcher, Laravel’s Illuminate\Events\Dispatcher, or PSR-14 compliant ones like league/event).

The first real use case is to define events as value objects implementing Symfony\Contracts\EventDispatcher\Event. In Laravel, you might define an event like this:

use Symfony\Contracts\EventDispatcher\Event;

class UserRegistered extends Event
{
    public function __construct(public User $user) {}
}

Then dispatch it using Laravel’s event() helper or Symfony’s dispatcher—this contract ensures your event classes stay decoupled from the underlying dispatcher implementation.

Implementation Patterns

• Decoupled Event Definitions: Use Event as the base class for domain-specific events. This keeps event classes reusable across frameworks (e.g., same events in a Laravel app and a standalone CLI tool using Symfony dispatcher).
• Named Events (Optional): While not required by the contract, you can optionally implement getEventName() to return a string identifier—useful for debugging or custom dispatchers.
• Event Names as Constants: Define event names as class constants (public const NAME = 'user.registered') to avoid typos and support IDE autocompletion.
• Laravel Integration: Laravel’s Event class already extends Symfony’s Event, so you can start using contracts-based events immediately. To enforce the pattern, update EventServiceProvider to type-hint Symfony\Contracts\EventDispatcher\Event where appropriate.
• PSR-14 Compatibility: Since this package depends on psr/event-dispatcher, your events also satisfy PSR-14 EventInterface, enabling compatibility with PSR-14 dispatchers (e.g., via symfony/event-dispatcher’s PSR adapter).

Gotchas and Tips

• Not a Standalone Package: This package only provides interfaces—no dispatcher logic. Confusion arises when expecting to use it alone. Always pair with a concrete implementation (e.g., symfony/event-dispatcher for Symfony apps, Laravel’s built-in dispatcher).
• No eventName() by Default: The contract does not require an eventName() method. Laravel’s Event adds this automatically, but custom implementations must define it if needed for manual event registration.
• PHP 8.1+ Required: The package requires PHP 8.1+ due to its use of readonly properties and other modern features—ensure your project meets this.
• Extension Points: The Event class is intentionally minimal (just a name property internally). Want to add metadata? Extend it—but avoid overriding core behavior to preserve interoperability.
• Debugging Tip: When events don’t fire, check if your dispatcher is configured with the correct event-to-listener mapping—symfony/var-dumper can help inspect event objects mid-dispatch.
• Avoid Over-Abstraction: Don’t force events into this contract for trivial cases (e.g., simple hooks in small apps). Reserve it for domain events where decoupling, testability, or cross-framework reuse matters.