Tutorial

A Guide to Using Eloquent ORM in Laravel

Draft updated on Invalid Date

Laravel

By Chris on Code

A Guide to Using Eloquent ORM in Laravel

This tutorial is out of date and no longer maintained.

Introduction

The Eloquent ORM that comes with Laravel makes it incredibly easy to interact with a database. Today we’ll look at how we can use Eloquent to interact with our database and do:

The basic CRUD functions
Set up and use one-to-one relationships
Set up and use one-to-many relationships
Set up and use many-to-many relationships

How Does Eloquent Work?

The Eloquent ORM provides an ActiveRecord implementation to work with your database. This means that each model you create in your MVC structure corresponds to a table in your database.

A Bear model will correspond to a bears table in your database. Since we have conventions when creating our models and database tables, we can easily call data from our database.

For example, to get all bears from a Bear model, all you would do is Bear::all(). Using this function would query the database and generate the proper SQL command. Here are some quick examples:

Description	Function
Find all bears	`Bear::all()`
Find a record	`Bear::find(id)`
Delete a record	`Bear::delete(id)`

Super simple! There are many more applications of this and we’ll get into them further into this article.

Sample Application

Let’s create a sample application about bears. Let’s say there are many bears. There are different types of bears with different weights and danger levels.

We will also say there are fish. Each fish belongs to a single bear since bears don’t like sharing. This will be our one-to-one relationship.

Bears also love to climb trees. Each bear will have many trees they like to climb. This will be our one-to-many relationship.

There will also be picnics. Many bears can go to many picnics since they like to ransack as many delicious picnics as they can. This will be our many-to-many relationship.

Laravel Setup

To get started using Eloquent, we’ll need to set up our database and application. Let’s run through that real quick. We’ll need to:

Install Laravel: composer install --prefer-dist
Change our database settings in app/config/database.php
Create migrations using artisan
Create Eloquent models
Seed our database

Those first two parts are easy enough so get those done. Then we’ll work on migrating and seeding our database.

Creating Our Migrations

With our migrations, we will be adding three tables to our database: bears, fish, and picnics. For more information on using migrations, read the Laravel docs.

Migrations

Bears Migration

Let’s create our migration. Through the command line, type:

php artisan migrate:make create_bears_table --create=bears

Let’s go in and add our fields.

    // app/database/migrations/####_##_##_######_create_bears_table.php
    ...

    Schema::create('bears', function(Blueprint $table)
    {
        $table->increments('id');

        $table->string('name');
        $table->string('type');
        $table->integer('danger_level'); // this will be between 1-10

        $table->timestamps();
    });

    ...

By default, these migrations will include an auto-incrementing id. It will also include timestamps for the fields created_at and updated_at. updated_at will be automatically updated whenever the record is updated.

Fish Migration

php artisan migrate:make create_fish_table --create=fish

    // app/database/migrations/####_##_##_######_create_fish_table.php
    ...

    Schema::create('fish', function(Blueprint $table)
    {
        $table->increments('id');

        $table->integer('weight'); // we'll use this to demonstrate searching by weight
        $table->integer('bear_id'); // this will contain our foreign key to the bears table

        $table->timestamps();
    });

    ...

Plural vs Singular Database Table Names With our bears, we can create the standard plural table name (ie bears, picnics). With fish, it’s different. Do we use fish or fishes? The good news is we can use whichever we want and then override the defaults when defining our Eloquent model.

Tree Migration

php artisan migrate:make create_trees_table --create=trees

    // app/database/migrations/####_##_##_######_create_trees_table.php
    ...

    Schema::create('trees', function(Blueprint $table)
    {
        $table->increments('id');

        $table->string('type');
        $table->integer('age'); // how old is the tree
        $table->integer('bear_id'); // which bear climbs this tree

        $table->timestamps();
    });

    ...

Picnic Migration

Since we will be creating a one-to-many relationship, we will need two tables. One for the picnics and another to link a bear to a picnic.

php artisan migrate:make create_picnics_table --create=picnics

    // app/database/migrations/####_##_##_######_create_picnics_table.php
    ...

    Schema::create('picnics', function(Blueprint $table)
    {
        $table->increments('id');

        $table->string('name');
        $table->integer('taste_level'); // how tasty is this picnic?

        $table->timestamps();
    });

    ...

