laravel-eloquent

Laravel Eloquent ORM (L13 — Attributes-first)

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:

1. fuse-ai-pilot:explore-codebase - Inspect existing models, mixed property/attribute usage
2. fuse-ai-pilot:research-expert - Verify Laravel 13 Eloquent + Attributes docs via Context7
3. mcp__context7__query-docs - Query attribute patterns (#[Fillable], #[Casts], #[Scope])

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

---

Overview

Laravel 13 promotes PHP 8.3 Attributes as the primary metadata mechanism on Eloquent models. Legacy properties ($fillable, $hidden, ...) remain supported for backward compatibility but should not be mixed with their attribute counterparts.

Feature	Attribute (L13 MAIN)	Legacy property
Table name	#[Table('users')]	protected $table
Mass assignment	#[Fillable([...])]	protected $fillable
Hidden / Visible	#[Hidden([...])] / #[Visible([...])]	protected $hidden / $visible
Guarded	#[Guarded([...])] / #[Unguarded]	protected $guarded
Casts	#[Casts([...])]	casts() method
Appends	#[Appends([...])]	protected $appends
Touches	#[Touches([...])]	protected $touches
Connection	#[Connection('mysql')]	protected $connection

---

Critical Rules

1. Attributes are the source of truth - Use #[Fillable], #[Casts], #[Hidden] on new code
2. Never mix attribute + property for the same concern (#[Fillable] AND $fillable)
3. Eager load relationships - Prevent N+1 queries with with()
4. No new Model() in boot() - Throws LogicException in L13 (booted lifecycle protected)
5. Use factories in tests - Never hardcode test data

---

Architecture

app/Models/
├── User.php              # #[Table], #[Fillable], #[Hidden], #[Casts]
├── Post.php              # #[Connection], #[Appends], relationships
└── Concerns/
    └── HasUuid.php       # Reusable trait

→ See templates/ModelBasic.php.md

---

Reference Guide

Concepts

• Migration L12→L13: legacy-properties.md
• Modeling: models.md · casts.md · accessors-mutators.md · serialization.md · soft-deletes.md
• Relationships: relationships-basic.md · relationships-many-to-many.md · relationships-advanced.md · relationships-polymorphic.md
• Querying: eager-loading.md · scopes.md · aggregates.md · pagination.md · batch-operations.md · query-debugging.md
• Lifecycle / Output: events-observers.md · collections.md · resources.md · factories.md · transactions.md · performance.md

Templates

Template	When to Use
ModelBasic.php.md	Attribute-based model
ModelRelationships.php.md	All relationship types
ModelCasts.php.md	#[Casts] and accessors
Observer.php.md	Complete observer
Factory.php.md	Factory with states
Resource.php.md	API resource
EagerLoadingExamples.php.md	N+1 prevention

---

Quick Reference

Attribute-based Model (L13 MAIN)

use Illuminate\Database\Eloquent\Attributes\{Table, Fillable, Hidden, Casts};
use Illuminate\Database\Eloquent\Model;

#[Table('users')]
#[Fillable(['name', 'email', 'password'])]
#[Hidden(['password', 'remember_token'])]
#[Casts(['email_verified_at' => 'datetime', 'is_admin' => 'boolean'])]
final class User extends Model
{
    public function posts(): HasMany
    {
        return $this->hasMany(Post::class);
    }
}

Scope (attribute syntax)

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

Eager Loading

$posts = Post::with('author')->get();  // 2 queries, not N+1

→ Legacy $fillable / $hidden style — see legacy-properties.md

---

Best Practices

DO

• Declare metadata with PHP Attributes (#[Table], #[Fillable], #[Casts], ...)
• Use final on model classes when not extended
• Eager load with with()
• Use factories in tests
• Cast dates, arrays, enums via #[Casts]

DON'T

• Mix #[Fillable] and $fillable on the same model (conflict — single source of truth)
• Instantiate models in boot() / booted() — L13 throws LogicException
• Lazy-load relationships in loops (N+1)
• Use #[Unguarded] in production
• Query inside accessors / mutators
• Put business logic in models (use Services/Actions)