Whats New in Laravel 12.8?

Discover Laravel 12.8’s automatic relation loading, a game-changing feature that eliminates the N+1 query problem with dynamic eager loading. Learn how it works, its benefits, and an edge case with polymorphic relationships in this in-depth guide.

Laravel 12.8, a recent minor release, introduces a feature that could transform how developers handle database queries in Eloquent: automatic relation loading. This addition tackles the notorious N+1 query problem, a common performance bottleneck in ORM-based applications. In this article, we’ll dive into what this feature does, how it works, its benefits, and an edge case where it falls short. We’ll also explore practical examples using a sample database structure and discuss why this could be a turning point for Laravel developers. By the end, you’ll understand why this feature is generating buzz and how to leverage it in your projects.

Understanding the N+1 Query Problem

Before we explore the new feature, let’s clarify the N+1 query problem. Imagine you’re building an e-commerce application with an orders table. Each order is linked to a customer, who belongs to a city, which in turn belongs to a country. Additionally, each order is associated with one or more products. When you fetch all orders and display their details in a table—such as the customer’s city and country or the product names—you might write code that looks like this:

$orders = Order::all();

In a Blade template, you loop through the orders and access related data:

@foreach ($orders as $order)
    <tr>
        <td>{{ $order->customer->city->country->name }}</td>
        <td>{{ $order->product->name }}</td>
    </tr>
@endforeach

This code seems straightforward, but it hides a performance trap. For each order, Eloquent lazily loads the related customer, city, country, and product. If you have 10 orders, you’ll execute:

• 1 query to fetch all orders.
• 10 queries for the customers (one per order).
• 10 queries for the cities.
• 10 queries for the countries.
• 10 queries for the products.

That’s 41 queries for just 10 orders—a classic N+1 scenario, where “N” is the number of orders, and “1” is the initial query. As the dataset grows, the number of queries balloons, slowing down your application.

Traditionally, developers solve this by eager loading relationships using the with method:

$orders = Order::with(['customer.city.country', 'product'])->get();

This reduces the query count significantly, grouping related data into a few efficient queries. For the same 10 orders, you might end up with just 4 queries:

• 1 for orders.
• 1 for customers.
• 1 for cities and countries.
• 1 for products.

While effective, eager loading requires you to manually specify every relationship you need, which can be tedious and error-prone, especially in large projects with nested relationships or when junior developers forget to include them.

Laravel 12.8 Automatic Relation Loading

Laravel 12.8 introduces automatic relation loading, a feature that aims to eliminate the N+1 problem without requiring developers to manually specify relationships. Contributed by Sirh Hillitwinuk from Ukraine, this feature began as a pull request in November 2024 and was refined over several months before being merged into the framework. It’s a testament to Laravel’s active community and commitment to improving performance.

How It Works

Automatic relation loading allows Eloquent to detect and eager load relationships dynamically based on how they’re accessed in your code. Instead of writing:

$orders = Order::with(['customer.city.country', 'product'])->get();

You can simply write:

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

Or, even more powerfully, you can enable automatic eager loading globally for your entire project. By adding a single line to your AppServiceProvider, you can ensure that all Eloquent queries automatically eager load relationships when needed:

use Illuminate\Database\Eloquent\Model;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        Model::automaticallyEagerLoadRelationships();
    }
}

With this global setting, you can write Order::all() and still get the performance benefits of eager loading—no with statements required. This is a game-changer for projects where developers might overlook eager loading or when maintaining large codebases with complex relationships.

Seeing It in Action

To demonstrate, let’s use a sample database structure for an e-commerce application:

• Orders: Contains order details, linked to a customer and products.
• Customers: Each customer belongs to a city (via city_id).
• Cities: Each city belongs to a country.
• Countries: Contains country details.
• Products: Contains product details, linked to orders.
• Media: A polymorphic relationship (via Spatie’s Media Library) for storing product images.

In a controller, we fetch all orders:

