Laravel TutorialChange default routing behaviour in Laravel 5.2.31 +CustomException class in LaravelDeploy Laravel 5 App on Shared Hosting on Linux ServerLaravel ArtisanLaravel AuthenticationLaravel AuthorizationLaravel Blade TemplatesLaravel CashierLaravel CollectionsLaravel Common Issues & Quick FixesLaravel ConstantsLaravel ControllersLaravel Cron basicsLaravel Cross Domain RequestLaravel Custom Helper functionLaravel DatabaseLaravel Database MigrationsLaravel Database SeedingLaravel Directory StructureLaravel DockerLaravel EloquentLaravel Eloquent : RelationshipLaravel Eloquent: Accessors & MutatorsLaravel Eloquent: ModelLaravel Error HandlingLaravel Events and ListenersLaravel Filesystem / Cloud StorageLaravel Form Request(s)Laravel Getting started with laravel-5.3Laravel HelpersLaravel HTML and Form BuilderLaravel InstallationLaravel Installation GuideLaravel Introduction to laravel-5.2Laravel Introduction to laravel-5.3Laravel lumen frameworkLaravel Macros in Eloquent RelationshipLaravel MailLaravel MiddlewareLaravel ObserverLaravel PackagesLaravel PaginationLaravel Permissions for storageLaravel PoliciesLaravel QueuesLaravel RequestsLaravel Route Model BindingLaravel RoutingLaravel SeedingLaravel ServicesLaravel SocialiteLaravel Task SchedulingLaravel TestingLaravel Token Mismatch Error in AJAXLaravel use fields aliases in EloquentLaravel Useful linksLaravel ValetLaravel ValidationMultiple DB Connections in LaravelNaming Files when uploading with Laravel on WindowsRemove public from URL in laravelSparkpost integration with Laravel 5.4

Laravel Eloquent

From WikiOD

The Eloquent is an ORM (Object Relational Model) included with the Laravel. It implements the active record pattern and is used to interact with relational databases.

Remarks[edit | edit source]

Table naming

The convention is to use pluralised “snake_case” for table names and singular “StudlyCase” for model names. For example:

  • A cats table would have a Cat model
  • A jungle_cats table would have a JungleCat model
  • A users table would have a User model
  • A people table would have a Person model

Eloquent will automatically try to bind your model with a table that has the plural of the name of the model, as stated above.

You can, however, specify a table name to override the default convention.

class User extends Model
    protected $table = 'customers';

Introduction[edit | edit source]

Eloquent is the ORM built into the Laravel framework. It allows you to interact with your database tables in an object-oriented manner, by use of the ActiveRecord pattern.

A single model class usually maps to a single database table, and also relationships of different types (one-to-one, one-to-many, many-to-many, polymorphic) can be defined between different model classes.

Section Making a Model describes the creation and definition of model classes.

Before you can start using Eloquent models, make sure at least one database connection has been configured in your config/database.php configuration file.

To understand usage of eloquent query builder during development you may use php artisan ide-helper:generate command. Here is the link.

Sub-topic Navigation[edit | edit source]

Eloquent Relationship

Deleting[edit | edit source]

You can delete data after writing it to the database. You can either delete a model instance if you have retrieved one, or specify conditions for which records to delete.

To delete a model instance, retrieve it and call the delete() method:

$user = User::find(1);

Alternatively, you can specify a primary key (or an array of primary keys) of the records you wish to delete via the destroy() method:

User::destroy([1, 2, 3]);

You can also combine querying with deleting:

User::where('age', '<', 21)->delete();

This will delete all users who match the condition.

Note: When executing a mass delete statement via Eloquent, the deleting and deleted model events will not be fired for the deleted models. This is because the models are never actually retrieved when executing the delete statement.

Soft Deleting[edit | edit source]

Some times you don’t want to permanently delete a record, but keep it around for auditing or reporting purposes. For this, Eloquent provides soft deleting functionality.

To add soft deletes functionality to your model, you need to import the SoftDeletes trait and add it to your Eloquent model class:

namespace Illuminate\Database\Eloquent\Model;
namespace Illuminate\Database\Eloquent\SoftDeletes;

class User extends Model
     use SoftDeletes;

When deleting a model, it will set a timestamp on a deleted_at timestamp column in the table for your model, so be sure to create the deleted_at column in your table first. Or in migration you should call softDeletes() method on your blueprint to add the deleted_at timestamp. Example:

