laravel-eloquent

Covers Laravel 13 Eloquent ORM with PHP 8.3 Attributes as the primary metadata mechanism (#[Table], #[Fillable], #[Hidden], #[Visible], #[Guarded], #[Appends], #[Touches], #[Connection], #[Refreshes]) alongside legacy property equivalents for backward compatibility. Includes all relationship types (basic, many-to-many, advanced, polymorphic), eager loading, scopes, accessors/mutators, events/observers, soft deletes, collections, serialization, factories, API resources, transactions, pagination, aggregates, batch operations, and query debugging/performance.

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], #[Table], #[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	no attribute — casts() method	protected $casts
Appends	#[Appends([...])]	protected $appends
Touches	#[Touches([...])]	protected $touches
Connection	#[Connection('mysql')]	protected $connection
Primary key	#[Table(key: 'uuid', keyType: 'string', incrementing: false)]	$primaryKey / $keyType / $incrementing
Timestamps off	#[WithoutTimestamps]	public $timestamps = false
Refresh after write (13.33+)	#[Refreshes(['slug'])]	—

---

Critical Rules

1. Attributes are the source of truth - Use #[Fillable], #[Hidden], #[Table] on new code (casts stay in casts())
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 static() / new Model() inside the model's own boot() / trait boot*() - Throws LogicException in L13 (nested booting disallowed)
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};
use Illuminate\Database\Eloquent\Model;

#[Table('users')]
#[Fillable(['name', 'email', 'password'])]
#[Hidden(['password', 'remember_token'])]
final class User extends Model
{
    protected function casts(): array
    {
        return ['email_verified_at' => 'datetime', 'is_admin' => 'boolean'];
    }

    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

13.x additions

#[Refreshes(['slug'])]            // 13.33+: re-read generated columns after insert/update
final class Post extends Model {}

DB::transaction(function () use ($flight) {
    $flight->refreshForUpdate();  // 13.27+: reload with a FOR UPDATE lock
});

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

---

Best Practices

DO

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

DON'T

• Mix #[Fillable] and $fillable on the same model (conflict — single source of truth)
• Instantiate the model inside its own boot() / trait boot*() — 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)