🗄️ Eloquent ORM and Database Migrations

What Is an ORM?

Eloquent is Laravel's Object-Relational Mapper (ORM). An ORM is a translation layer that maps rows in a relational database onto objects in your programming language. Instead of writing SELECT * FROM products WHERE id = 1 and manually stitching the result into a data structure, you write Product::find(1) and get back a Product object with typed attributes and methods.

Eloquent implements the Active Record pattern: each model class corresponds to one database table, and each instance of that class corresponds to one row. The object knows how to save, update, and delete itself.

💡 A useful analogy: Think of Eloquent as a bilingual translator sitting between two rooms. In one room your PHP code speaks in objects and methods; in the other the database speaks in tables and SQL. You never have to learn the other language fluently — the translator handles every exchange for you.

Models & CRUD

You generate a model with Artisan. The -m flag creates a matching migration at the same time — a common shortcut.

# Just the model
php artisan make:model Product

# Model + migration
php artisan make:model Product -m

# Model + migration, factory, seeder, controller, form requests, policy
php artisan make:model Product --all

A model needs almost no configuration. Laravel infers the table name (products), primary key (id), and timestamp columns automatically. You mainly declare what may be mass-assigned and how attributes should be cast.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Product extends Model
{
    use HasFactory;

    // Attributes that may be set via create()/update() (mass assignment).
    protected $fillable = ['name', 'description', 'price', 'category_id', 'active'];

    // Never expose these in arrays or JSON responses.
    protected $hidden = ['wholesale_price'];

    // Laravel 11+ casts live in a method; earlier versions used a $casts array.
    protected function casts(): array
    {
        return [
            'price'       => 'decimal:2',
            'active'      => 'boolean',
            'options'     => 'array',
            'released_at' => 'datetime',
        ];
    }
}

The four CRUD operations

// CREATE
$product = Product::create([
    'name'  => 'Laptop',
    'price' => 1299.99,
    'category_id' => 2,
]);

// READ
$all       = Product::all();
$one       = Product::find(1);
$orFail    = Product::findOrFail(1);      // throws 404 if missing
$expensive = Product::where('price', '>', 1000)->get();

// UPDATE
$product->update(['price' => 899.99]);
Product::where('category_id', 5)->update(['active' => true]);

// DELETE
$product->delete();
Product::destroy([1, 2, 3]);

Because a model instance is a row, working with data feels like working with any object: you construct it, read its properties, change them, and delete it — no SQL in sight.

Querying with Eloquent

Eloquent exposes a fluent query builder. You chain constraints, then call a terminal method like get(), first(), or paginate() to run the query.

$products = Product::where('price', '>', 100)
    ->where('category_id', 2)
    ->orderBy('name')
    ->limit(10)
    ->get();

// Aggregates
$count = Product::where('active', true)->count();
$avg   = Product::avg('price');

// Pagination (returns a paginator with links)
$page  = Product::latest()->paginate(15);

Local scopes: reusable query fragments

When the same constraint appears again and again, wrap it in a scope so the intent reads clearly at the call site.

class Product extends Model
{
    // Local scope — call it as Product::popular()
    public function scopePopular($query)
    {
        return $query->where('views', '>', 1000);
    }

    public function scopePriceRange($query, $min, $max)
    {
        return $query->whereBetween('price', [$min, $max]);
    }
}

$popular  = Product::popular()->get();
$midRange = Product::priceRange(100, 500)->get();

💡 Analogy: A query is like a request slip at a library. Rather than "bring me every book," you write "science-fiction titles published after 2010, sorted by author." A scope is a pre-printed slip for a request you make often.

Relationships & Eager Loading

Relationships are Eloquent's headline feature. You declare how models connect once, as methods, and then traverse those connections like properties.

// One-to-many: a user has many posts
class User extends Model
{
    public function posts()
    {
        return $this->hasMany(Post::class);
    }
}

