Prooph V7 Event Store Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require event-engine/prooph-v7-event-store
   

   Ensure prooph/event-store (v7+) is also installed as a dependency.

2. Basic Configuration Add the service provider to config/app.php:

   EventEngine\ProophEventStore\ProophEventStoreServiceProvider::class,
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="EventEngine\ProophEventStore\ProophEventStoreServiceProvider"
   

3. First Use Case: Persisting an Event

   use EventEngine\ProophEventStore\EventStore;
   use Prooph\EventStore\Domain\Message;
   
   $eventStore = app(EventStore::class);
   $event = new MyDomainEvent('payload', ['metadata']);
   
   $eventStore->dispatch($event); // Persists to Prooph Event Store
   

4. Where to Look First

   • Config: config/event-engine-prooph-event-store.php (if published).
   • Facade: EventEngine\ProophEventStore\Facades\EventStore for quick access.
   • Contracts: EventEngine\ProophEventStore\Contracts\EventStore for custom implementations.

Implementation Patterns

Core Workflows

1. Event Dispatching Use EventStore::dispatch() for synchronous persistence:

   $eventStore->dispatch(new UserRegistered('user@example.com'));
   

   For async dispatching, integrate with Laravel queues:

   $eventStore->dispatchAsync(new OrderPlaced($orderId));
   

2. Event Retrieval Fetch events by aggregate ID:

   $events = $eventStore->loadAggregate('user-123');
   

   Or stream events from a point in time:

   $streamName = 'user-123';
   $events = $eventStore->stream($streamName)->getEvents();
   

3. Event Subscribing Subscribe to events in real-time:

   $eventStore->subscribeTo('user-123', function ($event) {
       // Handle event (e.g., update cache, send notification)
   });
   

4. Integration with Laravel Services

   • Commands: Dispatch events in handle():

     public function handle()
     {
         $eventStore->dispatch(new Event('data'));
     }
     

   • Jobs: Use dispatchSync() or dispatchAsync() in job execution.
   • Listeners: Subscribe to Prooph events via Laravel’s event system:

     Event::listen('prooph.event_store.event_published', function ($event) {
         // Cross-cutting logic
     });
     

5. Aggregate Root Management Rebuild aggregates from events:

   $aggregate = $eventStore->replayAggregate(
       UserAggregate::class,
       'user-123',
       $events
   );
   

Advanced Patterns

• Event Versioning: Leverage Prooph’s EventStore to handle schema migrations.
• Event Sourcing: Use EventStore::replay() to reconstruct state.
• CQRS: Decouple reads by projecting events into read models.

Gotchas and Tips

Pitfalls

1. Stream Naming Collisions

   • Prooph uses stream names (e.g., user-123) to isolate aggregates.
   • Fix: Ensure unique stream names (e.g., include entity type: user-123-events).

2. Async Dispatch Deadlocks

   • Async dispatch relies on Laravel queues. Unprocessed jobs may block event consistency.
   • Fix: Monitor queue workers and implement retries with retryAfter.

3. Event Serialization Issues

   • Custom events must implement JsonSerializable or Arrayable.
   • Fix: Use Prooph\EventStore\Serialization\Serializer for complex payloads.

4. Transaction Boundaries

   • Prooph’s EventStore is not a database transaction manager.
   • Fix: Wrap dispatches in Laravel transactions:

     DB::transaction(function () use ($eventStore, $event) {
         $eventStore->dispatch($event);
         // Other DB operations
     });
     

5. Memory Leaks with Subscribers

   • Long-running subscribers may accumulate memory.
   • Fix: Use EventStore::unsubscribe() or limit subscriber scope.

Debugging Tips

• Enable Prooph Logging:

  'logging' => [
      'enabled' => true,
      'channel' => 'single',
  ],
  

• Inspect Streams:

  php artisan prooph:event-store:list-streams
  

• Replay Events: Use EventStore::replay() to debug state transitions.

Extension Points

1. Custom Serializers Override the default serializer:

   $eventStore->setSerializer(new CustomSerializer());
   

2. Event Filters Filter events before dispatching:

   $eventStore->setEventFilter(function ($event) {
       return $event instanceof AllowedEvent;
   });
   

3. Event Store Plugins Extend Prooph’s EventStore with plugins (e.g., audit logging):

   $eventStore->addPlugin(new AuditPlugin());
   

4. Laravel Integration Bind custom Prooph repositories:

   $this->app->bind(
       Prooph\EventStore\Repository::class,
       function () {
           return new CustomRepository($eventStore);
       }
   );
   

Config Quirks

• Default Stream Strategy: Uses StreamNameFromAggregateId. Override in config:

  'stream_name_strategy' => EventEngine\ProophEventStore\StreamNameFromAggregateType::class,
  

• Async Dispatch: Requires queue driver in .env:

  QUEUE_CONNECTION=database