Allow for eager loading models

[inxilpro]

Many events create or update models in their handle() method, and up until now, this could cause an N+1 issue if you were operating on a lot of events that all interact with the same model at the same time (either batch operations or replays).

This introduces a new #[EagerLoad] attribute that you can add to any protected model property of an event (they must be protected because the model shouldn't be serialized with the event data).

For example:

class UserPromotedToManager extends Event
{
  #[StateId(UserState::class)]
  public int $user_id;

  #[EagerLoad]
  protected User $user;

  public function handle()
  {
    // If the user wasn't eager-loaded, load it lazily
    $this->user ??= User::find($this->user_id);

    $this->user->update(['role' => 'manager']);
  }
}

When verbs encounters a batch of events that have EagerLoad attributes, it'll load them all in a single query and then push the results into the appropriate events.

🪄

[inxilpro]

I'm not certain this should be clone here — there are pros and cons to both approaches. Deserves discussion.

[inxilpro]

Namely: with clone you avoid subtle bugs around recursion and side effects (although some of these are addressed in the latest Laravel 11 release). Without clone, each event will be mutating the same model, which is probably preferable. Otherwise changes in one even won't impact others correctly.