---
name: laravel-eloquent
description: Write performant Eloquent queries with eager loading, reusable scopes, and strict lazy-loading prevention in Laravel. Use when defining model relationships, creating query scopes, or processing large datasets with chunk/cursor.
metadata:
  triggers:
    files:
    - 'app/Models/**/*.php'
    keywords:
    - scope
    - with
    - eager
    - chunk
    - model
---
# Laravel Eloquent

## **Priority: P0 (CRITICAL)**

## Workflow: Add Model with Safe Queries

1. **Define model** — Set `$fillable`, `$casts`, and relationships.
2. **Enable strict loading** — Call `Model::preventLazyLoading(!app()->isProduction())` in AppServiceProvider.
3. **Add scopes** — Create `scopeActive()`, `scopeVerified()` for reusable filters.
4. **Eager-load in queries** — Use `with()` for all relationship access.
5. **Process large datasets** — Use `chunk()` or `cursor()` instead of `get()`.

## Scope + Eager Loading Example

See [implementation examples](references/implementation.md#scope--eager-loading-example) for model scopes, eager loading, and directory structure.

## Implementation Guidelines

### Query Efficiency & Performance

- **N+1 Prevention**: **Always use `with()`** or `$with` for relationships. Never access relationship properties in loop without eager loading (**N+1 Prevention**).
- **Strict Loading**: Call **`Model::preventLazyLoading(!app()->isProduction())`** in **`AppServiceProvider::boot()`** to throw **`LazyLoadingViolationException`** in local/dev.
- **Large Datasets**: Use **`chunk()`**, **`lazy()`**, or **`cursor()`** for processing many records without memory issues (**Memory Efficiency**).

### Query Logic & Scopes

- **Reusable Scopes**: Define **`scopeName(Builder $query): Builder`** methods in models for **reusable query filters**.
- **Chaining**: Chain scopes (e.g., `User::active()->verified()->get()`) to keep controllers from duplicating query logic.

### Models & Security

- **Mass Assignment**: Always define **`protected $fillable`** array; use **`$request->validated()`** for **`Model::create()`**.
- **Casting**: Use **`protected $casts`** for dates, JSON, and custom types to ensure data consistency.

## Anti-Patterns

- **No lazy loading**: Eager-load with `with()` or `$with`; never in loops.
- **No business logic in Models**: Move to Services or Actions.
- **No raw SQL strings**: Use Query Builder or Eloquent methods.
- **No `select *`**: Specify required columns to limit data transfer.

## References

- [Eloquent Performance Guide](references/implementation.md)