Getting started with Eloquent

What is the Eloquent ORM?

Laravel includes an object-relational mapper (ORM) called Eloquent. Eloquent makes it easy to interact with the database and implements the Active Record pattern. With Eloquent, you create a “model” class that corresponds to each table in the database. You retrieve, insert, update, and delete records through the model.

Before using Eloquent, configure your database connection in config/database.php. By default, the DB_* settings in your .env file are used.

Creating a model

Generate a new model with the make:model Artisan command.

php artisan make:model Post

To create a migration at the same time, use the -m option.

php artisan make:model Post -m

The model is created in the app/Models directory.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    // ...
}

Model-to-table mapping

Eloquent infers the table name from the class name automatically. The class name converted to a snake_case plural becomes the table name.

Model name	Table name
`Post`	`posts`
`User`	`users`
`AirTrafficController`	`air_traffic_controllers`

If your table name does not follow the naming convention, define the $table property on the model to specify it explicitly.

class Post extends Model
{
    protected $table = 'blog_posts';
}

Timestamps

By default, Eloquent automatically manages the created_at and updated_at columns. Include $table->timestamps() in your migration and Eloquent will set these values for you when the model is saved or updated. To disable automatic timestamp management, set $timestamps to false.

class Post extends Model
{
    public $timestamps = false;
}

Mass assignment protection

When saving data in bulk with Eloquent, you must configure mass assignment protection.

fillable

Use the $fillable property to specify which columns may be mass assigned.

class Post extends Model
{
    protected $fillable = [
        'user_id',
        'title',
        'body',
        'published',
    ];
}

guarded

Conversely, use $guarded to specify which columns cannot be mass assigned.

class Post extends Model
{
    // Only protect the primary key, allow every other column
    protected $guarded = ['id'];
}

Setting $guarded to an empty array allows mass assignment on every column. When you pass user input directly, there is a risk that unintended columns will be overwritten, so we recommend explicitly listing allowed columns with $fillable.

Eloquent query execution flow

Here is how a query such as User::where()->get() is executed internally.

Basic CRUD operations

Retrieving records (Read)

Retrieve every record:

use App\Models\Post;

$posts = Post::all();

Retrieve records with a condition:

// Retrieve posts where published is true
$publishedPosts = Post::where('published', true)->get();

// Retrieve the first matching record
$post = Post::where('published', true)->first();

// Retrieve a single record by ID
$post = Post::find(1);

// Return a 404 response when the record is not found
$post = Post::findOrFail(1);

Creating records (Create)

Use the create method to insert a single record (you must configure $fillable):

$post = Post::create([
    'title' => 'My first post',
    'body' => 'Laravel is a fantastic framework.',
    'published' => true,
]);

You can also create an instance and assign values individually.

$post = new Post;
$post->title = 'My first post';
$post->body = 'Laravel is a fantastic framework.';
$post->save();

Updating records (Update)

Retrieve the model, change its values, and call save to persist the update.

$post = Post::find(1);
$post->title = 'Updated title';
$post->save();

Use update to update multiple columns at once.

Post::find(1)->update([
    'title' => 'Updated title',
    'published' => true,
]);

You can also update every record that matches a condition in one call.

Post::where('published', false)->update(['published' => true]);

Deleting records (Delete)

Use the delete method to remove a record.

$post = Post::find(1);
$post->delete();

You can also delete directly by ID.

Post::destroy(1);

// Delete multiple IDs at once
Post::destroy([1, 2, 3]);

Common query methods

Method	Description
`Post::all()`	Retrieve all records
`Post::find($id)`	Retrieve one record by ID (returns `null` if not found)
`Post::findOrFail($id)`	Retrieve one record by ID (returns 404 if not found)
`Post::where('column', 'value')->get()`	Retrieve records matching the condition
`Post::where('column', 'value')->first()`	Retrieve the first record matching the condition
`Post::where('column', 'value')->count()`	Count records matching the condition
`Post::orderBy('created_at', 'desc')->get()`	Retrieve records in a specific order
`Post::latest()->get()`	Retrieve records in descending order of `created_at`
`Post::limit(10)->get()`	Retrieve a limited number of records

Practical example: working with the Post model

Here is a controller that operates on the posts table created by a migration.

<?php

namespace App\Http\Controllers;

use App\Models\Post;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\View\View;

class PostController extends Controller
{
    // Display a list of posts
    public function index(): View
    {
        $posts = Post::where('published', true)
            ->latest()
            ->get();

        return view('posts.index', ['posts' => $posts]);
    }

    // Create a post
    public function store(Request $request): RedirectResponse
    {
        $validated = $request->validate([
            'title' => ['required', 'string', 'max:255'],
            'body' => ['required', 'string'],
            'published' => ['boolean'],
        ]);

        Post::create([
            ...$validated,
            'user_id' => $request->user()->id,
        ]);

        return redirect('/posts');
    }

    // Update a post
    public function update(Request $request, Post $post): RedirectResponse
    {
        $validated = $request->validate([
            'title' => ['required', 'string', 'max:255'],
            'body' => ['required', 'string'],
        ]);

        $post->update($validated);

        return redirect('/posts');
    }

    // Delete a post
    public function destroy(Post $post): RedirectResponse
    {
        $post->delete();

        return redirect('/posts');
    }
}

When you type-hint a controller method parameter as Post $post, Laravel automatically retrieves the model from the route parameter (route model binding). You no longer need to call Post::findOrFail($id) yourself.

The model event lifecycle

Here are the events fired when you call save(). Different events fire depending on whether it is a create or an update, but saving and saved fire in both cases.

Next steps

Migrations

A refresher on creating the tables Eloquent uses with migrations.

Getting Started

Basics

Request Handling

Database

Authentication

Helpers and External Communication

Testing and Deployment

AI Development Support

What is the Eloquent ORM?

Creating a model

Model-to-table mapping

Timestamps

Mass assignment protection

fillable

guarded

Eloquent query execution flow

Basic CRUD operations

Retrieving records (Read)

Creating records (Create)

Updating records (Update)

Deleting records (Delete)

Common query methods

Practical example: working with the Post model

The model event lifecycle

Next steps

Migrations

​What is the Eloquent ORM?

​Creating a model

​Model-to-table mapping

​Timestamps

​Mass assignment protection

​fillable

​guarded

​Eloquent query execution flow

​Basic CRUD operations

​Retrieving records (Read)

​Creating records (Create)

​Updating records (Update)

​Deleting records (Delete)

​Common query methods

​Practical example: working with the Post model

​The model event lifecycle

​Next steps

Migrations

What is the Eloquent ORM?

Creating a model

Model-to-table mapping

Timestamps

Mass assignment protection

fillable

guarded

Eloquent query execution flow

Basic CRUD operations

Retrieving records (Read)

Creating records (Create)

Updating records (Update)

Deleting records (Delete)

Common query methods

Practical example: working with the Post model

The model event lifecycle

Next steps