// Inverse: a post belongs to one user
class Post extends Model
{
    public function user()
    {
        return $this->belongsTo(User::class);
    }

    // Many-to-many through a pivot table
    public function tags()
    {
        return $this->belongsToMany(Tag::class);
    }
}

Traversing is natural — call the method for a query, or access it as a property for the loaded result:

$user  = User::find(1);
$posts = $user->posts;              // Collection of Post models
$first = $user->posts()->latest()->first();  // add more constraints

// Attach / detach / sync on many-to-many
$post->tags()->attach([1, 2]);
$post->tags()->sync([2, 3]);        // ends up with exactly tags 2 and 3

// Bad: 1 + N queries
$posts = Post::all();
foreach ($posts as $post) {
    echo $post->user->name;   // a new query every iteration
}

// Good: 2 queries total, no matter how many posts
$posts = Post::with('user')->get();
foreach ($posts as $post) {
    echo $post->user->name;   // already loaded
}

// Eager-load several, count, and constrain
$posts = Post::with(['user:id,name', 'tags'])
    ->withCount('comments')
    ->get();

💡 Analogy: N+1 is like driving to the store for each ingredient in a recipe. Eager loading is writing one shopping list and making a single trip.

Accessors, Mutators & Casts

These three tools transform attribute values as they move between the database and your code, so the logic lives in one place.

• Accessor — transforms a value when you read it.
• Mutator — transforms a value when you write it.
• Cast — automatically converts a column's type (e.g. a JSON string ↔ a PHP array).

use Illuminate\Database\Eloquent\Casts\Attribute;

class User extends Model
{
    // Modern (Laravel 9+) accessor + mutator in one method.
    protected function name(): Attribute
    {
        return Attribute::make(
            get: fn ($value) => ucwords($value),      // read: "jane doe" -> "Jane Doe"
            set: fn ($value) => strtolower($value),    // write: store lowercase
        );
    }

    // A computed, read-only attribute: $user->full_name
    protected function fullName(): Attribute
    {
        return Attribute::make(
            get: fn () => "{$this->first_name} {$this->last_name}",
        );
    }
}

Migrations: Schema as Code

A migration is version control for your database. Each migration file has an up() method that applies a change and a down() method that reverses it. Because the schema lives in code, every teammate and every environment can reach an identical structure by running the same commands.

php artisan make:migration create_products_table
php artisan migrate            # apply pending migrations
php artisan migrate:rollback   # undo the last batch
php artisan migrate:fresh --seed   # drop all, re-migrate, then seed

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('products', function (Blueprint $table) {
            $table->id();
            $table->string('name');
            $table->text('description')->nullable();
            $table->decimal('price', 8, 2);
            $table->foreignId('category_id')->constrained();
            $table->boolean('active')->default(true);
            $table->timestamps();          // created_at + updated_at
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('products');
    }
};

The Blueprint object offers a fluent, database-agnostic vocabulary: column types (string, text, decimal, boolean, json, timestamp) and modifiers you chain on (->nullable(), ->unique(), ->default(), ->index()). The foreignId(...)->constrained() pair creates a foreign-key column and its constraint in one line.

💡 Analogy: Migrations are a time machine for your schema. migrate moves the database forward; rollback moves it back. Because the trips are recorded, you can reproduce any point in history on any machine.

Seeders & Factories

Seeders fill your database with data; factories define how to fabricate a single realistic record. Together they give you a repeatable, populated database for development and testing.

// database/factories/PostFactory.php
namespace Database\Factories;

use Illuminate\Database\Eloquent\Factories\Factory;

class PostFactory extends Factory
{
    public function definition(): array
    {
        return [
            'title'        => fake()->sentence(),
            'content'      => fake()->paragraphs(3, true),
            'published_at' => fake()->dateTimeBetween('-1 year', 'now'),
        ];
    }

    // A named state for reuse
    public function draft(): static
    {
        return $this->state(['published_at' => null]);
    }
}

