Schema evolution and event types

Event streams outlive the code that first wrote them. This package provides two independent tools for evolving that history: stable event type names and payload upcasting/migration.

Stable event names

Use #[EventName] and register the class with EventTypeRegistry:

use DomainFlow\EventSourcing\Attribute\EventName;
use DomainFlow\EventSourcing\Event\EventTypeRegistry;

#[EventName('order.placed')]
final class OrderPlaced extends SourceEvent
{
    // ...
}

$types = EventTypeRegistry::fromClasses([OrderPlaced::class]);

Pass the registry to DefaultEventEntryFactory. The stable name is stored in place of the fully qualified class name. Once data has been written under a name, keep that name permanent; the PHP class can then move or be renamed.

Registration is incremental. An unregistered class is stored by its class name, and the registry still reads existing rows whose stored value is an existing class name.

Payload schema versions

An event may expose a static getLatestSchemaVersion(): int method. The default entry factory writes that value to the reserved _schemaVersion payload key. This is the shape version of the payload, not the aggregate stream version.

Keep the marker in the payload when the payload is transformed. The core reads it to decide whether an older payload still needs migration.

When the current event class exposes migratePayload(array $payload, int $fromVersion, int $toVersion): array, the entry rebuild path calls it for an older payload before hydration. Rows without a marker are treated as the first schema version. A custom entry factory can provide a schema version from an adapter-specific column instead.

Upcasters and factories

EventFactoryInterface creates a current event from a payload. An EventUpcasterInterface can transform an older event type/payload into a newer one before the factory creates the domain event. EventUpcasterRegistry runs registered upcasters as a chain and requires an EventFactoryInterface before it can finish reconstruction.

ReflectionEventFactory is a reference factory for constructor-based events. It maps constructor parameter names to payload keys and converts identifier, DateTimeImmutable, and EventVersion parameters where the type is explicit. Use a custom factory when your event construction rules are different.