The new event_version column. What is this for?

[nrobates]

I have been looking through the codebase as well as the documentation. I do not see the purpose of the event_version column. Could anyone please explain what it is or should be used for compared to the aggregate_version?

[andycowan]

If you need to change the definition of an event, for example, add a property, you can tell your event that it's a new version and provide a serializer to cope with the changes.

So, say I want to add a 'description' property to an event CardProcessed.

I can add

#[
    EventVersion(2),
    EventSerializer(CardProcessedSerializer::class)
]

before my class definition, add my new property and create the CardProcessedSerializer class which should do something like:

class CardProcessedSerializer extends JsonEventSerializer
{
    public function deserialize(
        string $eventClass,
        string $json,
        int $version,
        string $metadata = null
    ): TransactionCardProcessed {
        $data = json_decode($json, true);

        if ($version === 1) {
            $data['description'] = ''; // or whatever...
        }

        return new TransactionCardProcessed(...$data);
    }
}

Now when retrieving version 1 events, the serializer will provide a value for the new field, rather than borking because the event constructor requires the property, but it wasn't stored on the older events.