Laravel EloquentSAFE

A collection of Agent Skills Standard and Best Practice for Programming Languages, Frameworks that help our AI Agent follow best practies on frameworks and programming laguages

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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)

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.