Events

An event is an immutable record of something that happened in your system. Events are the source of truth in EventSourcerer — every projection, every aggregate, and every integration ultimately derives from the event log.

Anatomy of an event

  • Event Name — a unique, descriptive name in past tense (e.g. OrderPlaced, ItemAddedToBasket).
  • Event Version — an integer that allows safe evolution of the event's shape.
  • Stream Id — identifies the stream this event belongs to.
  • Payload — typed properties carrying the event's data.
  • Metadata — automatically attached: timestamp, correlation id, application id.

Registering an event in the dashboard

  1. Navigate to Events → Register New Event.
  2. Enter the Event Name (PascalCase, past tense).
  3. Add each property and choose its type:
    • Text — UTF-8 string
    • Integer / Float — numeric values
    • Boolean
    • UUID — for identifiers
    • DateTime — ISO-8601 timestamps
    • Json — arbitrary structured data
    • Custom types — declared through the extension API
  4. Mark properties as PII if they must be encrypted at rest (see PII Encryption).
  5. Save. The event definition is now available to every registered application.

Writing an event from PHP

use PearTreeWeb\EventSourcerer\Client\Infrastructure\Client;
use PearTreeWebLtd\EventSourcererMessageUtilities\Model\{StreamId, EventName, EventVersion};

$client
    ->connect()
    ->writeNewEvent(
        StreamId::fromString('basket-42'),
        EventName::fromString('ItemAddedToBasket'),
        EventVersion::fromString('1'),
        [
            'productId' => '0b1f...c0de',
            'name'      => 'Crystal Ball',
            'amount'    => 1999,
        ],
    );

Versioning events

Events are immutable, so when their shape changes you bump the version number. The dashboard lets you define a new version side-by-side, and projection mutations can target a specific version or fall back to the latest.

Rule of thumb: never rewrite history. Add new event versions, write upcasters, and let projections decide how to handle older versions.