Schema::table('users', function ($table) {

Any queries will omit soft-deleted records. You can force-show them if you wish by using the withTrashed() scope:


If you wish to allow users to restore a record after soft-deleting (i.e. in a trash can-type area) then you can use the restore() method:

$user = User::find(1);

To forcefully delete a record use the forceDelete() method which will truly remove the record from the database:

$user = User::find(1);

Change primary key and timestamps[edit | edit source]

By default, Eloquent models expect for the primary key to be named 'id'. If that is not your case, you can change the name of your primary key by specifying the $primaryKey property.

class Citizen extends Model
    protected $primaryKey = 'socialSecurityNo';

    // ...

Now, any Eloquent methods that use your primary key (e.g. find or findOrFail) will use this new name.

Additionally, Eloquent expects the primary key to be an auto-incrementing integer. If your primary key is not an auto-incrementing integer (e.g. a GUID), you need to tell Eloquent by updating the $incrementing property to false:

class Citizen extends Model
    protected $primaryKey = 'socialSecurityNo';

    public $incrementing = false;

    // ...

By default, Eloquent expects created_at and updated_at columns to exist on your tables. If you do not wish to have these columns automatically managed by Eloquent, set the $timestamps property on your model to false:

class Citizen extends Model
    public $timestamps = false;

    // ...

If you need to customize the names of the columns used to store the timestamps, you may set the CREATED_AT and UPDATED_AT constants in your model:

class Citizen extends Model
    const CREATED_AT = 'date_of_creation';
    const UPDATED_AT = 'date_of_last_update';

    // ...

Persisting[edit | edit source]

In addition to reading data with Eloquent, you can also use it to insert or update data with the save() method. If you have created a new model instance then the record will be inserted; otherwise, if you have retrieved a model from the database and set new values, it will be updated.

In this example we create a new User record:

$user = new User();
$user*>first_name = 'John';
$user*>last_name = 'Doe';
$user*>email = '';
$user*>password = bcrypt('my_password');

You can also use the create method to populate fields using an array of data:

    'first_name'=> 'John',
    'last_name' => 'Doe',
    'email'     => '', 
    'password'  => bcrypt('changeme'),

When using the create method your attributes should be declared in the fillable array within your model:

class User extends Model
    protected $fillable = [

Alternatively, if you would like to make all attributes mass assignable, you may define the $guarded property as an empty array:

class User extends Model
    * The attributes that aren't mass assignable.
    * @var array
    protected $guarded = [];

But you can also create a record without even changing fillable attribute in your model by using forceCreate method rather than create method

    'first_name'=> 'John',
    'last_name' => 'Doe',
    'email'     => '', 
    'password'  => bcrypt('changeme'),

The following is an example of updating an existing User model by first loading it (by using find), modifying it, and then saving it:

$user = User::find(1);
$user*>password = bcrypt('my_new_password');

To accomplish the same feat with a single function call, you may use the update method:

    'password' => bcrypt('my_new_password'),

The create and update methods make working with large sets of data much simpler than having to set each key/value pair individually, as shown in the following examples:

Note the use of only and except when gathering request data. It's important you specify the exact keys you want to allow/disallow to be updated, otherwise it's possible for an attacker to send additional fields with their request and cause unintended updates.

// Updating a user from specific request data
$data = Request::only(['first_name', 'email']);

// Create a user from specific request data
$data = Request::except(['_token', 'profile_picture', 'profile_name']);

Throw 404 if entity not found[edit | edit source]

If you want to automatically throw an exception when searching for a record that isn't found on a modal, you can use either



Vehicle::where('make', 'ford')->firstOrFail();

If a record with the primary key of 1 is not found, a ModelNotFoundException is thrown. Which is essentially the same as writing (view source):

$vehicle = Vehicle::find($id);

if (!$vehicle) {

Cloning Models[edit | edit source]

You may find yourself needing to clone a row, maybe change a few attributes but you need an efficient way to keep things DRY. Laravel provides a sort of 'hidden' method to allow you to do this functionality. Though it is completely undocumented, you need to search through the API to find it.

Using $model->replicate() you can easily clone a record

$robot = Robot::find(1);
$cloneRobot = $robot->replicate();
// You can add custom attributes here, for example he may want to evolve with an extra arm!
$cloneRobot*>arms += 1;

The above would find a robot that has an ID of 1, then clones it.