[12.x] Add withTrashedRelations() to automatically eager load deleted related models

[alex-wass]

Problem

When you have several related models that have all been trashed, it can be tricky and verbose to load these along with your original model.

Let's use a blog for this example, which we can expect to have the model structure of User -> Post -> Comment. Now let's say our blog allows us to archive users along with any content they've created. That's all pretty basic Eloquent, until you need to add a way to still show archived users and their content.

The assumption would be to do something like this:

use App\Models\User;

User::limit(10)
    ->with('posts.comments')
    ->withTrashed()
    ->get();

However if we look at the queries that ran we'll quickly see why your blog is still missing some content:

select * from `users`
select * from `posts` where `posts`.`id` in (...) and `posts`.`deleted_at` is null
select * from `comments` where `comments`.`id` in (...) and `comments`.`deleted_at` is null

The method only removed the global scope for the model we queried and not any relations.

A solution for this would be to add constraints to your eager loaded models:

use App\Models\User;

User::limit(10)
    ->with([
        'posts' => fn ($query) => $query->withTrashed(),
        'posts.comments' => fn ($query) => $query->withTrashed(),
    ])
    ->withTrashed()
    ->get();

If we check the queries again, everything is now scoped correctly:

select * from `users`
select * from `posts` where `posts`.`id` in (...)
select * from `comments` where `comments`.`id` in (...)

As you can see, those with() constraints will quickly get out of hand on larger models or a more complicated query.

Solution

use App\Models\User;

User::limit(10)
    ->with('posts.comments')
-   ->withTrashed()
+   ->withTrashedRelations()
    ->get();

This new method will automatically remove the trashed scope on all eager loaded models, just like we did with the manual constraints, but without the bloat. If we check our query again, everything is still scoped correctly!

select * from `users`
select * from `posts` where `posts`.`id` in (...)
select * from `comments` where `comments`.`id` in (...)

Now I'm not discounting that you could just scope this on the model relationship, but for scenarios like this you generally want the default behaviour throughout the application, and to override it in smaller doses.

Notes

After much trial and error this seemed the best approach I could find that avoided a breaking change (based on the many ways relationships can be loaded) but I'm open to suggestions! There's also the possibility to repeat this for onlyTrashed() - I just wasn't sure if it would be wanted.

Currently this doesn't work with lazy or automatic eager loading, but if there's interest in this first step I'm happy to investigate further.

The problem I see with both of those is we don't have access to the original query because they happen once the data is collected - unless we introduce a new method like loadWithTrashed() or wrap it in a static callback like with event muting:

User::withTrashedRelations(function () {
    //
});

This implementation isn't limited to just soft deletes though, it could be used for a number of other things as it allows you to ensure any eager-loaded nested relation uses the same scope as the parent.

[rodrigopedra]

The inheritScopes() method should allow one to specify which scopes to inherit.

If a parent model has other scopes other than the SoftDeletingScope, the $builder->withTrashed()->inheritScopes() might have unexpected results.

Let's say a User model has a TeamScope applied to it to list only the users within the same team.

When calling $builder->withTrashed()->inheritScopes() that TeamScope would be applied to any related model, that could lack the required columns to apply the TeamScope scope.

[alex-wass]

Ah, good catch @rodrigopedra! I've amended that now to allow you to choose what scopes should be kept or removed - although I wasn't sure if two explicit methods would be preferred here, like with/without.

I don't think those failing tests are related to my changes, but happy to investigate if that not a known problem.

[taylorotwell]

I think a few things about this give me enough pause to hold off for now.

I don't think the before is bad enough to warrant the introduction of "inherited scopes" as a concept. I also am not sure if it's going to be a point of confusion this only applies to the eager loaded relationships you specify - not anything you lazily load after that.