event-sourcing-knowledge

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

• Append-only (no updates, no deletes)
• Ordered within stream
• Supports optimistic concurrency
• Events never modified
• Stream position tracking

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