Common Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require prooph/common
   

   No additional configuration is required—it’s a pure PHP library with no Laravel-specific setup.

2. First Use Case: Event Streaming The package provides Prooph\Common\Event\EventStream for handling event sourcing. Initialize it in a Laravel service:

   use Prooph\Common\Event\EventStream;
   
   $stream = new EventStream('order_events', 'user-123');
   $stream->append(new OrderCreatedEvent('order-456', '2023-01-01'));
   

3. Key Classes to Explore

   • EventStream: Core for event sourcing.
   • Message: Base class for domain events/commands.
   • EventStoreId: UUID handling (via ramsey/uuid).
   • Metadata: Attach metadata to messages.

Implementation Patterns

Event Sourcing Workflow

1. Aggregate Root Design Use EventStream to track state transitions:

   class OrderAggregate {
       private EventStream $stream;
   
       public function __construct(EventStream $stream) {
           $this->stream = $stream;
       }
   
       public function create(string $orderId): void {
           $this->stream->append(new OrderCreatedEvent($orderId));
       }
   }
   

2. Replaying Events Reconstruct state by replaying events:

   $stream = new EventStream('order_events', 'user-123');
   $stream->loadFromHistory([/* array of serialized events */]);
   

3. Metadata Integration Attach context (e.g., timestamps, user IDs):

   $event = new OrderCreatedEvent('order-456');
   $event->setMetadata(['created_by' => 'admin']);
   

Command/Query Patterns

• Commands: Extend Prooph\Common\Message\Command for CQRS.
• Queries: Extend Prooph\Common\Message\Query for read models.

Laravel Integration Tips

• Service Providers: Bind EventStream to the container:

  $this->app->bind(EventStream::class, function () {
      return new EventStream('events', 'user-' . auth()->id());
  });
  

• Event Dispatching: Use Laravel’s Event facade to trigger domain events:

  event(new OrderCreatedEvent('order-456'));
  

Gotchas and Tips

Pitfalls

1. UUID Handling

   • EventStoreId uses ramsey/uuid. Ensure your Laravel app has it installed:

     composer require ramsey/uuid
     

   • Avoid hardcoding UUIDs; generate them dynamically:

     use Prooph\Common\Event\EventStoreId;
     
     $id = EventStoreId::fromString(Uuid::uuid4()->toString());
     

2. Immutable Events Events are immutable. Modify metadata via setMetadata() before appending to the stream.

3. Serialization Events must implement JsonSerializable or __toString(). Use Prooph\Common\Event\ActionEvent as a base for complex events.

Debugging

• EventStream State Dump the stream’s events to verify state:

  dd($stream->getUncommittedEvents());
  

• Metadata Conflicts Check for duplicate metadata keys during event appending.

Extension Points

1. Custom Event Stores Extend Prooph\Common\Event\EventStore for persistence (e.g., Doctrine, Eloquent). Example:

   class LaravelEventStore implements EventStore {
       public function load($streamName, $streamIdentifier) {
           // Fetch from DB
       }
   }
   

2. Event Subscribers Use Laravel’s Events to listen to Prooph\Common\Event\EventPublished:

   Event::listen(OrderCreatedEvent::class, function ($event) {
       // Side effects (e.g., notifications)
   });
   

3. Testing Mock EventStream in tests:

   $mockStream = Mockery::mock(EventStream::class);
   $mockStream->shouldReceive('append')->once();