eloquent-patterns

Eloquent Patterns

Patterns for working with Eloquent that catch the common pitfalls (N+1, mass assignment, race conditions on counts, raw SQL injection).

1. N+1 prevention

The single most common Eloquent performance bug.

Problem

$users = User::all();
foreach ($users as $user) {
    echo $user->subscription->plan;  // 1 query per user → N+1
}

Solution: eager loading

$users = User::with('subscription')->get();
foreach ($users as $user) {
    echo $user->subscription?->plan;  // No extra queries
}

Nested eager loading

$users = User::with('subscription.invoices')->get();

Selective columns (further optimization)

$users = User::with(['subscription:id,user_id,plan,status'])->get();

Detection in code review

Look for any foreach or array_map over an Eloquent collection followed by ->relation access without with() upstream. That's N+1 90% of the time.

2. Scopes for reusable query logic

Encapsulate common query fragments as model scopes.

class Subscription extends Model
{
    public function scopeActive(Builder $query): void
    {
        $query->where('status', 'active')
              ->where('ends_at', '>=', now());
    }

    public function scopeForUser(Builder $query, User $user): void
    {
        $query->where('user_id', $user->id);
    }
}

// Usage:
$activeForUser = Subscription::active()->forUser($user)->get();

Benefits:

• DRY — definition lives once.
• Testable — scopes can be unit-tested.
• Self-documenting — Subscription::active() reads better than where('status', 'active')->where(...).

3. Mass assignment safety

class Subscription extends Model
{
    protected $fillable = [
        'user_id',
        'plan',
        'status',
        'starts_at',
    ];
}

Then:

Subscription::create($request->validated());  // ✅ safe

Never:

class Subscription extends Model
{
    protected $guarded = [];  // ❌ — opens door to mass-assigning is_admin, etc.
}