Eloquent Model Class

Overview

This guide shows you how to use the Laravel MongoDB package to define and customize Laravel Eloquent models. You can use these models to work with MongoDB data by using the Laravel Eloquent object-relational mapper (ORM).

The following sections explain how to add Laravel Eloquent ORM behaviors to Laravel MongoDB models:

• Define an Eloquent Model Class demonstrates how to create a model class.

• Extend the Authenticatable Model shows how to set MongoDB as the authentication user provider.

• Customize an Eloquent Model Class explains several model class customizations.

• Specify Pruning Behavior shows how to periodically remove models that you no longer need.

Define an Eloquent Model Class

Eloquent models are classes that represent your data. They include methods that perform database operations such as inserts, updates, and deletes.

To declare a Laravel MongoDB model, create a class in the app/Models directory of your Laravel application that extends MongoDB\Laravel\Eloquent\Model as shown in the following code example:

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
}

By default, the model uses the MongoDB database name set in your Laravel application's config/database.php setting and the snake case plural form of your model class name for the collection.

This model is stored in the planets MongoDB collection.

To learn how to specify the database name that your Laravel application uses, Configure Your MongoDB Connection.

Extend the Authenticatable Model

To configure MongoDB as the Laravel user provider, you can extend the Laravel MongoDB MongoDB\Laravel\Auth\User class. The following code example shows how to extend this class:

<?php
namespace App\Models;
use MongoDB\Laravel\Auth\User as Authenticatable;
class User extends Authenticatable
{
}

To learn more about customizing a Laravel authentication user provider, see Adding Custom User Providers in the Laravel docs.

Customize an Eloquent Model Class

This section shows how to perform the following Eloquent model behavior customizations:

• Change the Model Collection Name

• Change the Primary Key Field

• Enable Soft Deletes

• Cast Data Types

• Customize Mass Assignment

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
    protected $collection = 'celestial_body';
}

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
    protected $primaryKey = 'name';
}

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
use MongoDB\Laravel\Eloquent\SoftDeletes;
class Planet extends Model
{
    use SoftDeletes;
}

Cast Data Types

Eloquent lets you convert model attribute data types before storing or retrieving data by using a casting helper. This helper is a convenient alternative to defining equivalent accessor and mutator methods on your model.

In the following example, the casting helper converts the discovery_dt model attribute, stored in MongoDB as a MongoDB\BSON\UTCDateTime type, to the Laravel datetime type.

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
    protected $casts = [
        'discovery_dt' => 'datetime',
    ];
}

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

This conversion lets you use the PHP DateTime or the Carbon class to work with dates in this field. The following example shows a Laravel query that uses the casting helper on the model to query for planets with a discovery_dt of less than three years ago:

Planet::where( 'discovery_dt', '>', new DateTime('-3 years'))->get();

To learn more about MongoDB's data types, see BSON Types in the MongoDB server docs.

To learn more about the Laravel casting helper and supported types, see Attribute Casting in the Laravel docs.

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
    protected $fillable = [
        'name',
        'gravitational_force',
        'diameter',
        'moons',
    ];
}

$planets = [
    [ 'name' => 'Earth', 'gravitational_force' => 9.8, 'day_length' => '24 hours' ],
    [ 'name' => 'Mars', 'gravitational_force' => 3.7, 'day_length' => '25 hours' ],
];
Planet::create($planets);

Specify Pruning Behavior

Eloquent lets you specify criteria to periodically delete model data that you no longer need. When you schedule or run the model:prune command, Laravel calls the prunable() method on all models that import the Prunable and MassPrunable traits to match the models for deletion.

To use this feature with models that use MongoDB as a database, add the appropriate import to your model:

• MongoDB\Laravel\Eloquent\Prunable optionally performs a cleanup step before deleting a model that matches the criteria

• MongoDB\Laravel\Eloquent\MassPrunable deletes models that match the criteria without fetching the model data

To learn more about the pruning feature, see Pruning Models in the Laravel docs.

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
use MongoDB\Laravel\Eloquent\Prunable;
class Planet extends Model
{
    use Prunable;
    public function prunable()
    {
        // matches models in which the solar_system field contains a null value
        return static::whereNull('solar_system');
    }
    protected function pruning()
    {
        // Add cleanup actions, such as logging the Planet 'name' attribute
    }
}

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\MassPrunable;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
    use MassPrunable;
    public function prunable()
    {
        // matches models in which the gravitational_force field contains
        // a value greater than 0.5
        return static::where('gravitational_force', '>', 0.5);
    }
}