Download the PHP package fast-forward/event-dispatcher without Composer

Fast Forward Event Dispatcher

A lightweight PSR-14 event dispatcher for PHP 8.3+ with named events, Symfony-style subscribers, attribute-based listeners, and first-class integration with the Fast Forward container.

✨ Features

• 🚀 PSR-14 dispatcher with support for Symfony\Contracts\EventDispatcher\EventDispatcherInterface
• 🏷️ Named events via dispatch($event, $eventName) and the NamedEvent wrapper
• 🔌 Automatic listener classification inside Fast Forward applications
• 🧩 Support for invokable listeners, Symfony subscribers, attributes, and custom listener providers
• 📊 Priority-aware execution for subscribers and #[AsEventListener]
• 🛑 Propagation control through StoppableEventInterface, the Event base class, and StoppableEventTrait
• 🧯 Error instrumentation through ErrorEvent and LogErrorEventListener
• 🌐 Wildcard listener providers for cross-cutting observers such as logging, metrics, and audit trails
• 🪶 Small surface area with practical defaults and clear extension points

📦 Installation

Install the package with Composer:

Requirements:

• PHP ^8.3
• psr/event-dispatcher
• psr/container
• psr/log
• fast-forward/container

If you want to register Symfony-style subscribers or use #[AsEventListener], also install:

🛠️ Usage

1. Dispatch a typed PSR-14 event

The Fast Forward service provider wires the dispatcher and classifies configured listeners by strategy.

Output:

2. Dispatch the same event with an explicit name

Use a named dispatch when you want string-based routing in addition to the event class itself.

3. Use priorities with #[AsEventListener]

Attribute-based listeners are detected and routed to a priority-aware provider automatically.

4. Observe listener failures with ErrorEvent

When a listener throws, the dispatcher emits an ErrorEvent and then rethrows the original exception. This gives you a clean place to log, trace, or notify without swallowing the failure.

5. Log every dispatched object with a wildcard listener provider

WildcardListenerProvider is a small base class for providers that should observe every dispatched object. LogEventListenerProvider builds on it and sends each dispatch to a PSR-3 logger, including NamedEvent wrappers produced by named dispatch.

Output:

See examples/06-log-all-events.php for the runnable version.

6. Understand the dispatch flow

For each dispatched object, the library follows this sequence:

1. Resolve listeners for the original event object.
2. Invoke listeners until propagation stops or a listener throws.
3. If the event is not already a NamedEvent, dispatch a named wrapper using the explicit name or the event class.
4. If a listener throws, emit ErrorEvent.
5. Rethrow the original throwable after error listeners have been notified.

🧰 API Summary

🔌 Integration

This package fits well in two modes:

• Fast Forward mode: register EventDispatcherServiceProvider::class and declare listeners in ListenerProviderInterface::class.
• Standalone mode: instantiate EventDispatcher manually with any Psr\EventDispatcher\ListenerProviderInterface.

Out of the box, the Fast Forward integration understands these listener styles:

• Invokable listeners and callable listeners resolved by reflection
• #[AsEventListener] classes and public methods
• Symfony EventSubscriberInterface subscribers
• Custom listener providers implementing ListenerProviderInterface, including wildcard providers such as LogEventListenerProvider

📊 Listener Registration Styles

📁 Directory Structure Example

⚙️ Advanced and Customization

Mix listener strategies in one configuration

The service provider classifies each configured item and routes it to the matching provider. That means you can combine plain callables, attributed listeners, subscribers, and custom providers in the same app.

Create stoppable domain events

Build wildcard observers

When you need one listener-provider to observe every dispatched object, extend ListenerProvider\WildcardListenerProvider. This is useful for logging, metrics, auditing, and other cross-cutting concerns that should not depend on one event class.

Choose between Event and StoppableEventTrait

Use FastForward\EventDispatcher\Event\Event when you want a generic base class compatible with Symfony's event contract and you are fine with a public stopPropagation() method.

Use Event\StoppableEventTrait when you need the same stoppable behavior but your event already extends another class and cannot inherit from Event.

Log failures without hiding them

LogErrorEventListener is intentionally observational. It helps you record failures, but the dispatcher still rethrows the original exception so your application can fail fast when it should.

🛠️ Versioning and Breaking Changes

• The Composer branch alias is currently 1.x-dev.
• The package targets modern PHP 8.3+.
• No public breaking-change matrix is documented yet; review release notes and changelog entries as the package evolves.

❓ FAQ

Do I need the Fast Forward container to use this package?

No. The core EventDispatcher only needs a PSR-14 ListenerProviderInterface. The Fast Forward service provider is the convenience layer that makes configuration and listener discovery ergonomic.

When should I use named events?

Use named events when your application already relies on string-based event identifiers, or when you want to expose a stable semantic name that is different from the PHP class name.

Do Symfony subscribers and attributes work out of the box?

They work with this package, but they rely on Symfony's event-dispatcher component types. If your project does not already include them, add symfony/event-dispatcher.

What happens if a listener throws an exception?

The dispatcher emits ErrorEvent, gives your error listeners a chance to observe the failure, and then rethrows the original exception.

How do I log every dispatched event?

Register LogEventListenerProvider or create your own subclass of WildcardListenerProvider. Wildcard providers receive the original event object and the generated NamedEvent wrapper when named dispatch is used.

🛡️ License

This library is released under the MIT License.

Copyright (c) 2025-2026 Felipe Sayão Lobato Abreu.

🤝 Contributing

Contributions, issues, and pull requests are welcome.

Useful local commands:

When changing behavior, keep the examples and this README in sync with the code.

🔗 Links

• Repository
• Issues
• Packagist
• PSR-14: Event Dispatcher
• PSR-3: Logger Interface
• Symfony Event Subscribers
• Examples directory