Now we will need a table to link our bears to a picnic. We’ll create a pivot table here. This is how we can define our many-to-many relationship.

php artisan migrate:make create_bears_picnics_table --create=bears_picnics

    // app/database/migrations/####_##_##_######_create_bears_picnics_table.php
    ...

    Schema::create('bears_picnics', function(Blueprint $table)
    {
        $table->increments('id');

        $table->integer('bear_id'); // the id of the bear
        $table->integer('picnic_id'); // the id of the picnic that this bear is at

        $table->timestamps();
    });

    ...

Now we have a way to link our multiple bears to multiple picnics. This is how we create our many-to-many relationship.

Migrating Our Database

With our migration files made, migrate your database using artisan:

php artisan migrate

Eloquent Models

Now that we have migrated our database, we will need to seed our database. The process of seeding however is inserting records into our database and this will require Eloquent! We will need to create our models before we can seed the database.

Let’s make our Eloquent models. This is also where we will define our relationships.

Bear Model

Let’s look at our Bear model first.

    // app/models/Bear.php
    <?php

    class Bear extends Eloquent {

        // MASS ASSIGNMENT -------------------------------------------------------
        // define which attributes are mass assignable (for security)
        // we only want these 3 attributes able to be filled
        protected $fillable = array('name', 'type', 'danger_level');

        // DEFINE RELATIONSHIPS --------------------------------------------------
        // each bear HAS one fish to eat
        public function fish() {
            return $this->hasOne('Fish'); // this matches the Eloquent model
        }

        // each bear climbs many trees
        public function trees() {
            return $this->hasMany('Tree');
        }

        // each bear BELONGS to many picnic
        // define our pivot table also
        public function picnics() {
            return $this->belongsToMany('Picnic', 'bears_picnics', 'bear_id', 'picnic_id');
        }

    }

Mass Assignment We have to set our mass assignable attributes so that we make sure that only the attributes we want are allowed to be changed.

Defining Relationships When defining relationships, the name of the function can be whatever you want it to be named. It makes sense here since we will be finding the fish that belongs to the bear. On the line return $this->hasOne('Fish') however, you will need to match the name of the Eloquent model that corresponds to that item.

There are different ways we can define relationships. There are hasOne, hasMany, belongsTo, belongsToMany, and more. Read the Eloquent Relationship docs to see all the things you can do.

Eloquent Model and Database Table Naming Conventions By default, when you define an Eloquent model, you name it for the singular term. In this case Bear. Eloquent will then look to the database for the lowercase and plural version of that word. In this case, this model will be linked to our bears table we created in our migration.

Fish Model

Here is our Fish model.

    // app/models/Fish.php
    <?php

    class Fish extends Eloquent {

        // MASS ASSIGNMENT -------------------------------------------------------
        // define which attributes are mass assignable (for security)
        // we only want these 3 attributes able to be filled
        protected $fillable = array('weight', 'bear_id');

        // LINK THIS MODEL TO OUR DATABASE TABLE ---------------------------------
        // since the plural of fish isnt what we named our database table we have to define it
        protected $table = 'fish';

        // DEFINE RELATIONSHIPS --------------------------------------------------
        public function bear() {
            return $this->belongsTo('Bear');
        }

    }

Like we talked about earlier, since we named our table fish, then it doesn’t follow convention. We will explicitly call out the database name using protected $table.

Similar to how we defined our relationship in the Bear model, we will define the inverse of that relationship. A Fish belongs to a Bear.

Tree Model

    // app/models/Tree.php
    <?php

    class Tree extends Eloquent {

        // MASS ASSIGNMENT -------------------------------------------------------
        // define which attributes are mass assignable (for security)
        // we only want these 3 attributes able to be filled
        protected $fillable = array('type', 'age', 'bear_id');

        // DEFINE RELATIONSHIPS --------------------------------------------------
        public function bear() {
            return $this->belongsTo('Bear');
        }

    }

Picnic Model