public function index()
{
    return view('orders.index', ['orders' => Order::all()]);
}

In the Blade template, we display a table:

<table>
    <thead>
        <tr>
            <th>Order ID</th>
            <th>Customer City</th>
            <th>Country</th>
            <th>Product</th>
        </tr>
    </thead>
    <tbody>
        @foreach ($orders as $order)
            <tr>
                <td>{{ $order->id }}</td>
                <td>{{ $order->customer->city->name }}</td>
                <td>{{ $order->customer->city->country->name }}</td>
                <td>{{ $order->product->name }}</td>
            </tr>
        @endforeach
    </tbody>
</table>

Without eager loading, this code triggers the N+1 problem. Using a debug bar (like Laravel Telescope or Debugbar), you might see 42 queries for a small dataset:

• 1 query for orders.
• Repeated queries for customers, cities, countries, and products for each order.

Now, let’s apply automatic relation loading:

public function index()
{
    return view('orders.index', ['orders' => Order::all()->withRelationshipAutoloading()]);
}

Refresh the page, and the debug bar shows only 6 queries:

• 1 for orders.
• 1 for customers.
• 1 for cities.
• 1 for countries.
• 1 for products.
• 1 for additional metadata.

The same result as manual eager loading, but without specifying the relationships. Now, let’s enable it globally in AppServiceProvider:

Model::automaticallyEagerLoadRelationships();

Remove the withRelationshipAutoloading() call from the controller:

public function index()
{
    return view('orders.index', ['orders' => Order::all()]);
}

Refresh again, and you still get 6 queries. This global setting ensures that all Eloquent queries in your application benefit from automatic eager loading, reducing the risk of N+1 issues across your codebase.

Comparing to PreventLazyLoading

Laravel has long offered a preventLazyLoading method, which throws an exception when a relationship is lazily loaded. You can enable it in your AppServiceProvider:

Model::preventLazyLoading();

When a lazy load occurs, Laravel halts execution and displays an error, prompting you to fix it by adding eager loading. This is useful for catching mistakes during development, especially in local environments. However, it’s reactive—you must manually address each issue.

Automatic relation loading, by contrast, is proactive. It dynamically eager loads relationships without requiring you to intervene. For example, in our orders table, accessing $order->customer->city->country->name (three levels deep) works seamlessly with automatic loading, reducing queries without extra configuration.

The Edge Case: Polymorphic Relationships

While automatic relation loading is impressive, it’s not flawless. During testing, an edge case emerged with polymorphic relationships, specifically when using Spatie’s Media Library package.

The Scenario

Spatie’s Media Library allows models to have media files (e.g., product images) stored in a media table with a polymorphic relationship (model_type and model_id). In our Blade template, we add a column to display the first media file for each product:

<td><img src="{{ $order->product->getFirstMediaUrl('images') }}" alt="Product Image"></td>

With automatic relation loading enabled, you’d expect the media files to be eager loaded. However, the debug bar reveals 13 queries:

• 6 for the orders, customers, cities, countries, and products.
• 7 additional queries, one for each product’s media file.

The polymorphic relationship isn’t automatically eager loaded, resulting in an N+1 issue. To fix this, you must manually eager load the media relationship:

public function index()
{
    return view('orders.index', ['orders' => Order::with('product.media')->get()]);
}

This reduces the query count to 7, as the media queries are grouped into one. Interestingly, even combining preventLazyLoading with automatic loading doesn’t catch this issue, suggesting that polymorphic relationships (especially in third-party packages) may require special handling.

Why It Happens

Polymorphic relationships are inherently complex, as they involve dynamic model_type and model_id fields that point to different tables. Eloquent’s automatic loading may struggle to infer these relationships without explicit configuration. This could be a limitation of the feature itself or a specific interaction with Spatie’s Media Library. Either way, it’s an edge case worth noting.

Workaround

