Add whenRelation to Eloquent relations

[mashirou1234]

Summary

This adds whenRelation() to Eloquent relations.

This addresses #53292, where calling when() on a relationship forwards the call
to the underlying Eloquent builder instead of passing the relationship instance
to the callback.

$user->posts()
    ->whenRelation($condition, function (BelongsToMany $relation) {
        return $relation->wherePivotIn('post_id', [1, 2]);
    });

The existing when() behavior is left unchanged so callbacks typed as
Illuminate\Database\Eloquent\Builder continue to work.

Fixes #53292.

Tests

• Added coverage for whenRelation() callbacks receiving the relation instance.
• Added coverage that when() continues to receive the underlying builder.

[shaedrich]

First things first, it would have helped me understand this if there was an example in the PR description

The existing when() call is forwarded to the underlying Eloquent builder, so changing it would be a breaking change for callbacks typed as Illuminate\Database\Eloquent\Builder.

Okay, so

User::query()->posts()->when(...);

doesn't work, right?

And now we can do

User::query()->posts()->whenRelation(...);

as if it was when(), correct?

Without this context and by just seeing the method name, I would assume, I would have to write

User::query()->whenRelation('posts', ...);

[mashirou1234]

Sorry about that, and thanks for pointing it out.

I've updated the description to show that whenRelation() is intended to be
called on the relationship instance, not as
User::query()->whenRelation('posts', ...).

[shaedrich]

Thanks for updating to prevent misunderstandings. However, I would find whenRelation('posts', ...) more intuitive

[mashirou1234]

That makes sense. I see how whenRelation() can suggest something closer to
whereRelation(), where the relation name is passed as the first argument.

The intent here is narrower: an opt-in when()-style helper for an already
created relationship instance, without changing the existing forwarded when()
behavior.

Given that, I agree the current name may be misleading. I'm open to renaming it
if there is a better fit for Laravel's API conventions.