Laravel Eloquent ORM (L13 — Attributes-first)
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - Inspect existing models, mixed property/attribute usage
- fuse-ai-pilot:research-expert - Verify Laravel 13 Eloquent + Attributes docs via Context7
- 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
- Attributes are the source of truth - Use
#[Fillable], #[Casts], #[Hidden] on new code
- Never mix attribute + property for the same concern (
#[Fillable] AND $fillable)
- Eager load relationships - Prevent N+1 queries with
with()
- No
new Model() in boot() - Throws LogicException in L13 (booted lifecycle protected)
- 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)
1---2name: laravel-eloquent3description: Use when working with database models — Eloquent ORM, PHP attributes, relationships, queries, observers, or factories in Laravel 13.4versions:5 laravel: "13.0"6 php: "8.3"7user-invocable: true8references: references/legacy-properties.md, references/models.md, references/relationships-basic.md, references/relationships-many-to-many.md, references/relationships-advanced.md, references/relationships-polymorphic.md, references/eager-loading.md, references/scopes.md, references/casts.md, references/accessors-mutators.md, references/events-observers.md, references/soft-deletes.md, references/collections.md, references/serialization.md, references/factories.md, references/performance.md, references/resources.md, references/transactions.md, references/pagination.md, references/aggregates.md, references/batch-operations.md, references/query-debugging.md, references/templates/ModelBasic.php.md, references/templates/ModelRelationships.php.md, references/templates/ModelCasts.php.md, references/templates/Observer.php.md, references/templates/Factory.php.md, references/templates/Resource.php.md, references/templates/EagerLoadingExamples.php.md9related-skills: laravel-attributes, laravel-migrations, laravel-api, laravel-testing10metadata:11 source: https://skillmd.com/skills/fusengine/laravel-eloquent12---1314<objective>15Covers Laravel 13 Eloquent ORM with PHP 8.3 Attributes as the primary16metadata mechanism (#[Table], #[Fillable], #[Hidden], #[Visible], #[Guarded],17#[Casts], #[Appends], #[Touches], #[Connection]) alongside legacy property18equivalents for backward compatibility. Includes all relationship types19(basic, many-to-many, advanced, polymorphic), eager loading, scopes,20accessors/mutators, events/observers, soft deletes, collections,21serialization, factories, API resources, transactions, pagination,22aggregates, batch operations, and query debugging/performance.23</objective>2425# Laravel Eloquent ORM (L13 — Attributes-first)2627## Agent Workflow (MANDATORY)2829Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:30311. **fuse-ai-pilot:explore-codebase** - Inspect existing models, mixed property/attribute usage322. **fuse-ai-pilot:research-expert** - Verify Laravel 13 Eloquent + Attributes docs via Context7333. **mcp__context7__query-docs** - Query attribute patterns (#[Fillable], #[Casts], #[Scope])3435After implementation, run **fuse-ai-pilot:sniper** for validation.3637---3839## Overview4041Laravel 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.4243| Feature | Attribute (L13 MAIN) | Legacy property |44|---------|---------------------|-----------------|45| Table name | `#[Table('users')]` | `protected $table` |46| Mass assignment | `#[Fillable([...])]` | `protected $fillable` |47| Hidden / Visible | `#[Hidden([...])]` / `#[Visible([...])]` | `protected $hidden` / `$visible` |48| Guarded | `#[Guarded([...])]` / `#[Unguarded]` | `protected $guarded` |49| Casts | `#[Casts([...])]` | `casts()` method |50| Appends | `#[Appends([...])]` | `protected $appends` |51| Touches | `#[Touches([...])]` | `protected $touches` |52| Connection | `#[Connection('mysql')]` | `protected $connection` |5354---5556## Critical Rules57581. **Attributes are the source of truth** - Use `#[Fillable]`, `#[Casts]`, `#[Hidden]` on new code592. **Never mix attribute + property** for the same concern (`#[Fillable]` AND `$fillable`)603. **Eager load relationships** - Prevent N+1 queries with `with()`614. **No `new Model()` in `boot()`** - Throws `LogicException` in L13 (booted lifecycle protected)625. **Use factories** in tests - Never hardcode test data6364---6566## Architecture6768```69app/Models/70├── User.php # #[Table], #[Fillable], #[Hidden], #[Casts]71├── Post.php # #[Connection], #[Appends], relationships72└── Concerns/73 └── HasUuid.php # Reusable trait74```7576→ See [templates/ModelBasic.php.md](references/templates/ModelBasic.php.md)7778---7980## Reference Guide8182### Concepts8384- **Migration L12→L13:** [legacy-properties.md](references/legacy-properties.md)85- **Modeling:** [models.md](references/models.md) · [casts.md](references/casts.md) · [accessors-mutators.md](references/accessors-mutators.md) · [serialization.md](references/serialization.md) · [soft-deletes.md](references/soft-deletes.md)86- **Relationships:** [relationships-basic.md](references/relationships-basic.md) · [relationships-many-to-many.md](references/relationships-many-to-many.md) · [relationships-advanced.md](references/relationships-advanced.md) · [relationships-polymorphic.md](references/relationships-polymorphic.md)87- **Querying:** [eager-loading.md](references/eager-loading.md) · [scopes.md](references/scopes.md) · [aggregates.md](references/aggregates.md) · [pagination.md](references/pagination.md) · [batch-operations.md](references/batch-operations.md) · [query-debugging.md](references/query-debugging.md)88- **Lifecycle / Output:** [events-observers.md](references/events-observers.md) · [collections.md](references/collections.md) · [resources.md](references/resources.md) · [factories.md](references/factories.md) · [transactions.md](references/transactions.md) · [performance.md](references/performance.md)8990### Templates9192| Template | When to Use |93|----------|-------------|94| [ModelBasic.php.md](references/templates/ModelBasic.php.md) | Attribute-based model |95| [ModelRelationships.php.md](references/templates/ModelRelationships.php.md) | All relationship types |96| [ModelCasts.php.md](references/templates/ModelCasts.php.md) | #[Casts] and accessors |97| [Observer.php.md](references/templates/Observer.php.md) | Complete observer |98| [Factory.php.md](references/templates/Factory.php.md) | Factory with states |99| [Resource.php.md](references/templates/Resource.php.md) | API resource |100| [EagerLoadingExamples.php.md](references/templates/EagerLoadingExamples.php.md) | N+1 prevention |101102---103104## Quick Reference105106### Attribute-based Model (L13 MAIN)107108```php109use Illuminate\Database\Eloquent\Attributes\{Table, Fillable, Hidden, Casts};110use Illuminate\Database\Eloquent\Model;111112#[Table('users')]113#[Fillable(['name', 'email', 'password'])]114#[Hidden(['password', 'remember_token'])]115#[Casts(['email_verified_at' => 'datetime', 'is_admin' => 'boolean'])]116final class User extends Model117{118 public function posts(): HasMany119 {120 return $this->hasMany(Post::class);121 }122}123```124125### Scope (attribute syntax)126127```php128#[Scope]129protected function published(Builder $query): void130{131 $query->whereNotNull('published_at');132}133// Usage: Post::published()->get();134```135136### Eager Loading137138```php139$posts = Post::with('author')->get(); // 2 queries, not N+1140```141142→ Legacy `$fillable` / `$hidden` style — see [legacy-properties.md](references/legacy-properties.md)143144---145146## Best Practices147148### DO149- Declare metadata with **PHP Attributes** (`#[Table]`, `#[Fillable]`, `#[Casts]`, ...)150- Use `final` on model classes when not extended151- Eager load with `with()`152- Use factories in tests153- Cast dates, arrays, enums via `#[Casts]`154155### DON'T156- **Mix `#[Fillable]` and `$fillable`** on the same model (conflict — single source of truth)157- **Instantiate models in `boot()` / `booted()`** — L13 throws `LogicException`158- Lazy-load relationships in loops (N+1)159- Use `#[Unguarded]` in production160- Query inside accessors / mutators161- Put business logic in models (use Services/Actions)