symfony/event-dispatcher

symfony/event-dispatcher provides tools that let application components communicate by dispatching named events and registering listeners or subscribers to react to them, implementing the Mediator and Observer design patterns for PHP. It’s a foundational Symfony component used both standalone and as the backbone of the full Symfony framework’s extension points.

The component supports prioritized listeners, event subscribers (classes that declare which events they listen to), a traceable/debug dispatcher for profiling, and PSR-14 (psr/event-dispatcher-implementation) compatibility, making it interoperable with other PSR-14-compliant PHP packages.

What You Get

• EventDispatcher and EventDispatcherInterface for dispatching named events to registered listeners
• EventSubscriberInterface for declaring which events a class listens to, plus their priority, without manual registration calls
• ImmutableEventDispatcher, a read-only wrapper preventing runtime listener modification once configured
• Debug\TraceableEventDispatcher and WrappedListener for profiling listener execution time inside the Symfony framework/profiler
• PSR-14 (psr/event-dispatcher-implementation) compatibility for interoperability with other PSR-14 PHP packages

Common Use Cases

• Decoupling business logic in a Symfony application by dispatching domain events (e.g. OrderPlaced) instead of direct method calls
• Adding cross-cutting concerns (logging, caching invalidation, notifications) as event listeners without modifying core application code
• Extending third-party bundles/plugins by subscribing to their published events
• Building a plugin or extension architecture in any PHP application, framework-independent, via the standalone component

Under The Hood

Architecture — The core EventDispatcher.php (256 lines) maintains a priority-ordered listener registry keyed by event name and implements dispatch(), addListener(), addSubscriber(), and related methods against the EventDispatcherInterface (66 lines) contract. ImmutableEventDispatcher.php wraps an existing dispatcher to forbid further listener registration at runtime, and Debug/TraceableEventDispatcher.php + Debug/WrappedListener.php instrument dispatch calls for the Symfony Profiler. DependencyInjection/RegisterListenersPass.php and AddEventAliasesPass.php are Symfony DI compiler passes that auto-wire tagged services as listeners/subscribers when used inside the full framework, while the component itself has zero required framework dependency beyond symfony/event-dispatcher-contracts.

Tech Stack — Pure PHP 8.4+, PSR-4 autoloaded under the Symfony\Component\EventDispatcher namespace. It is one of Symfony’s independently versioned, independently installable components (read-only GitHub mirror split from the symfony/symfony monorepo via Symfony’s splitsh tooling), with dev-only dependencies on other Symfony components (config, dependency-injection, http-foundation, etc.) used solely for integration testing.

Code Quality — The Tests/ directory contains 12 PHP test files covering the dispatcher, subscribers, immutable wrapper, and debug/traceable variants, run via PHPUnit (phpunit.xml.dist). A maintained CHANGELOG.md tracks behavioral changes release over release, and the component has shipped over 100 tagged releases with continuous point releases across the 4.4 through 8.1 major/minor lines through mid-2026, reflecting Symfony’s strict backward-compatibility and long-term support policy.

API Design — The dispatcher’s API is intentionally minimal — dispatch(), addListener(), addSubscriber(), getListeners() — with EventSubscriberInterface::getSubscribedEvents() offering a declarative alternative to manual registration that keeps listener wiring co-located with the class that implements it. Because the interface is PSR-14 compliant, code written against EventDispatcherInterface can swap in other PSR-14 implementations without modification, a deliberate interoperability design choice.