Weave Code
Event Dispatcher Contracts Laravel Package
symfony/event-dispatcher-contracts
A small set of PHP interfaces that abstract Symfony's event dispatcher, letting you build on proven event semantics and swap implementations without locking your code to a specific package.
Generic abstractions related to dispatching event
Frequently asked questions about Event Dispatcher Contracts
- What is symfony/event-dispatcher-contracts and why would a Laravel project need it?
- It is an interfaces-and-traits-only package that ships PSR-14 style abstractions: EventDispatcherInterface, Event, StoppableEventInterface, and ListenerProviderInterface. It contains no dispatching implementation of its own. Laravel apps typically need it only when domain events must be shared with Symfony services, CLI tools, or an SDK published to multiple frameworks. For a single-framework CRUD application it is over-abstraction.
- How do I install symfony/event-dispatcher-contracts with Composer?
- Run composer require symfony/event-dispatcher-contracts. It is very often already present transitively through Symfony components, so check composer show before declaring it as a direct dependency. The package requires PHP 8.1 or newer, so confirm your runtime floor first. Verify the released version on Packagist before pinning it in your lockfile.
- Is symfony/event-dispatcher-contracts compatible with Laravel 10, 11 and 12?
- Yes. The package is plain PHP interfaces with a PHP 8.1+ floor, which lines up with Laravel 10, 11, and 12. There is no service provider, config file, or registration step to worry about. Any compatibility problems will come from the adapter or bridge you build, not from the contracts themselves.
- Does installing this package make Laravel's event dispatcher PSR-14 compliant?
- No. Illuminate\Contracts\Events\Dispatcher uses a different dispatch() signature and return value, registers listeners through EventServiceProvider instead of a ListenerProvider, and does not handle StoppableEventInterface. The contracts give you a shared vocabulary, not interoperability on their own. Real PSR-14 dispatching requires a bridge such as spatie/laravel-psr-event-dispatcher or a custom adapter you own.
- Can I dispatch Symfony Event objects with Laravel's event() helper or Event::dispatch?
- Yes. Events that extend Symfony\Contracts\EventDispatcher\Event are ordinary PHP objects, so Laravel can dispatch them unchanged. In practice the change is a type-hint migration with no runtime delta. What you do not get automatically is PSR-14 listener semantics on the consuming side.
- Will Event::fake() still work if my events implement the Symfony event contract?
- Event::fake() only observes Laravel's dispatcher, so it works as long as the events still travel through Laravel. If they are routed through a separate PSR-14 dispatcher instead, faked assertions will not see them. That produces the classic green tests with silently skipped listeners problem, so keep dispatching through Laravel in tests or assert against your adapter directly.
- What Laravel features are lost if I replace its dispatcher with a PSR-14 one?
- Queued listeners via ShouldQueue, ShouldBroadcast, wildcard listeners, model events, and Event::fake() assertions all sit outside the PSR-14 contract. Swapping the dispatcher therefore silently removes capabilities teams depend on. Model events in particular are not covered by this contract at all. Keep Laravel's dispatcher as the runtime transport and treat PSR-14 as an optional ingress path.
- How do I bridge PSR-14 dispatch to Laravel's dispatcher?
- Use an existing bridge such as spatie/laravel-psr-event-dispatcher, or write a small adapter that maps PSR-14 dispatch() onto Laravel's dispatcher. Treat that bridge as code you own and maintain, because Laravel core has no commitment to PSR-14 dispatching. Also watch for listener signature drift between Laravel's handle($event) style and PSR-14 __invoke($event) callables.
- Why does symfony/event-dispatcher-contracts show zero dependents, and is it still maintained?
- The dependents count is unreliable metadata, not a signal of low adoption. The package is overwhelmingly consumed transitively through Symfony components rather than declared directly in composer.json files. It is maintained as part of the Symfony contracts monorepo. Confirm release dates and versions on Packagist before relying on them in a lockfile.
- When should I avoid this package, and what are the alternatives?
- Skip it for a single-framework Laravel CRUD app where nothing outside Laravel consumes the events; plain Laravel events and Illuminate contracts are simpler. Adopt it when you have a concrete second consumer, such as a Symfony service, CLI tool, or multi-framework SDK, and validate interoperability against that consumer in a pilot. Alternatives include full PSR-14 implementations or Symfony's complete event-dispatcher component if you also need a runtime dispatcher.
Weaver
How can I help you explore Laravel packages today?