Eloquent Model Class

Change the Model Collection Name

By default, the model uses the snake case plural form of your model class name. To change the name of the collection the model uses to retrieve and save data in MongoDB, override the $collection property of the model class.

The following example specifies the custom MongoDB collection name, celestial_body, for the Planet class:

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

Without overriding the $collection property, this model maps to the planets collection. With the overridden property, the example class stores the model in the celestial_body collection.

Change the Primary Key Field

To customize the model's primary key field that uniquely identifies a MongoDB document, override the $primaryKey property of the model class.

By default, the model uses the PHP MongoDB driver to generate unique ObjectIDs for each document your Laravel application inserts.

The following example specifies the name field as the primary key for the Planet class:

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

To learn more about primary key behavior and customization options, see Eloquent Primary Keys in the Laravel docs.

To learn more about the _id field, ObjectIDs, and the MongoDB document structure, see Documents in the MongoDB server docs.

Enable Soft Deletes

Eloquent includes a soft delete feature that changes the behavior of the delete() method on a model. When soft delete is enabled on a model, the delete() method marks a document as deleted instead of removing it from the database. It sets a timestamp on the deleted_at field to exclude it from retrieve operations automatically.

To enable soft deletes on a class, add the MongoDB\Laravel\Eloquent\SoftDeletes trait as shown in the following code example:

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

To learn about methods you can perform on models with soft deletes enabled, see Eloquent Soft Deleting in the Laravel docs.

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.

Customize Mass Assignment

Eloquent lets you create several models and their attribute data by passing an array of data to the create() model method. This process of inserting multiple models is called mass assignment.

Mass assignment can be an efficient way to create multiple models. However, it can expose an exploitable security vulnerability. The data in the fields might contain updates that lead to unauthorized permissions or access.

Eloquent provides the following traits to protect your data from mass assignment vulnerabilities:

• $fillable contains the fields that are writeable in a mass assignment

• $guarded contains the fields that are ignored in a mass assignment

In the following example, the model allows mass assignment of the fields by using the $fillable attribute:

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

The following code example shows mass assignment of the Planet model:

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

The models saved to the database contain only the name and gravity fields since day_length is omitted from the $fillable attribute.

To learn how to change the behavior when attempting to fill a field omitted from the $fillable array, see Mass Assignment Exceptions in the Laravel docs.

Extended Class Example

This example creates a Planet model class that extends the CelestialBody class from a package called ThirdPartyPackage. The Post class includes the DocumentModel trait and defines properties including $primaryKey and $keyType:

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\DocumentModel;
use ThirdPartyPackage\CelestialBody;
class Planet extends CelestialBody
{
    use DocumentModel;
    protected $fillable = ['name', 'diameter'];
    protected $primaryKey = '_id';
    protected $keyType = 'string';
}

After defining your class, you can perform MongoDB operations as usual.

Prunable Example

The following prunable class includes a prunable() method that matches models that the prune action deletes and a pruning() method that runs before deleting a matching model:

<?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
    }
}

Mass Prunable Example

The following mass prunable class includes a prunable() method that matches models that the prune action deletes:

<?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);
    }
}

Schema Versioning Example

In this sample situation, you are working with a collection that was first modeled by the following class:

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

Now, you want to implement a new schema version on the collection. You can define the new model class with the following behavior:

• Implements the HasSchemaVersion trait and sets the current SCHEMA_VERSION to 2

• Defines the migrateSchema() method to migrate models in which the schema version is less than 2 to have a galaxy field that has a value of 'Milky Way'

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\HasSchemaVersion;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
    use HasSchemaVersion;
    public const SCHEMA_VERSION = 2;
    protected $fillable = ['name', 'type', 'galaxy'];
    /**
     * Migrate documents with a lower schema version to the most current
     * schema when inserting new data or retrieving from the database.
     */
    public function migrateSchema(int $fromVersion): void
    {
        if ($fromVersion < 2) {
            $this->galaxy = 'Milky Way';
        }
    }
}

In the "WASP-39 b" document in the following code, the schema_version field value is less than 2. When you retrieve the document, Laravel MongoDB adds the galaxy field and updates the schema version to the current version, 2.

The "Saturn" document does not contain the schema_version field, so Laravel MongoDB assigns it the current schema version upon saving.

Finally, the code retrieves the models from the collection to demonstrate the changes:

// Simulates a document in the collection with schema version 1
Planet::insert([
    [
        'name' => 'WASP-39 b',
        'type' => 'gas',
        'schema_version' => 1,
    ],
]);
// Saves a document with no specified schema version
$saturn = Planet::create([
    'name' => 'Saturn',
    'type' => 'gas',
]);
// Retrieves both models from the collection
$planets = Planet::where('type', 'gas')
    ->get();