For now, monitor your queries using tools like Laravel Debugbar or Telescope, especially when working with polymorphic relationships. If you encounter N+1 issues, manually eager load the problematic relationships. You can also report such cases to the Laravel community (e.g., on GitHub) to help improve the feature. The pull request author or other contributors may propose a fix in future releases.

Why This Feature Matters

Automatic relation loading is a significant step forward for Laravel’s Eloquent ORM. Here’s why it’s generating excitement:

1. Simplified Code: No need to manually specify relationships with with. This reduces boilerplate code and makes controllers cleaner.

2. Error Prevention: Junior developers or those unfamiliar with eager loading are less likely to introduce N+1 issues, as the framework handles it automatically.

3. Global Configuration: Enabling automatic loading project-wide ensures consistent performance across all queries, even in legacy codebases.

4. Scalability: As datasets grow, N+1 issues become more pronounced. Automatic loading mitigates this, improving application scalability.

5. Future Potential: If Laravel makes automatic loading the default in future versions, it could redefine best practices for Eloquent, making performance optimization effortless.

However, the feature isn’t a silver bullet. You should still:

• Monitor Queries: Use tools like Debugbar or Telescope to verify query performance, especially for edge cases like polymorphic relationships.
• Test Thoroughly: Ensure automatic loading works as expected in your specific use cases, particularly with third-party packages.
• Stay Informed: Follow Laravel’s documentation and GitHub discussions for updates on the feature, as it may evolve in future releases.

Practical Tips for Using Automatic Relation Loading

To make the most of this feature, consider these tips:

1. Enable Globally for New Projects: Add Model::automaticallyEagerLoadRelationships() to your AppServiceProvider for new projects to ensure consistent performance from the start.

2. Use Debug Tools: Install Laravel Debugbar or Telescope to monitor query counts and identify N+1 issues during development.

3. Combine with PreventLazyLoading: In local environments, enable preventLazyLoading alongside automatic loading to catch any relationships that aren’t being eager loaded correctly.

4. Handle Edge Cases Manually: For polymorphic relationships or other complex scenarios, be prepared to use manual eager loading as a fallback.

5. Contribute to the Community: If you encounter issues like the polymorphic relationship problem, share them on GitHub. Your feedback could help refine the feature.

6. Educate Your Team: If you’re working in a team, explain the feature to colleagues, especially those new to Laravel, to ensure everyone understands its benefits and limitations.

Looking Ahead: The Future of Eloquent Performance

Automatic relation loading is a glimpse into the future of Eloquent. By reducing the cognitive load on developers and automating performance optimizations, Laravel continues to prioritize developer experience without sacrificing power. While the feature is still new and has room for improvement (e.g., better handling of polymorphic relationships), it’s a bold step toward making Eloquent more efficient out of the box.

In the broader context, this feature aligns with Laravel’s philosophy of balancing simplicity and sophistication. It’s reminiscent of earlier performance-focused features like preventLazyLoading, but it takes a more proactive approach. If adopted as a default in future Laravel versions, it could redefine how developers approach database queries, making N+1 a relic of the past.

For now, automatic relation loading is a tool to embrace with cautious optimism. Use it to streamline your code, but keep an eye on your queries to ensure it’s working as expected. As the Laravel community continues to test and refine this feature, we can expect even more robust solutions for Eloquent performance.

Conclusion

Laravel 12.8’s automatic relation loading is a powerful addition to Eloquent, offering a seamless way to tackle the N+1 query problem. By enabling dynamic eager loading—either per query or globally—it simplifies code, boosts performance, and reduces the risk of common mistakes. While it shines in most scenarios, edge cases like polymorphic relationships remind us to stay vigilant and monitor our queries.

Whether you’re building a small app or a large-scale platform, this feature can save you time and improve your application’s scalability. Try it in your next project, experiment with global configuration, and share your findings with the Laravel community. With tools like this, Laravel continues to make PHP development both enjoyable and efficient.