Polyfill Symfony Event Dispatcher Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require sylius-labs/polyfill-symfony-event-dispatcher
   

   Add to composer.json under require or require-dev depending on your needs.

2. First Use Case Replace legacy event dispatching logic with Symfony’s EventDispatcherInterface:

   use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
   use SyliusLabs\PolyfillSymfonyEventDispatcher\EventDispatcher;
   
   // Initialize (if not using DI)
   $dispatcher = new EventDispatcher();
   
   // Dispatch an event
   $dispatcher->dispatch(new MyEvent(), 'my.event');
   

3. Where to Look First

   • README for basic usage.
   • Symfony’s EventDispatcher docs for API reference (this polyfill mirrors it).
   • src/EventDispatcher.php for implementation details (if extending).

Implementation Patterns

Core Workflows

1. Event Listener Registration Register listeners dynamically or statically:

   $dispatcher->addListener('event.name', [$listener, 'handle']);
   $dispatcher->addSubscriber(new MySubscriber());
   

2. Event Dispatching Dispatch events with optional priority:

   $dispatcher->dispatch($event, 'event.name', 10); // Priority 10
   

3. Integration with Laravel Bind the polyfill to Laravel’s service container:

   $app->singleton(EventDispatcherInterface::class, function ($app) {
       return new EventDispatcher();
   });
   

   Use in controllers/services:

   public function __construct(private EventDispatcherInterface $dispatcher) {}
   

4. Legacy Code Migration Replace old-style event systems (e.g., custom EventManager) with the polyfill:

   // Before:
   $eventManager->trigger('event.name', $event);
   
   // After:
   $dispatcher->dispatch($event, 'event.name');
   

Advanced Patterns

• Event Subscribers: Group related listeners into a single class implementing EventSubscriberInterface.
• Stopping Propagation: Use Event::stopPropagation() in listeners to halt further dispatching.
• Lazy Loading: Initialize the dispatcher only when needed (e.g., in a service provider).

Gotchas and Tips

Pitfalls

1. PHP Version Compatibility

   • Drop PHP 8.0+: The package no longer polyfills (as of v1.2.0). Use native Symfony EventDispatcher for PHP 8.0+.
   • Symfony 4.4+: Requires Symfony 4.4+ or 5.4+ (check composer.json constraints).

2. Listener Ordering

   • Listeners are called in the order they were added. Use priorities (e.g., addListener(..., 20)) for control.

3. Event Object Mutability

   • Events should be immutable unless designed otherwise. Avoid modifying them in listeners unless intentional.

4. Circular Dependencies

   • Avoid circular references between listeners and events (e.g., EventA dispatching EventB which re-dispatches EventA).

Debugging Tips

• Listener Not Firing? Verify the event name matches exactly (case-sensitive) and the listener method signature:

  // Correct:
  $dispatcher->addListener('user.created', [$userService, 'handleUserCreated']);
  
  // Incorrect (wrong name or method):
  $dispatcher->addListener('user.created', [$userService, 'handleUserCreatedEvent']);
  

• Performance Bottlenecks Use addSubscriber() for groups of listeners to reduce overhead.

• Testing Mock EventDispatcherInterface in tests:

  $mockDispatcher = $this->createMock(EventDispatcherInterface::class);
  $mockDispatcher->expects($this->once())->method('dispatch');
  

Extension Points

1. Custom EventDispatcher Extend EventDispatcher to add middleware or logging:

   class CustomDispatcher extends EventDispatcher {
       public function dispatch($event, string $eventName = null, int $priority = 0) {
           Log::debug("Dispatching {$eventName}");
           parent::dispatch($event, $eventName, $priority);
       }
   }
   

2. Global Event Namespaces Prefix event names to avoid collisions (e.g., app.user.created instead of user.created).

3. Laravel-Specific Publish config or bind the dispatcher to Laravel’s events facade:

   Event::listen('event.name', function () { /* ... */ });
   

   (Requires additional binding logic.)