home / skills / fusengine / agents / laravel-eloquent

laravel-eloquent skill

needs review

/plugins/laravel-expert/skills/laravel-eloquent

This skill helps you efficiently model, relate, and query Laravel Eloquent data with best practices like eager loading, scopes, and casts.

npx playbooks add skill fusengine/agents --skill laravel-eloquent

Review the files below or copy the command above to add this skill to your agents.

Files (29)

SKILL.md

7.2 KB

---
name: laravel-eloquent
description: Complete Eloquent ORM - models, relationships, queries, casts, observers, factories. Use when working with database models.
versions:
  laravel: "12.x"
  php: "8.4"
user-invocable: true
references: 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.md
related-skills: laravel-migrations, laravel-api, laravel-testing
---

# Laravel Eloquent ORM

## Agent Workflow (MANDATORY)

Before ANY implementation, use `TeamCreate` to spawn 3 agents:

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 |
|-------|-----------|-----------------|
| **Models** | [models.md](references/models.md) | Model config, fillable, conventions |
| **Basic Relations** | [relationships-basic.md](references/relationships-basic.md) | HasOne, HasMany, BelongsTo |
| **Many-to-Many** | [relationships-many-to-many.md](references/relationships-many-to-many.md) | Pivot tables, attach/sync |
| **Advanced Relations** | [relationships-advanced.md](references/relationships-advanced.md) | Through, dynamic relations |
| **Polymorphic** | [relationships-polymorphic.md](references/relationships-polymorphic.md) | MorphTo, MorphMany |
| **Eager Loading** | [eager-loading.md](references/eager-loading.md) | N+1 prevention, with() |
| **Scopes** | [scopes.md](references/scopes.md) | Local, global, dynamic |
| **Casts** | [casts.md](references/casts.md) | Type casting, custom casts |
| **Accessors/Mutators** | [accessors-mutators.md](references/accessors-mutators.md) | Attribute transformation |
| **Events/Observers** | [events-observers.md](references/events-observers.md) | Lifecycle hooks |
| **Soft Deletes** | [soft-deletes.md](references/soft-deletes.md) | Recoverable deletion |
| **Collections** | [collections.md](references/collections.md) | Eloquent collection methods |
| **Serialization** | [serialization.md](references/serialization.md) | toArray, toJson, hidden |
| **Factories** | [factories.md](references/factories.md) | Test data generation |
| **Performance** | [performance.md](references/performance.md) | Optimization techniques |
| **API Resources** | [resources.md](references/resources.md) | JSON transformation |
| **Transactions** | [transactions.md](references/transactions.md) | Atomic operations, rollback |
| **Pagination** | [pagination.md](references/pagination.md) | paginate, cursor, simplePaginate |
| **Aggregates** | [aggregates.md](references/aggregates.md) | count, sum, withCount, exists |
| **Batch Operations** | [batch-operations.md](references/batch-operations.md) | insert, upsert, mass update |
| **Query Debugging** | [query-debugging.md](references/query-debugging.md) | toSql, dd, DB::listen |

### Templates (Complete Code)

| Template | When to Use |
|----------|-------------|
| [ModelBasic.php.md](references/templates/ModelBasic.php.md) | Standard model with scopes |
| [ModelRelationships.php.md](references/templates/ModelRelationships.php.md) | All relationship types |
| [ModelCasts.php.md](references/templates/ModelCasts.php.md) | Casts and accessors |
| [Observer.php.md](references/templates/Observer.php.md) | Complete observer |
| [Factory.php.md](references/templates/Factory.php.md) | Factory with states |
| [Resource.php.md](references/templates/Resource.php.md) | API resource |
| [EagerLoadingExamples.php.md](references/templates/EagerLoadingExamples.php.md) | N+1 prevention |

---

## Quick Reference

### Basic Model

```php
class Post extends Model
{
    protected $fillable = ['title', 'content', 'author_id'];

    protected function casts(): array
    {
        return [
            'published_at' => 'datetime',
            'metadata' => 'array',
        ];
    }

    public function author(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }
}
```

### Eager Loading

```php
// ✅ Good - 2 queries
$posts = Post::with('author')->get();

// ❌ Bad - N+1 queries
$posts = Post::all();
foreach ($posts as $post) {
    echo $post->author->name;
}
```

### Query Scopes

```php
#[Scope]
protected function published(Builder $query): void
{
    $query->whereNotNull('published_at');
}

// Usage: Post::published()->get();
```

---

## Best Practices

### DO
- Use `$fillable` for mass assignment protection
- Eager load relationships with `with()`
- Use scopes for reusable query logic
- Cast dates, arrays, and enums
- Use factories in tests

### DON'T
- Put business logic in models
- Lazy load in loops (N+1)
- Use `$guarded = []` in production
- Query in accessors/mutators
- Forget foreign keys in `with()` columns

Overview

This skill provides a complete, opinionated guide to working with Laravel Eloquent: models, relationships, queries, casts, observers, and factories. It codifies patterns for performance, type safety, and maintainability so you can model your database cleanly and avoid common pitfalls. Use it when implementing or reviewing Eloquent models and related database logic.

How this skill works

The skill inspects model structure, relationship types, query patterns, casts, observers, and factory definitions to recommend concrete implementations and fixes. It enforces critical rules like eager loading, scope reuse, proper casting, and separation of business logic from models. It also suggests performance remedies (eager loading, chunking, indexing) and provides templates for common model and relationship code.

When to use it

When creating new Eloquent models or migrating schema to models
When defining or refactoring relationships (one-to-one, one-to-many, many-to-many, polymorphic)
When diagnosing performance issues (N+1, memory, slow queries)
When adding casts, accessors/mutators, observers, or factories
When writing tests and generating realistic test data

Best practices

Always eager load relationships to prevent N+1 queries
Encapsulate reusable constraints as query scopes, not repeated WHEREs
Define casts for dates, arrays, and enums for type safety
Keep business logic out of models; use services or domain classes
Use factories for test data and avoid hardcoded values in tests
Prefer chunk()/cursor() for large datasets and batch inserts for bulk writes

Example use cases

Create a Post model with published scope, datetime casts, and author relationship; use Post::published()->with('author')->paginate()
Refactor a controller that lazy-loads relations into a query with with() to eliminate N+1 queries
Define a polymorphic Comment relation that can attach to Post and Video with morphMany/morphTo
Add an observer to set derived attributes and dispatch domain events on create/update
Build factories with states to seed realistic test scenarios and use them in feature tests

FAQ

How do I decide which relationship type to use?

Pick by cardinality: one-to-one uses hasOne/belongsTo, one-to-many uses hasMany/belongsTo, many-to-many uses belongsToMany with a pivot, and use hasOneThrough/hasManyThrough or polymorphic relations when appropriate.

How can I quickly fix N+1 query problems?

Identify the missing relationships and use with() to eager load them. For large result sets, combine with select() to limit columns or use chunk()/cursor() to reduce memory.