// database/seeders/DatabaseSeeder.php
public function run(): void
{
    // Create 10 users, each with 3 posts
    User::factory(10)
        ->has(Post::factory()->count(3))
        ->create();
}

php artisan db:seed                       # run DatabaseSeeder
php artisan db:seed --class=UserSeeder    # run one seeder
php artisan migrate:fresh --seed          # rebuild + seed in one shot

Seeding: Database\Seeders\DatabaseSeeder
Seeded:  Database\Seeders\DatabaseSeeder (14.2ms)
Database seeding completed successfully.

Worked Example: A Blog Data Layer

Let's assemble everything into one coherent data layer: users write posts, posts belong to a category and carry many tags, and readers leave comments.

1 · Migrations

Schema::create('categories', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('slug')->unique();
    $table->timestamps();
});

Schema::create('posts', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->string('slug')->unique();
    $table->text('content');
    $table->foreignId('user_id')->constrained()->cascadeOnDelete();
    $table->foreignId('category_id')->constrained();
    $table->timestamp('published_at')->nullable();
    $table->timestamps();
});

// Pivot table for the many-to-many posts <-> tags
Schema::create('post_tag', function (Blueprint $table) {
    $table->foreignId('post_id')->constrained()->cascadeOnDelete();
    $table->foreignId('tag_id')->constrained()->cascadeOnDelete();
    $table->primary(['post_id', 'tag_id']);
});

2 · The Post model

use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Support\Str;

class Post extends Model
{
    use HasFactory;

    protected $fillable = ['title', 'slug', 'content', 'category_id', 'published_at'];

    protected function casts(): array
    {
        return ['published_at' => 'datetime'];
    }

    // Relationships
    public function user()      { return $this->belongsTo(User::class); }
    public function category()  { return $this->belongsTo(Category::class); }
    public function tags()      { return $this->belongsToMany(Tag::class); }
    public function comments()  { return $this->hasMany(Comment::class); }

    // Scope: only posts that are live
    public function scopePublished($query)
    {
        return $query->whereNotNull('published_at')
                     ->where('published_at', '<=', now());
    }

    // Auto-generate the slug whenever the title is set
    protected function title(): Attribute
    {
        return Attribute::make(
            set: fn ($value) => [
                'title' => $value,
                'slug'  => Str::slug($value),
            ],
        );
    }

    // Read-only excerpt
    protected function excerpt(): Attribute
    {
        return Attribute::make(
            get: fn () => Str::limit(strip_tags($this->content), 150),
        );
    }
}

3 · Using the data layer

// Create a post through its author, then tag it
$post = $user->posts()->create([
    'title'        => 'Getting Started with Eloquent',
    'content'      => 'Eloquent makes the data layer a joy...',
    'category_id'  => $category->id,
    'published_at' => now(),
]);

$post->tags()->sync([
    Tag::firstOrCreate(['name' => 'Laravel', 'slug' => 'laravel'])->id,
    Tag::firstOrCreate(['name' => 'Eloquent', 'slug' => 'eloquent'])->id,
]);

// Fetch the blog index: published posts, eager-loaded, paginated
$posts = Post::with(['user:id,name', 'category', 'tags'])
    ->withCount('comments')
    ->published()
    ->latest('published_at')
    ->paginate(10);

Hands-on Exercise

// Product model
public function scopeAvailable($query)
{
    return $query->where('active', true);
}

// Query
$products = Product::with('category')
    ->available()
    ->where('price', '<', 500)
    ->latest()
    ->get();

Best Practices

Summary & Quiz

📚 Further Reading

• Laravel — Eloquent: Getting Started
• Laravel — Eloquent Relationships
• Laravel — Database Migrations
• Laravel — Database Seeding

🚀 What's Next?

You can now model and persist data. Next we'll capture that data safely from users — building forms, validating input, and giving clear feedback in Form Handling and Validation.