Event Sourcing Knowledge Base

Quick reference for Event Sourcing architecture patterns and PHP implementation guidelines.

Core Principles

Event Sourcing Fundamentals

Traditional Storage:          Event Sourcing:
┌─────────────────┐           ┌─────────────────┐
│  Current State  │           │  Event Stream   │
│  ─────────────  │           │  ─────────────  │
│  Order #123     │           │  1. OrderCreated│
│  Status: Paid   │           │  2. ItemAdded   │
│  Total: $150    │           │  3. ItemAdded   │
└─────────────────┘           │  4. OrderPaid   │
       ↓                      └────────┬────────┘
  Direct update                        │
                                       ▼
                              ┌─────────────────┐
                              │  Current State  │
                              │  (Rebuilt from  │
                              │   events)       │
                              └─────────────────┘

Rule: Store events, derive state. Never modify events.

Key Concepts

Concept	Description
Event	Immutable record of something that happened
Event Store	Append-only storage for events
Event Stream	Ordered sequence of events for one aggregate
Aggregate	Consistency boundary, rebuilt from events
Projection	Read model built by processing events
Snapshot	Cached aggregate state for performance

Quick Checklists

Event Checklist

Named in past tense (OrderCreated, ItemAdded)
Immutable (readonly class)
Contains all data needed to apply change
Has metadata (timestamp, causation, correlation IDs)
No business logic
Versioned for schema evolution

Aggregate Checklist

State rebuilt from events only
apply*() methods modify state from events
record*() methods create and apply events
No direct state modification
Returns uncommitted events for persistence

Event Store Checklist

Projection Checklist

Idempotent event handlers
Can be rebuilt from scratch
Handles event ordering
Tracks processed position

Common Violations Quick Reference

Violation	Where to Look	Severity
Mutable event	Event with setters	Critical
Direct state mutation	Aggregate bypassing events	Critical
Missing event data	Event without full state info	Critical
Event with logic	Event doing calculations	Warning
Non-idempotent projection	Projection with side effects	Warning
Missing metadata	Event without timestamp/IDs	Warning

PHP 8.4 Event Sourcing Patterns

Domain Event

final readonly class OrderConfirmedEvent
{
    public function __construct(
        public string $orderId,
        public int $totalCents,
        public string $currency,
        public DateTimeImmutable $confirmedAt,
        public EventMetadata $metadata
    ) {}
}

final readonly class EventMetadata
{
    public function __construct(
        public string $eventId,
        public DateTimeImmutable $occurredAt,
        public ?string $causationId = null,
        public ?string $correlationId = null,
        public int $version = 1
    ) {}
}

Event-Sourced Aggregate

final class Order extends EventSourcedAggregate
{
    private OrderStatus $status;
    private Money $total;

    public static function create(OrderId $id, CustomerId $customerId): self
    {
        $order = new self($id);
        $order->recordThat(new OrderCreatedEvent(
            orderId: $id->value,
            customerId: $customerId->value,
            createdAt: new DateTimeImmutable()
        ));
        return $order;
    }

    public function confirm(): void
    {
        if ($this->status !== OrderStatus::Draft) {
            throw new InvalidStateException();
        }
        $this->recordThat(new OrderConfirmedEvent(
            orderId: $this->id->value,
            totalCents: $this->total->cents(),
            currency: $this->total->currency(),
            confirmedAt: new DateTimeImmutable()
        ));
    }

    protected function applyOrderCreatedEvent(OrderCreatedEvent $event): void
    {
        $this->status = OrderStatus::Draft;
        $this->total = Money::zero('USD');
    }

    protected function applyOrderConfirmedEvent(OrderConfirmedEvent $event): void
    {
        $this->status = OrderStatus::Confirmed;
    }
}

Projection

final class OrderListProjection
{
    public function __construct(
        private Connection $connection
    ) {}

    public function applyOrderCreatedEvent(OrderCreatedEvent $event): void
    {
        $this->connection->insert('order_list', [
            'id' => $event->orderId,
            'customer_id' => $event->customerId,
            'status' => 'draft',
            'created_at' => $event->createdAt->format('Y-m-d H:i:s'),
        ]);
    }

    public function applyOrderConfirmedEvent(OrderConfirmedEvent $event): void
    {
        $this->connection->update('order_list', [
            'status' => 'confirmed',
            'total_cents' => $event->totalCents,
            'confirmed_at' => $event->confirmedAt->format('Y-m-d H:i:s'),
        ], ['id' => $event->orderId]);
    }
}

References

For detailed information, load these reference files:

```
references/event-store-patterns.md
```
— Event persistence, streams, concurrency
```
references/projection-patterns.md
```
— Read model projections
```
references/snapshot-patterns.md
```
— Performance optimization with snapshots
```
references/versioning-patterns.md
```
— Event schema evolution
```
references/antipatterns.md
```
— Common violations with detection patterns

Awesome-claude-code event-sourcing-knowledge