Custom Eloquent Relations & Query Builder Internals | Mohamed Said        [  ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png)   Mohamed Said Laravel Backend Engineer  ](https://msaied.com) [ Home ](https://msaied.com) [ Projects ](https://msaied.com/projects) [ Articles  ](https://msaied.com/articles) [ Certificates ](https://msaied.com/certificates) [ Contact ](https://msaied.com#contact-section) 

       [  ](https://github.com/EG-Mohamed)       

 [ Home ](https://msaied.com) [ Projects ](https://msaied.com/projects) [ Articles ](https://msaied.com/articles) [ Certificates ](https://msaied.com/certificates) [ Contact ](https://msaied.com#contact-section) 

  [ home ](https://msaied.com)    [ articles ](https://msaied.com/articles)    Eloquent Without the Magic: Custom Relations and Query Builder Internals        On this page       1. [  Why Bother Going Deeper? ](#why-bother-going-deeper)
2. [  How a Relation Is Actually Built ](#how-a-relation-is-actually-built)
3. [  Tapping the Query Builder Directly ](#tapping-the-query-builder-directly)
4. [  Testing the Custom Relation ](#testing-the-custom-relation)
5. [  Key Takeaways ](#key-takeaways)

  ![Eloquent Without the Magic: Custom Relations and Query Builder Internals](https://cdn.msaied.com/279/2ec9eec2d01575b831b7a9230b2ffd06.png)

  #laravel   #eloquent   #query-builder   #orm  

 Eloquent Without the Magic: Custom Relations and Query Builder Internals 
==========================================================================

     24 Jun 2026      4 min read    ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg)  Mohamed Said  

       Table of contents

1. [  01   Why Bother Going Deeper?  ](#why-bother-going-deeper)
2. [  02   How a Relation Is Actually Built  ](#how-a-relation-is-actually-built)
3. [  03   Tapping the Query Builder Directly  ](#tapping-the-query-builder-directly)
4. [  04   Testing the Custom Relation  ](#testing-the-custom-relation)
5. [  05   Key Takeaways  ](#key-takeaways)

 Why Bother Going Deeper?
------------------------

Eloquent's built-in relations cover 90 % of use-cases elegantly. The remaining 10 % — lateral joins, filtered aggregates, multi-column foreign keys — either get shoved into raw SQL strings or balloon into unmaintainable query scopes. Understanding the internals lets you write a proper `Relation` subclass instead, keeping the Eloquent API consistent across your codebase.

---

How a Relation Is Actually Built
--------------------------------

Every relation extends `Illuminate\Database\Eloquent\Relations\Relation`. The two methods you must implement are:

- **`addConstraints()`** — called immediately when the relation is instantiated on a single model, adds the `WHERE` clause for eager loading.
- **`addEagerConstraints(array $models)`** — called during eager loading, replaces the single-model constraint with an `IN (...)` clause across all parent keys.

The third required method is **`initRelation(array $models, string $relation)`** and **`match()`**, which hydrate the loaded records back onto the parent models.

```php
namespace App\Relations;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\Relation;

class LatestOfMany extends Relation
{
    public function __construct(
        Builder $query,
        Model $parent,
        protected string $foreignKey,
        protected string $localKey,
        protected string $orderColumn,
    ) {
        parent::__construct($query, $parent);
    }

    public function addConstraints(): void
    {
        if (static::$constraints) {
            $this->query
                ->where($this->foreignKey, $this->parent->{$this->localKey})
                ->orderByDesc($this->orderColumn)
                ->limit(1);
        }
    }

    public function addEagerConstraints(array $models): void
    {
        $keys = collect($models)->pluck($this->localKey)->unique()->values();

        // Use a subquery per parent key to avoid the N+1 trap
        $this->query->whereIn($this->foreignKey, $keys);
    }

    public function initRelation(array $models, $relation): array
    {
        foreach ($models as $model) {
            $model->setRelation($relation, null);
        }
        return $models;
    }

    public function match(array $models, Collection $results, $relation): array
    {
        $dictionary = $results->keyBy($this->foreignKey);

        foreach ($models as $model) {
            $key = $model->{$this->localKey};
            $model->setRelation($relation, $dictionary->get($key));
        }
        return $models;
    }

    public function getResults(): mixed
    {
        return $this->query->first();
    }
}

```

Register it on the parent model:

```php
class Order extends Model
{
    public function latestShipment(): LatestOfMany
    {
        return new LatestOfMany(
            Shipment::query(),
            $this,
            foreignKey: 'order_id',
            localKey: 'id',
            orderColumn: 'dispatched_at',
        );
    }
}

```

Now `Order::with('latestShipment')->get()` works exactly like any built-in relation — no raw SQL leaking into controllers.

---

Tapping the Query Builder Directly
----------------------------------

When you need a covering aggregate without a relation, reach for `withAggregate` or drop to the grammar layer:

```php
// Built-in — generates a correlated subquery
$orders = Order::withSum('items', 'quantity')->get();

// Manual subquery column — same idea, full control
$orders = Order::addSelect([
    'latest_dispatch' => Shipment::select('dispatched_at')
        ->whereColumn('order_id', 'orders.id')
        ->orderByDesc('dispatched_at')
        ->limit(1),
])->get();

```

For window functions, bypass Eloquent entirely and use `DB::table()` with a raw expression, then hydrate manually:

```php
$rows = DB::table('shipments')
    ->selectRaw(
        'order_id,
         dispatched_at,
         ROW_NUMBER() OVER (PARTITION BY order_id ORDER BY dispatched_at DESC) AS rn'
    )
    ->toBase() // returns the underlying QueryBuilder, no Eloquent overhead
    ->get()
    ->where('rn', 1);

```

---

Testing the Custom Relation
---------------------------

With Pest, assert eager loading produces no extra queries:

```php
it('eager-loads latest shipment without N+1', function () {
    $orders = Order::factory(5)->create();
    Shipment::factory()->for($orders->first())->create();

    $queryCount = 0;
    DB::listen(fn () => $queryCount++);

    Order::with('latestShipment')->get();

    expect($queryCount)->toBe(2); // one for orders, one for shipments
});

```

---

Key Takeaways
-------------

- `addConstraints` and `addEagerConstraints` are the two hooks that separate single-model access from eager loading — get them wrong and you reintroduce N+1.
- `match()` is pure PHP array work; keep it O(n) by keying the results collection before the loop.
- `withAggregate` / `addSelect` subqueries are often faster than a join when the aggregate touches only a few rows per parent.
- Always verify query count in tests — a custom relation that silently falls back to N+1 is worse than no relation at all.

 Found this useful?

          [  ](https://twitter.com/intent/tweet?url=https%3A%2F%2Fmsaied.com%2Farticles%2Feloquent-without-the-magic-custom-relations-and-query-builder-internals&text=Eloquent+Without+the+Magic%3A+Custom+Relations+and+Query+Builder+Internals) [  ](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fmsaied.com%2Farticles%2Feloquent-without-the-magic-custom-relations-and-query-builder-internals) 

 Frequently Asked Questions 
----------------------------

  2 questions  

     Q01  When should I write a custom Relation class instead of using a query scope?        Write a custom Relation when you need eager loading support (with/load), want the result hydrated as a model or collection, or need the relation to be chainable with further Eloquent constraints. Query scopes are better for filtering, not for associating related models. 

      Q02  Does a custom Relation class support lazy eager loading via `$model->load()`?        Yes. As long as you implement addEagerConstraints, initRelation, and match correctly, Laravel's eager loading pipeline treats your class identically to built-in relations, including load(), loadMissing(), and with(). 

  Continue reading

 More Articles 
---------------

 [ View all    ](https://msaied.com/articles) 

 [ ![Typed Enums as First-Class Domain Citizens in Laravel with PHP 8.3](https://cdn.msaied.com/282/71a8fc3e4cf4239b1bf6d38d57e0b985.png) laravel php8.3 enums 

### Typed Enums as First-Class Domain Citizens in Laravel with PHP 8.3

Go beyond simple enum labels. Learn how to attach behaviour, implement interfaces, and use backed enums as Elo...

  ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg)  Mohamed Said 

 24 Jun 2026     3 min read  

  Read    

 ](https://msaied.com/articles/typed-enums-as-first-class-domain-citizens-in-laravel-with-php-83) [ ![RAG in Laravel: pgvector, Embeddings, and Retrieval-Augmented Generation in Practice](https://cdn.msaied.com/281/8d2ac57c0e69d3ff9f1e68faf0e4d10c.png) laravel ai pgvector 

### RAG in Laravel: pgvector, Embeddings, and Retrieval-Augmented Generation in Practice

Build a production-ready RAG pipeline in Laravel using pgvector, OpenAI embeddings, and a clean retrieval laye...

  ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg)  Mohamed Said 

 24 Jun 2026     4 min read  

  Read    

 ](https://msaied.com/articles/rag-in-laravel-pgvector-embeddings-and-retrieval-augmented-generation-in-practice) [ ![Ship AI with Laravel: Failover, Queues, and Middleware for AI Agents](https://cdn.msaied.com/283/f0a6d6a6f22d9131bacb96bae1bfc10b.png) Laravel AI Agents Queues 

### Ship AI with Laravel: Failover, Queues, and Middleware for AI Agents

Learn how to make Laravel AI agents production-ready with automatic provider failover, background queue proces...

  ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg)  Mohamed Said 

 24 Jun 2026     3 min read  

  Read    

 ](https://msaied.com/articles/ship-ai-with-laravel-failover-queues-and-middleware-for-ai-agents) 

   [  ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png)   Mohamed Said Laravel Backend Engineer  ](https://msaied.com)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow.

Explore

- [Home](https://msaied.com)
- [Projects](https://msaied.com/projects)
- [Articles](https://msaied.com/articles)
- [Certificates](https://msaied.com/certificates)
- [Contact](https://msaied.com#contact-section)

Connect

- [   hello@msaied.com ](mailto:hello@msaied.com)
- [   +20 109 461 9204 ](tel:+201094619204)

© 2026 Mohamed Said. All rights reserved.

 [  ](https://github.com/EG-Mohamed) [  ](https://www.linkedin.com/in/msaiedm/) [  ](https://wa.me/201094619204) [  ](mailto:hello@msaied.com) [  ](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view)