Event Dispatcher Implementations Laravel Package

Getting Started

Install via Composer:

composer require psr-discovery/event-dispatcher-implementations

Register the package in config/app.php under providers:

PsrDiscovery\EventDispatcherImplementations\EventDispatcherImplementationsServiceProvider::class,

Publish the config (if needed) with:

php artisan vendor:publish --provider="PsrDiscovery\EventDispatcherImplementations\EventDispatcherImplementationsServiceProvider"

First use case: Replace Laravel's default event dispatcher with a PSR-14 compliant implementation (e.g., Symfony's EventDispatcher). Bind it in AppServiceProvider:

public function register(): void
{
    $this->app->bind(\Symfony\Component\EventDispatcher\EventDispatcherInterface::class, function ($app) {
        return new \Symfony\Component\EventDispatcher\EventDispatcher();
    });
}

Implementation Patterns

Core Workflow

1. PSR-14 Compliance: Use the package to integrate PSR-14 event dispatchers (e.g., Symfony, League) alongside Laravel’s native events.
2. Event Listeners: Register listeners via:
   • Config file (published by the package):

     'listeners' => [
         'App\Events\OrderPlaced' => [
             'App\Listeners\NotifyCustomer',
             'App\Listeners\LogOrder',
         ],
     ],
     

   • Programmatically in a service provider:

     $dispatcher->addListener(OrderPlaced::class, new NotifyCustomer());
     

3. Hybrid Dispatching: Dispatch both Laravel and PSR-14 events:

   // Laravel-style
   event(new OrderPlaced($order));
   
   // PSR-14 style
   $dispatcher->dispatch(new OrderPlaced($order));
   

Integration Tips

• Middleware: Use Symfony’s EventSubscriberInterface for subscriber-based patterns:

  class OrderSubscriber implements EventSubscriberInterface
  {
      public static function getSubscribedEvents(): array
      {
          return [
              OrderPlaced::class => 'onOrderPlaced',
          ];
      }
  }
  

• Testing: Mock the dispatcher in tests:

  $mockDispatcher = $this->createMock(EventDispatcherInterface::class);
  $this->app->instance(EventDispatcherInterface::class, $mockDispatcher);
  

Gotchas and Tips

Breaking Changes (1.2.0)

• PHP 8.2 Requirement: Ensure your project meets the minimum PHP version. Update php: in composer.json:

  "config": {
      "platform": {
          "php": "8.2"
      }
  }
  

  Run composer update afterward.

Debugging

• Listener Registration: Verify listeners are bound via:

  php artisan config:clear
  

  Or inspect the dispatcher’s listeners:

  $dispatcher->getListenersFor(OrderPlaced::class);
  

• Circular Dependencies: Avoid circular references between listeners/subcribers (e.g., A calls B, which calls A).

Extension Points

• Custom Dispatchers: Extend the base EventDispatcherImplementationsServiceProvider to add your own PSR-14 implementations.
• Priority Handling: Use Symfony’s EventDispatcher for priority-based listeners (not natively supported in Laravel’s dispatcher):

  $dispatcher->addListener(OrderPlaced::class, new NotifyCustomer(), 100); // Higher priority
  

• Event Normalization: Convert Laravel events to PSR-14-compliant classes if needed (e.g., implement Psr\EventDispatcher\StoppableEventInterface).