You know the drill now. Let’s make the Picnic model.

    // app/models/Picnic.php
    <?php

    class Picnic extends Eloquent {

        // MASS ASSIGNMENT -------------------------------------------------------
        // define which attributes are mass assignable (for security)
        // we only want these 3 attributes able to be filled
        protected $fillable = array('name', 'taste_level');

        // DEFINE RELATIONSHIPS --------------------------------------------------
        // define a many to many relationship
        // also call the linking table
        public function bears() {
            return $this->belongsToMany('Bear', 'bears_picnics', 'picnic_id', 'bear_id');
        }

    }

Just like our other models, we have defined mass assignable attributes and relationships. When defining many-to-many relationships, you use belongsToMany() and not hasMany. hasMany is used for one-to-many relationships.

Now that we have our migrations and models done, we can seed our database. We will use Eloquent for inserting into our database for our seeds.

For more information on Eloquent concepts like creating Eloquent models, performing CRUD, or defining relationships, definitely read the Laravel Eloquent docs.

Seeding Our Database

For those of you who don’t know, seeding allows us to fill our database with dummy information to play with. This is great when developing our applications and need data to populate our application.

We will create database seeders inside of the app/database/seeds/DatabaseSeeder.php.

Usually, you would want to create separate seed files, but we’re going to dump everything into this file to make this simple. (We want to get to querying things with Eloquent already!)

    // app/database/seeds/DatabaseSeeder.php
    <?php

    class DatabaseSeeder extends Seeder {

        /**
         * Run the database seeds.
         *
         * @return void
         */
        public function run()
        {
            Eloquent::unguard();

            // call our class and run our seeds
            $this->call('BearAppSeeder');
            $this->command->info('Bear app seeds finished.'); // show information in the command line after everything is run
        }

    }

    // our own seeder class
    // usually this would be its own file
    class BearAppSeeder extends Seeder {

        public function run() {

            // clear our database ------------------------------------------
            DB::table('bears')->delete();
            DB::table('fish')->delete();
            DB::table('picnics')->delete();
            DB::table('trees')->delete();
            DB::table('bears_picnics')->delete();

            // seed our bears table -----------------------
            // we'll create three different bears

            // bear 1 is named Lawly. She is extremely dangerous. Especially when hungry.
            $bearLawly = Bear::create(array(
                'name'         => 'Lawly',
                'type'         => 'Grizzly',
                'danger_level' => 8
            ));

            // bear 2 is named Cerms. He has a loud growl but is pretty much harmless.
            $bearCerms = Bear::create(array(
                'name'         => 'Cerms',
                'type'         => 'Black',
                'danger_level' => 4
            ));

            // bear 3 is named Adobot. He is a polar bear. He drinks vodka.
            $bearAdobot = Bear::create(array(
                'name'         => 'Adobot',
                'type'         => 'Polar',
                'danger_level' => 3
            ));

            $this->command->info('The bears are alive!');

            // seed our fish table ------------------------
            // our fish wont have names... because theyre going to be eaten

            // we will use the variables we used to create the bears to get their id

            Fish::create(array(
                'weight'  => 5,
                'bear_id' => $bearLawly->id
            ));
            Fish::create(array(
                'weight'  => 12,
                'bear_id' => $bearCerms->id
            ));
            Fish::create(array(
                'weight'  => 4,
                'bear_id' => $bearAdobot->id
            ));

            $this->command->info('They are eating fish!');

            // seed our trees table ---------------------
            Tree::create(array(
                'type'    => 'Redwood',
                'age'     => 500,
                'bear_id' => $bearLawly->id
            ));
            Tree::create(array(
                'type'    => 'Oak',
                'age'     => 400,
                'bear_id' => $bearLawly->id
            ));

            $this->command->info('Climb bears! Be free!');

            // seed our picnics table ---------------------

            // we will create one picnic and apply all bears to this one picnic
            $picnicYellowstone = Picnic::create(array(
                'name'        => 'Yellowstone',
                'taste_level' => 6
            ));
            $picnicGrandCanyon = Picnic::create(array(
                'name'        => 'Grand Canyon',
                'taste_level' => 5
            ));

            // link our bears to picnics ---------------------
            // for our purposes we'll just add all bears to both picnics for our many to many relationship
            $bearLawly->picnics()->attach($picnicYellowstone->id);
            $bearLawly->picnics()->attach($picnicGrandCanyon->id);

            $bearCerms->picnics()->attach($picnicYellowstone->id);
            $bearCerms->picnics()->attach($picnicGrandCanyon->id);

            $bearAdobot->picnics()->attach($picnicYellowstone->id);
            $bearAdobot->picnics()->attach($picnicGrandCanyon->id);

            $this->command->info('They are terrorizing picnics!');

        }

    }

