laravel-eloquent

# 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.

| Feature | Purpose |
|---------|---------|
| **Models** | Table representation with attributes |
| **Relationships** | Define connections between models |
| **Query Scopes** | Reusable query constraints |
| **Casts** | Attribute type conversion |
| **Events/Observers** | React to model lifecycle |
| **Factories** | Generate test data |

---

## 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)

| Topic | Reference | When to Consult |
|