eloquent-patterns

Laravel guidance to keep Eloquent models explicit, query shapes intentional, relationship loading visible, and production data access bounded.

SKILL.md

GitHub

Eloquent Patterns

Keep models explicit, query shape intentional, and relationship loading visible near the code that renders or returns data.

Model Contracts

Models should declare mass-assignment boundaries, casts, and concrete relationship return types.

class Record extends Model
{
    protected $fillable = [
        'owner_id',
        'number',
        'total',
        'issued_at',
        'is_active',
    ];

    protected function casts(): array
    {
        return [
            'issued_at' => 'date',
            'total' => 'decimal:2',
            'is_active' => 'boolean',
            'metadata' => 'array',
        ];
    }

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

Use accessors sparingly for simple derived values. Move heavy behavior into Actions or Services.

Relationship Loading

Prevent N+1 queries by eager loading the relations a surface needs.

Before rendering Blade reports, printable views, exports, or PDFs, explicitly load the relation graph.

public function show(Record $record): View
{
    $record->load([
        'owner',
        'items.product',
        'approvals.user',
    ]);

    return view('records.show', ['record' => $record]);
}

Do not add new relation dependencies inside templates without updating the load list and render tests.

Query Volume

Do not process unbounded production datasets with all() or broad get() calls.

Use:

  • paginate() for normal UI/API lists;
  • cursor pagination for large append-only lists;
  • chunkById() or lazyById() when updating rows during iteration;
  • cursor() or lazy collections for streaming;
  • selected columns and indexed filters for high-volume paths.

Bounded Values

Keep bounded validation/display values in one source of truth.

Prefer enums when supported.

enum RecordStatus: string
{
    case Draft = 'draft';
    case Approved = 'approved';
    case Cancelled = 'cancelled';

    public function label(): string
    {
        return match ($this) {
            self::Draft => 'Draft',
            self::Approved => 'Approved',
            self::Cancelled => 'Cancelled',
        };
    }
}

Use config files for deployment-level options and constants for small legacy/model-owned maps.

Historical Data

Use soft deletes with withTrashed() when historical records must remain readable after related reference data is removed from active use.

Do not use this as a blanket rule for personal data or records subject to hard-delete compliance.

Snapshot attributes that must remain true for a historical document.

DocumentLine::create([
    'reference_id' => $reference->id,
    'reference_snapshot' => $reference->only(['code', 'name']),
]);

Store only fields needed for historical correctness and avoid unnecessary sensitive data.

Context Efficiency

Layer: 3 (Implementation)

Load this skill only when models or queries need review. Do not load with unrelated skills. Keep changes minimal: explicit casts, eager-loaded relations, paginated queries, no unbounded all() or broad get() in production paths.