Seeding a Database with Relationships

In our seeder file, we are creating bears, fish, picnics, and linking many bears to one picnic.

Grabbing the ID of a Newly Created Record We need to grab the id of the inserted bears and picnic so we will save the record into a variable on creation. After doing this, we are able to pull the id using $bearLawly->id.

Why do we do this? Why do we pull the id of a newly created record? There are a few reasons for this. One, so we can create our relationships correctly. Second, after seeding your database multiple times, the id of your records will always be incrementing since that’s how we set up our database. As you can see in the picture below, the id of our bears are 10, 11, and 12. Dynamically creating our relationships instead of hardcoding in the id lets us not worry about messing with our seed files after they have been created.

With our seeder file ready to go, let’s go into the command line and execute our seeds.

php artisan db:seed

We can also look into our database and see the new records.

Just like that, we now have records in our database. We can finally get to the fun part and show off the true power of Eloquent! Finally!

Next, we will go through all the types of queries you can create with Eloquent and we will see how easy it is to query databases with one-to-one and many-to-many relationships.

Using Eloquent Querying our Database

With migrations and seeding finally done, we’ll go through some basic real-world scenarios where we would need to access the information we’ve just put into our new database.

With Eloquent, it is that easy to create records for our database. Just call your model and the function you need. It is also incredibly easy to read, update, or delete records out of our database. Let’s look at CRUD functionality with Eloquent.

CRUD With Eloquent

Creating Records

You’ve already seen how to create records since we used the ::create method in our seeders.

        // create a bear
        Bear::create(array(
            'name'         => 'Super Cool',
            'type'         => 'Black',
            'danger_level' => 1
        ));

        // alternatively you can create an object, assign values, then save
        $bear               = new Bear;

        $bear->name         = 'Super Cool';
        $bear->type         = 'Black';
        $bear->danger_level = 1;

        // save the bear to the database
        $bear->save();

In addition to the create method, you can also create a new object and assign different attributes to it. Once that is over you can call the save() function.

Another method for creation is using firstOrCreate() or firstOrNew(). These will let us try to find a bear with certain attributes, if that bear is not found, then we will either create it into the database or instantiate a new instance.

        // find the bear or create it into the database
        Bear::firstOrCreate(array('name' => 'Lawly'));

        // find the bear or instantiate a new instance into the object we want
        $bear = Bear::firstOrNew(array('name' => 'Cerms'));

Getting and Finding Records

We can build all of our queries simply. Select statements, get alls, and finding records are all doable and easy.

Here are a few examples of use cases.

        // get all the bears
        $bears = Bear::all();

        // find a specific bear by id
        $bear = Bear::find(1);

        // find a bear by a specific attribute
        $bearLawly = Bear::where('name', '=', 'Lawly')->first();

        // find a bear with danger level greater than 5
        $dangerousBears = Bear::where('danger_level', '>', 5)->get();

First vs Get When querying the database and creating where statements, you will have to use get() or first(). First will return only one record and get will return an array of records that you will have to loop over.

Updating Records

To update a record, just find the record you’d like to update, change the attributes, and save. Super simple!

        // let's change the danger level of Lawly to level 10

        // find the bear
        $lawly = Bear::where('name', '=', 'Lawly')->first();

        // change the attribute
        $lawly->danger_level = 10;

        // save to our database
        $lawly->save();

Deleting Records

Deleting records might be easier than updating records. There are two methods: pull the record you want and delete it or just use the destroy method.

        // find and delete a record
        $bear = Bear::find(1);
        $bear->delete();

        // delete a record
        Bear::destroy(1);

        // delete multiple records
        Bear::destroy(1, 2, 3);

        // find and delete all bears with a danger level over 5
        Bear::where('danger_level', '>', 5)->delete();

Querying Relationships

Now, this is where Eloquent gets fun. With most applications, you will have relationships amongst the parts of your database. We have already defined these: bears will have one fish and picnics will have many bears.

