Event Dispatcher Contracts Laravel Package

Product Decisions This Supports

• Framework-Agnostic Event Architecture: Enables the development of event-driven systems that can operate seamlessly across Laravel, Symfony, and other PSR-14-compliant frameworks. This reduces technical debt and vendor lock-in, particularly for projects targeting multi-framework ecosystems (e.g., shared libraries, microservices, or CLI tools).
• Modular and Decoupled Design: Aligns with Domain-Driven Design (DDD) principles by treating domain events as reusable value objects, decoupled from dispatching logic. This enhances testability, mocking, and the ability to replace event dispatchers without affecting core business logic.
• Build vs. Buy Decision: Justifies a "build" approach for custom event systems where off-the-shelf solutions (e.g., Laravel’s native events) are insufficient. The package provides foundational contracts to avoid reinventing the wheel while allowing tailored implementations.
• Interoperability Use Cases:
  • Shared libraries used across Laravel and Symfony applications (e.g., a payment service emitting PaymentProcessed events).
  • CLI tools or background jobs that need to consume events from a Laravel app but dispatch events to a Symfony-based service bus.
  • Projects migrating between frameworks (e.g., from Symfony to Laravel or vice versa) where event compatibility is critical.
• Testing and Observability: Standardizes event structures across the codebase, enabling consistent serialization/deserialization for logging, analytics, or event stores.
• Future-Proofing: Prepares the system for adoption of PSR-14-compliant tools (e.g., event stores, message brokers) without rewriting event logic. Ensures compatibility with emerging PHP standards and frameworks.

When to Consider This Package

Adopt When:

• Your project requires cross-framework event compatibility (e.g., shared codebases, polyglot architectures).
• You’re building a library or SDK intended for use in multiple frameworks (Laravel, Symfony, Lumen, etc.).
• You need strict decoupling between event definitions and dispatching logic (e.g., for testability or plugin architectures).
• Your team prioritizes PSR standards and wants to align with modern PHP practices (e.g., PHP 8.1+ features like readonly properties).
• You’re designing a modular monolith or microservices ecosystem where events must traverse framework boundaries.
• You anticipate future migration to/from Symfony or other PSR-14-compliant systems.
• You’re integrating with third-party PSR-14-compliant tools (e.g., Symfony’s event dispatcher, message brokers, or event stores).

Look Elsewhere When:

• You’re building a pure Laravel application with no need for framework interoperability. Laravel’s native event system (Illuminate\Events) is sufficient and more idiomatic.
• Your team lacks bandwidth to maintain a PSR-14 bridge (e.g., laravel-psr-event-dispatcher) or implement custom adapters.
• You’re working with legacy PHP versions (<8.1), as the package requires modern PHP features.
• Events are simple or trivial (e.g., one-off hooks in a small app). Overhead of contracts may not justify benefits.
• Your stakeholders prefer minimal dependencies and view PSR-14 as unnecessary abstraction.
• Existing third-party Laravel packages already solve your event needs (e.g., Spatie’s event tools, Laravel’s built-in system).

How to Pitch It (Stakeholders)

For Executives/Business Leaders:

*"This package allows us to build event-driven systems that work seamlessly across different PHP frameworks—like Laravel and Symfony—without being locked into one. It’s like using a universal adapter for your app’s event plugs. This is particularly valuable if we’re:

• Scaling with shared libraries (e.g., a payment module used by both our web app and a CLI tool).
• Future-proofing for migrations or multi-framework integrations (e.g., adding a Symfony-based microservice later).
• Reducing technical debt by standardizing how events are defined and consumed across our ecosystem.

The trade-off is a slight upfront investment to align our event system with industry standards (PSR-14), but it pays off in flexibility and long-term maintainability. For example, if we ever need to swap out Laravel’s event system or integrate with a Symfony service, our core logic remains intact and portable."*

For Engineering Teams:

*"This package provides PSR-14 event contracts—a set of interfaces that define how events should work without prescribing a specific implementation. Here’s why it’s worth adopting:

• Decoupled Design: Event classes become framework-agnostic value objects. For example, a UserRegistered event can be dispatched in Laravel and consumed by a Symfony CLI tool.
• Interoperability: Enables seamless integration with PSR-14-compliant tools (e.g., Symfony’s dispatcher, message brokers, or event stores).
• Laravel-Friendly: Laravel’s Event class already extends Symfony’s Event, so we can start using contracts with minimal changes. We’d just need to:
  1. Define events as Symfony\Contracts\EventDispatcher\Event (or extend Laravel’s Event).
  2. Use a bridge like laravel-psr-event-dispatcher if we need PSR-14 dispatching in Laravel.
• Future-Proof: Aligns with modern PHP practices (PHP 8.1+, readonly properties) and avoids vendor lock-in.

Key Risks:

• Requires a bridge for full PSR-14 support in Laravel (not a core feature).
• Overkill for simple apps—best for modular or multi-framework projects.

Proposal: Pilot this in our [shared library/module X] to test interoperability before rolling out broadly. Start by defining new events using PSR-14 contracts and gradually migrate existing ones."*

For Developers:

*"This package gives us standardized event interfaces to build reusable, testable event systems. Here’s how to use it:

1. Define Events: Extend Symfony\Contracts\EventDispatcher\Event (or Laravel’s Event):

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

2. Dispatch Events: Use Laravel’s event() helper or a PSR-14 dispatcher (e.g., Symfony’s).
3. Leverage Contracts: Your events now work with any PSR-14-compliant system.

Why It Matters:

• No More Vendor Lock-in: Events aren’t tied to Laravel’s internals.
• Easier Testing: Mock PSR-14 dispatchers in unit tests.
• Cross-Framework Reuse: Same event classes in Laravel and Symfony apps.

Gotchas:

• This package is only interfaces—you’ll need a dispatcher (e.g., Laravel’s or Symfony’s).
• Laravel’s native system isn’t PSR-14 by default; use a bridge if needed.

Start Small: Try it in a new module or shared library before adopting it app-wide. For example, define all new domain events using PSR-14 contracts and observe how it feels in practice."*