Agent Skills: Laravel Eloquent ORM (L13 — Attributes-first)

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)