Add Legacy Event handler

[nick-potts]

This PR introduces a new feature that allows mapping of legacy event types to new event classes. This functionality is crucial for maintaining backwards compatibility when refactoring event classes in long-lived applications.

Usage

You can now map legacy event types to new event classes using the Verbs facade:

Verbs::mapLegacyEvents([
    NewEvent::class => ['OldEvent', 'VeryOldEvent'],
]);

Why This Is Important

When refactoring event classes in a system that stores events in a database, you may encounter issues with deserializing old events. For example:

class UserRegistered extends Event
{
    public function __construct(public string $username) {}
}

// After refactoring
class UserSignedUp extends Event
{
    public function __construct(public string $username) {}
}

Without this mapping feature, trying to replay old UserRegistered events would fail because the class no longer exists.

With the new mapping feature, you can easily handle such refactoring:

Verbs::mapLegacyEvents([
    UserSignedUp::class => 'UserRegistered',
]);

This ensures that old UserRegistered events in the database are correctly deserialized as UserSignedUp events.

[inxilpro]

It feels like the solution here is just to run a one-time job that renames the event in your DB if you really need to change the name of a class…