Laravel Eloquent ORM

Laravel Eloquent ORM

Agent Workflow (MANDATORY)

Before ANY implementation, launch in parallel:

1. fuse-ai-pilot:explore-codebase - Check existing models, relationships
2. fuse-ai-pilot:research-expert - Verify latest Eloquent docs via Context7
3. mcp__context7__query-docs - Query specific patterns (casts, scopes)

After implementation, run fuse-ai-pilot:sniper for validation.

---

Overview

Eloquent is Laravel's ActiveRecord ORM implementation. Models represent database tables and provide a fluent interface for queries.

---

Critical Rules

1. Always eager load relationships - Prevent N+1 queries
2. Use scopes for reusable queries - Don't repeat WHERE clauses
3. Cast attributes properly - Type safety for dates, arrays, enums
4. No business logic in models - Keep models slim
5. Use factories for testing - Never hardcode test data

---

Decision Guide

Relationship Type

What's the cardinality?
├── One-to-One → hasOne / belongsTo
├── One-to-Many → hasMany / belongsTo
├── Many-to-Many → belongsToMany (pivot table)
├── Through another → hasOneThrough / hasManyThrough
└── Polymorphic?
    ├── One-to-One → morphOne / morphTo
    ├── One-to-Many → morphMany / morphTo
    └── Many-to-Many → morphToMany / morphedByMany

Performance Issue

What's the problem?
├── Too many queries → Eager loading (with)
├── Memory exhaustion → chunk() or cursor()
├── Slow queries → Add indexes, select columns
├── Repeated queries → Cache results
└── Large inserts → Batch operations

---

Reference Guide

Concepts (WHY & Architecture)

Templates (Complete Code)

---

Quick Reference

Basic Model

class Post extends Model
{
    protected $fillable = ['title', 'content', 'author_id'];

    protected function casts(): array
    {
        return [
            'published_at' => 'datetime',
            'metadata' => 'array',
        ];
    }

    public function author(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }
}

Eager Loading

// ✅ Good - 2 queries
$posts = Post::with('author')->get();

// ❌ Bad - N+1 queries
$posts = Post::all();
foreach ($posts as $post) {
    echo $post->author->name;
}

Query Scopes

#[Scope]
protected function published(Builder $query): void
{
    $query->whereNotNull('published_at');
}

// Usage: Post::published()->get();

---

Best Practices

DO

• Use $fillable for mass assignment protection
• Eager load relationships with with()
• Use scopes for reusable query logic
• Cast dates, arrays, and enums
• Use factories in tests

DON'T

• Put business logic in models
• Lazy load in loops (N+1)
• Use $guarded = [] in production
• Query in accessors/​mutators
• Forget foreign keys in with() columns