One to One Relationship

Let’s see how we can use Eloquent to query these relationships and get our bears something to eat! Since we defined the relationships in our models, querying will be incredibly easy.

        // find a bear named Adobot
        $adobot = Bear::where('name', '=', 'Adobot')->first();

        // get the fish that Adobot has
        $fish = $adobot->fish;

        // get the weight of the fish Adobot is going to eat
        $fish->weight;

        // alternatively you could go straight to the weight attribute
        $adobot->fish->weight;

One to Many Relationships

For this example, let’s look at all the trees that our Lawly bear climbs.

        // find the trees lawly climbs
        $lawly = Bear::where('name', '=', 'Lawly')->first();

        foreach ($lawly->trees as $tree)
            echo $tree->type . ' ' . $tree->age;

Many to Many Relationship

For this example, we will get the picnics that our Cerms bear goes to. We can also get all the bears that go to the Yellowstone picnic.

        // get the picnics that Cerms goes to ------------------------
        $cerms = Bear::where('name', '=', 'Cerms')->first();

        // get the picnics and their names and taste levels
        foreach ($cerms->picnics as $picnic)
            echo $picnic->name . ' ' . $picnic->taste_level;

        // get the bears that go to the Grand Canyon picnic -------------
        $grandCanyon = Picnic::where('name', '=', 'Grand Canyon')->first();

        // show the bears
        foreach ($grandCanyon->bears as $bear)
            echo $bear->name . ' ' . $bear->type . ' ' . $bear->danger_level;

As you can see, by setting up our Eloquent Models, we can easily query our database.

Demonstration

Let’s show all this off in an actual view file so we can see how we pass this data to our Laravel view. What good is all this work if we don’t show our users right?

We will need two things: a route and a view file. Let’s run through these quickly to show off all the great Eloquent things we just learned.

Our Route

    // app/routes.php

    ...
        // create our route, return a view file (app/views/eloquent.blade.php)
        // we will also send the records we want to the view

        Route::get('eloquent', function() {

            return View::make('eloquent')

                // all the bears (will also return the fish, trees, and picnics that belong to them)
                ->with('bears', Bear::all()->with('trees', 'picnics'));

        });

Our View File

We will use Laravel Blade Templating to loop through our data and show it off in our view now. Let’s create our view file at app/views/eloquent.blade.php.

    <!-- app/views/eloquent.blade.php -->

    <!doctype html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>Eloquent Bears</title>

        <!-- CSS -->
        <!-- BOOTSTRAP -->
        <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css">
        <style>
            body { padding-top:50px; } /* add some padding to the top of our site */
        </style>
    </head>
    <body class="container">
    <div class="col-sm-8 col-sm-offset-2">

        <!-- BEARS -->
        <!-- loop over the bears and show off some things -->
        @foreach ($bears as $bear)

            <!-- GET OUR BASIC BEAR INFORMATION -->
            <h2>{{ $bear->name }} <small>{{ $bear->type }}: Level {{ $bear->danger_level }}</small></h2>

            <!-- SHOW OFF THE TREES -->
            <h4>Trees</h4>
            @foreach ($bear->trees as $tree)
                <p>{{ $tree->type }}</p>
            @endforeach

            <!-- SHOW OFF THE PICNICS -->
            <h4>Picnics</h4>
            @foreach ($bear->picnics as $picnic)
                <p>{{ $picnic->name }}: Taste Level {{ $picnic->taste_level }}</p>
            @endforeach

        @endforeach

    </div>
    </body>
    </html>

Now when you go view your app in your browser at: http://example.com/eloquent, you will see all the data being pulled from your database.

Conclusion

Well, that was a lot of information! Thanks for reading along and hopefully all this information has given you a good primer on how to use Eloquent for a real-world application. We’ve gone through:

Migrations
Eloquent models
Seeding
Defining relationships
Querying our database
Querying relationships

While we have covered a good many topics, there is still so much more you can do when dealing with databases in your application. For more information, I always encourage reading through all the Eloquent docs. You can dive into things like pivot tables, polymorphic relationships, advanced querying, and so much more.

Also, for more reading on actual applications that use the database, check out our tutorial on Laravel CRUD with Resource Controllers.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about our products