laravel-eloquent

Laravel 13 Expert Skill: Advanced Eloquent Architecture, Performance & Domain Modeling

When to Use

Use this skill when building Laravel 13 applications that require deep Eloquent knowledge: complex relationship mapping, query performance optimization, domain-driven model design, and advanced ORM features. This is the definitive reference for Eloquent beyond simple CRUD.

---

Core Philosophy

Eloquent Is Not Your Architecture

Eloquent is:

• ORM (Object-Relational Mapper)
• Data Mapper Hybrid
• Query Builder
• Persistence Layer

Eloquent is NOT:

• Business Layer
• Application Layer
• Domain Layer

Models can contain domain behavior, but infrastructure concerns belong elsewhere. Avoid "Fat Models" that mix unrelated business logic, email sending, API calls, and file generation.

Architecture Flow

Controller (thin — validation, auth, response)
    ↓
Action / DTO (orchestration, type-safe data)
    ↓
Domain Service (business logic)
    ↓
Repository / Query Object / Custom Builder
    ↓
Model / Eloquent (persistence)
    ↓
Database

---

1. Relationships

General Rules

Always define explicit relationships — never access $post->user_id directly.

// BAD
$userId = $post->user_id;

// GOOD
$post->user;

Always declare return types on relationship methods:

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

public function posts(): HasMany
{
    return $this->hasMany(Post::class);
}

public function roles(): BelongsToMany
{
    return $this->belongsToMany(Role::class);
}

Naming conventions:

• Singular for single relations: user(), profile(), company(), subscription()
• Plural for collections: posts(), comments(), roles(), tags()

---

1.1 Morph Relations (Polymorphic Single)

Use when multiple model types can own a single related model. Best for: comments, media, attachments, activity logs, notifications, likes.

// Comment belongs to Post, Video, or Product
class Comment extends Model
{
    public function commentable(): MorphTo
    {
        return $this->morphTo();
    }
}

class Post extends Model
{
    public function comments(): MorphMany
    {
        return $this->morphMany(Comment::class, 'commentable');
    }
}

class Video extends Model
{
    public function comments(): MorphMany
    {
        return $this->morphMany(Comment::class, 'commentable');
    }
}