[12.x] Added Automatic Relation Loading (Eager Loading) Feature

[litvinchuk]

Description

In large projects it can become difficult to track and manually specify which relations should be eager-loaded, especially if those relations are deeply nested or dynamically used. Therefore, automatic relation loading can be useful.

# instead of this

$projects->load([
    'client.owner.details',
    'client.customPropertyValues',
    'clientContact.customPropertyValues',
    'status',
    'company.statuses',
    'posts.authors.articles.likes',
    'related.statuses'
]);


# We can use this

$projects->withRelationAutoload();

Challenges include:

1. Unnecessary overhead when relations change: If the logic for loading relations changes and we forget to remove or update a load() or with() call, unnecessary relations may still be loaded, leading to performance inefficiencies.
2. Tedious manual loading: Explicitly calling load() or with() for each relation makes the code verbose and harder to read.
3. Maintenance overhead: As the number of relations grows, the related logic becomes increasingly difficult to maintain and prone to duplication.

New withRelationAutoload() Method

A new method, withRelationAutoload(), has been added to models and Eloquent collections. When called, it automatically loads relations whenever they are accessed, without the need for explicit load() or with() calls.

Example:

$orders = Order::all()->withRelationAutoload();

foreach ($orders as $order) {
    echo $order->client->owner->company->name;
}

// automatic calls:
// $orders->loadMissing('client');
// $orders->loadMissing('client.owner');
// $orders->loadMissing('client.owner.company');

Support for Morph Relations

The feature works seamlessly with polymorphic relations. It only loads the specific morph type that is accessed, ensuring efficient use of resources.

Doesn’t Break Manual Relation Loading

Users can still manually load relations using load() or with() before accessing the relation. If a relation is already loaded manually, it won’t be reloaded.

Global Automatic Loading

For cases where you want automatic loading enabled across all models, you can use the static method `

Model::globalAutoloadRelations();

This feature significantly simplifies working with relations and reduces the overhead of managing eager loading in Laravel projects, enabling developers to focus on application logic instead of data loading mechanics.

If you have suggestions for better method names, feel free to share them!

[github-actions]

Thanks for submitting a PR!

Note that draft PR's are not reviewed. If you would like a review, please mark your pull request as ready for review in the GitHub user interface.

Pull requests that are abandoned in draft may be closed due to inactivity.

[MykolaVoitovych]

It's a very desired and powerful feature. It's going to save a lot of effort. I hope it will be approved soon. Thank you so much!

[stevebauman]

I'm not sure I understand this -- isn't this typical Eloquent lazy-loading behaviour? Won't the relations in your example be loaded via lazy-loading? Ex, this should work already:

$orders = Order::all();

foreach ($orders as $order) {
    echo $order->client->owner->company->name;
}

Or are you referring to preventing the possibility from N+1'ing due to the above lazy loading?

Please correct me if I'm misunderstanding 🙏

[litvinchuk]

I'm not sure I understand this -- isn't this typical Eloquent lazy-loading behaviour? Won't the relations in your example be loaded via lazy-loading? Ex, this should work already:

$orders = Order::all();

foreach ($orders as $order) {
    echo $order->client->owner->company->name;
}

Or are you referring to preventing the possibility from N+1'ing due to the above lazy loading?

Please correct me if I'm misunderstanding 🙏

You’re absolutely right, and typically, methods like load, loadMissing, or with are used to address the N+1 problem in Eloquent. However, the challenge often arises in scenarios like views, JSON resources, or other parts of the code where a large number of relations are being accessed.

In such cases, it can become difficult to track and manually specify which relations should be eager-loaded, especially if those relations are deeply nested or dynamically used.

The withRelationAutoload() method simplifies this by automatically resolving the required relations the first time they are accessed, without requiring developers to explicitly define them in advance. This ensures that all necessary relations are eager-loaded efficiently in bulk, preventing N+1 problems while reducing the overhead of managing relation loading manually.

In your example:

$orders = Order::all();

foreach ($orders as $order) {
    echo $order->client->owner->company->name;
}

If there are 10 orders, here’s what happens:
In total, this results in 31 queries (1 for orders + 10 for client + 10 for owner + 10 for company).

With withRelationAutoload:
In total, this results in 4 queries (1 for orders + 1 for client + 1 for owner + 1 for company).

It's very simple example, we can just use with the same result

$orders->load('client.owner.company');

But if we change our code in the future, the relations will be loaded unnecessarily until we explicitly remove them from the load.

foreach ($orders as $order) {
    echo $order->client->name;
}

Let me know if this makes sense or if you’d like further clarification! 🙏

[NickSdot]

I am not sure if I fully understand this, so sorry in advance if I don't make sense.

But if this works as you say, wouldn't it make sense to replace the current lazy loading behaviour instead of making your feature opt-in?

[litvinchuk]

I am not sure if I fully understand this, so sorry in advance if I don't make sense.

But if this works as you say, wouldn't it make sense to replace the current lazy loading behaviour instead of making your feature opt-in?

Thanks for the question! The feature is opt-in to avoid forcing developers who prefer manual control over relation loading and to preserve the existing lazy-loading behavior. This also helps prevent potential issues in existing projects relying on the default behavior.

However, if desired, you can enable it globally for the entire project using Model::globalAutoloadRelations();

[moisish]

This is a great idea especially for junior devs to avoid N+1 issues

[shaedrich]

Isn't that essentially what the $with property on the model does? Well, okay, to be fair: You approached it from the other end.

Eager Loading by Default (from the Laravel docs)

Sometimes you might want to always load some relationships when retrieving a model. To accomplish this, you may define a $with property on the model:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class Book extends Model
{
    /**
     * The relationships that should always be loaded.
     *
     * @var array
     */
    protected $with = ['author'];
 
    /**
     * Get the author that wrote the book.
     */
    public function author(): BelongsTo
    {
        return $this->belongsTo(Author::class);
    }

    /**
     * Get the genre of the book.
     */
    public function genre(): BelongsTo
    {
        return $this->belongsTo(Genre::class);
    }
}