Eventsauce Messenger Laravel Package

Integration Approach

Stack Fit

• Laravel + Symfony Messenger Bridge:

  • Symfony Messenger (via spatie/laravel-messenger or custom bridge) acts as the message broker for Laravel, replacing or extending the native Bus system.
  • EventSauce integrates as the event store and projection engine, with eventsauce-messenger acting as the adapter between Symfony Messenger and EventSauce’s event consumption.
  • Queue System: Laravel’s queue workers (e.g., queue:work) must be configured to process Symfony Messenger messages, requiring custom middleware sequencing.
  • Database: EventSauce’s event store (PostgreSQL/Redis) runs parallel to Laravel’s Eloquent, with projections syncing to Laravel models via event listeners or read models.

• Key Compatibility Points:

  • Event Classes: Must implement EventSauce’s Message interface (e.g., extends \EventSauce\EventSourcing\Message).
  • Handler Methods: Use #[AsEventSauceMessageHandler] attribute or Symfony Messenger tags (messenger.message_handler).
  • Middleware: HandleEventSauceMessageMiddleware must be inserted into Laravel’s queue worker pipeline (e.g., via Horizon or custom QueueWorker).

Migration Path

1. Prerequisites:

   • Upgrade Laravel to PHP 8.2+ (for union types and Symfony Messenger compatibility).
   • Install dependencies:

     composer require symfony/messenger andreo/eventsauce-messenger eventsauce/event-sourcing spatie/laravel-messenger
     

   • Configure spatie/laravel-messenger to use Symfony Messenger (e.g., config/messenger.php with eventBus).

2. EventSauce Setup:

   • Initialize EventSauce’s event store (e.g., PostgreSQL schema via EventSauce\EventSourcing\Postgres\PostgresEventRepository).
   • Define event classes (e.g., app/Events/FooCreated.php) extending EventSauce\EventSourcing\Message.
   • Create projections (e.g., app/Projections/FooProjection) to sync data to Laravel models.

3. Symfony Messenger Integration:

   • Configure eventBus in config/messenger.php:

     'buses': [
         'eventBus': [
             'middleware': [
                 'send_message',
                 'Andreo\EventSauce\Messenger\Middleware\HandleEventSauceMessageMiddleware',
                 'handle_message',
             ],
         ],
     ],
     

   • Register the MessengerMessageDispatcher in Laravel’s AppServiceProvider:

     $this->app->bind(
         \Andreo\EventSauce\Messenger\Dispatcher\MessengerMessageDispatcher::class,
         fn($app) => new \Andreo\EventSauce\Messenger\Dispatcher\MessengerMessageDispatcher(
             $app->get('messenger.bus.eventBus')
         )
     );
     

4. Event Handlers:

   • Option A: Attribute-Based (Recommended) Create handlers with #[AsEventSauceMessageHandler]:

     use Andreo\EventSauce\Messenger\Attribute\AsEventSauceMessageHandler;
     use EventSauce\EventSourcing\EventConsumption\EventConsumer;
     
     class FooHandler extends EventConsumer
     {
         #[AsEventSauceMessageHandler(bus: 'eventBus')]
         public function onFooCreated(FooCreated $event): void
         {
             // Handle event (e.g., update projection)
         }
     }
     

   • Option B: Manual YAML Tags Define handlers in config/services.yaml:

     services:
         App\Handlers\FooHandler:
             tags:
                 - { name: messenger.message_handler, handles: App\Events\FooCreated, bus: eventBus, method: handle }
     

5. Dispatching Events:

   • Replace Laravel’s event(new FooCreated()) with Symfony Messenger:

     $this->messenger->dispatch(new FooCreated());
     

   • For background processing, use Laravel’s queue system with Symfony Messenger’s send() method:

     $this->messenger->send(new FooCreated());
     

6. Queue Worker Configuration:

   • Extend Laravel’s queue:work to process Symfony Messenger messages:

     php artisan queue:work --queue=eventBus --daemon
     

   • For Horizon, configure a custom QueueWorker to include HandleEventSauceMessageMiddleware.

Compatibility

• Laravel-Symfony Conflicts:

  • Service Container: Resolve via Symfony’s ParameterBag or Laravel’s ExtendServiceProvider.
  • Event Dispatching: Use a wrapper class to translate between Laravel’s Event facade and Symfony Messenger.
  • Middleware: Sequence HandleEventSauceMessageMiddleware after send_message and before handle_message in Symfony Messenger’s pipeline.

• EventSauce-Specific:

  • Event Serialization: Ensure EventSauce’s Message classes are JSON-serializable (compatible with Symfony Messenger’s transport).
  • Projection Updates: Use Laravel’s Model observers or EventSauce projections to sync data (avoid duplicate logic).

Sequencing

1. Event Flow:

   Laravel Code → Symfony Messenger → EventSauce Dispatcher → EventSauce Event Store → Projections → Laravel Models
   

2. Middleware Order (Symfony Messenger):

   [send_message] → [HandleEventSauceMessageMiddleware] → [handle_message]
   

3. Queue Worker Pipeline (Laravel):
   • Before: Standard Laravel queue workers (e.g., Illuminate\Bus\QueueWorker).
   • After: Custom worker with Symfony Messenger’s MessageBus integration.

Operational Impact

Maintenance

• Dependency Management:
  • Symfony Messenger: Requires regular updates (v6.2+) and potential Laravel bridge maintenance.
  • EventSauce: Needs event store schema updates (e.g., PostgreSQL migrations) and projection maintenance.
  • Custom Middleware: HandleEventSauceMessageMiddleware may need bug fixes if Laravel/Symfony versions diverge.
• Logging/Monitoring:
  • Symfony Messenger: Use monolog for message dispatch logs.
  • EventSauce: Leverage EventSauce’s event store logs and projection errors.
  • Laravel: Extend queue:failed table to include Symfony Messenger-specific metadata.

Support

• Troubleshooting:
  • Event Handling Failures: Debug via:
    • Symfony Messenger’s failed_messages table (if using Doctrine transport).
    • EventSauce’s event replay for projection errors.
    • Laravel’s queue:failed for queue worker crashes.
  • Type Safety: Union types (e.g., BarCreated|BazCreated) may require custom error handling for mismatched events.
• Community/Documentation:
  • Limited Adoption: 0 stars on GitHub; rely on Symfony Messenger and EventSauce docs.
  • Stack Overflow: Search for symfony messenger eventsauce or laravel symfony messenger.

Scaling

• Horizontal Scaling:
  • Queue Workers: Scale Laravel’s queue:work horizontally, but ensure EventSauce projections are idempotent (handle duplicate events).
  • Event Store: EventSauce’s PostgreSQL/Redis store must support high write throughput (consider partitioning for large-scale systems).
• Performance:
  • Event Consumer Overhead: EventSauce’s EventConsumer may increase memory usage per event compared to Laravel’s lightweight jobs.
  • Projection Bottlenecks: Complex projections (e.g., aggregating 1M events) may require optimized queries or batch processing.
• Throughput:
  • Symfony Messenger: Configure async transports (e.g., doctrine://default) for high-volume event dispatching.
  • Laravel Queues: Use Redis queue for low-latency event processing.

Failure Modes