[11.x] afterQuery hook

[gdebrauwer]

Explanation

Query scopes (or custom query builder methods) can be used to add constraints to a query, but in my projects, I use them a lot to hide (complex) code to add extra data to every queried model. Most of the time that code can completely live inside a scope, but there are some cases where some extra code needs to be executed after running the query. That extra code currently needs to live outside of the scope. That also means you have to remember to add that extra code after every query that uses that scope. Would it not be nice if we could keep that code in the scope itself? That is what this PR makes possible by adding an afterQuery method.

$query->afterQuery(function ($models) {
    // Make changes to the queried models ...
});

Use cases

Set attributes or relations in certain situations

Let's say that you have a withIsFavorite() scope that queries a boolean attribute on every model based on the authenticated user. But if there is no authenticated user, then that boolean should just be false on every model. Using the afterQuery() method, you can easily set that attribute on every model if there is no authenticated user.

// Before

public function scopeWithIsFavoriteOf($query, ?User $user = null) : void
{
    if ($user === null) {
        return $query;
    }

    $query->addSelect([
        // 'is_favorite' => some query ...
    ]);
}

$products = Product::withIsFavoriteOf(auth()->user())->get();

if (auth()->user() === null) {
    $products->each->setAttribute('is_favorite', false);
}

// After

public function scopeWithIsFavoriteOf($query, ?User $user = null) : void
{
    if ($user === null) {
        $query->afterQuery(fn ($products) => $products->each->setAttribute('is_favorite', false));

        return;
    }

    $query->addSelect([
        // 'is_favorite' => some query ...
    ]);
}

Product::withIsFavoriteOf(auth()->user())->get();

The example above could probably be done inside a query as well, but in the next example that would not be possible. Let's say we want to load the event booking of the authenticated user on every event, but if there is no authenticated user, we want to set the relation to null. We can easily achieve this with the afterQuery() method

// Before

public function scopeWithBookingOf($query, ?User $user = null) : void
{
    if ($user === null) {
        return $query;
    }

    $query->with([
        'booking' => function ($query) use ($user) {
            // ...
        }
    ]);
}

$events = Event::withBookingOf(auth()->user())->get();

if (auth()->user() === null) {
    $events->each->setRelation('booking', null);
}

// After

public function scopeWithBookingOf($query, ?User $user = null) : void
{
    if ($user === null) {
        $query->afterQuery(fn ($users) => $users->each->setRelation('booking', null));

        return;
    }

    $query->with([
        'booking' => function ($query) use ($user) {
            // ...
        }
    ]);
}

Event::withBookingOf(auth()->user())->get();

Make changes to data after it has been queried

Another example is when you load some extra data / some special relationshp in your query, but when the models are hydrated, you need to make some changes to the models and their releationships. Again, the afterQuery() makes it possible to keep that code together.

// Before

public function scopewithExtraData($query) : void
{
    $query->with('someRelation');
}

$models = Model::withExtraData()->get()->each(function ($model) {
    // making some changes to models and the loaded relation ...
});

// After

public function scopewithExtraData($query) : void
{
    $query->with('someRelation')->afterQuery(function (Collection $models) {
        $models->each(function ($model) {
            // making some changes to models and the loaded relation ...
        });
    });
}

Model::withExtraData()->get();

Only load data on the queried models instead of querying that data immediately

Another use case is where you want to load some data through a subselect on a paginated query, but you only want to do that after you have fetched the models of the current page to keep the pagination query performant. You could achieve this by creating a custom eloquent collection class for that model and adding that code to a method in that custom collection class, but that is a lot of extra code and an extra class that you might not need for anything else. The afterQuery() method makes that a lot simpler.

// Before

class UserCollection extends Collection
{
    public function loadHeadySubselectData()
    {
        // run a heavy query to get dat of selected users ...
    }
}

User::query()->paginate()->getCollection()-> loadHeadySubselectData();

// After

public function scopewithHeadySubselectData($query)
{
    $query->afterQuery(function ($users) {
        // run a heavy query on those $users ...
    })
}

User::withHeadySubselectData()->paginate();

[taylorotwell]

There are some situations where I am curious if this would take affect, which may lead to inconsistency if it doesn't. Namely, BelongsToMany@get, HasManyThrough@get.

[gdebrauwer]

I added support for those relationships. The other relationship types call the Builder@get method so those do not require any changes (If needed, I can also add tests for those relationships)

[taylorotwell]

@gdebrauwer what do you think about cursor and pluck?

[gdebrauwer]

@taylorotwell I added support for those methods. I also added some extra tests to cover the change you made to the applyAfterQueryCallbacks method

[taylorotwell]

@gdebrauwer I'm not totally sure about the cursor implementation. The get implementation can filter models out of the result set and return a smaller set of models. But, since you're calling the callback for each individual model on cursor there is different behavior between get and cursor as cursor can not remove models from the result set or do any further filtering.

[gdebrauwer]

@taylorotwell I added support for filtering when using a cursor

[taylorotwell]

Thanks 👍

[hafezdivandari]

Tests are failing on SQL Server.

[driesvints]

@hafezdivandari fixed, thanks