> This page location: /docs.md > /docs/drivers.md > /docs/languages/php.md > /docs/drivers/php/laravel-mongodb/current.md

> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Eloquent Model Class

## Overview

This guide shows you how to use Laravel MongoDB 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](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/model-data/model-class.md#std-label-laravel-model-define) demonstrates how to create a model class.

- [Extend the Authenticatable Model](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/model-data/model-class.md#std-label-laravel-authenticatable-model) shows how to set MongoDB as the authentication user provider.

- [Customize an Eloquent Model Class](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/model-data/model-class.md#std-label-laravel-model-customize) explains several model class customizations.

- [Extend Third-Party Model Classes](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/model-data/model-class.md#std-label-laravel-third-party-model) explains how to make third-party model classes compatible with MongoDB.

- [Specify Pruning Behavior](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/model-data/model-class.md#std-label-laravel-model-pruning) shows how to periodically remove models that you no longer need.

- [Create a Versioned Model Schema](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/model-data/model-class.md#std-label-laravel-schema-versioning) shows how to implement model schema versioning.

## 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
<?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.

**Tip:**

Alternatively, use the `artisan` console to generate the model class and change the `Illuminate\Database\Eloquent\Model` import to `MongoDB\Laravel\Eloquent\Model`. To learn more about the `artisan` console, see [Artisan Console](https://laravel.com/docs/12.x/artisan) in the Laravel docs.

To learn how to specify the database name that your Laravel application uses, [Configure Your MongoDB Connection.](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/get-started.md#std-label-laravel-quick-start-connect-to-mongodb)

**Note:**

MongoDB always stores a primary key value in the `_id` field. This field is accessed as `$id` in the model. When you use the query builder, the Laravel Integration converts `id` to `_id` in the query. This allows for compatibility with other Laravel components that use an `id` field. You can customize the identifier type by setting the `$keyType` property of the model and assigning a value before saving the model.

## Extend the Authenticatable Model

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

```php
<?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](https://laravel.com/docs/12.x/authentication#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 MongoDB Collection Name](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/model-data/model-class.md#std-label-laravel-model-customize-collection-name)

- [Enable Soft Deletes](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/model-data/model-class.md#std-label-laravel-model-soft-delete)

- [Cast Data Types](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/model-data/model-class.md#std-label-laravel-model-cast-data-types)

- [Customize Mass Assignment](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/model-data/model-class.md#std-label-laravel-model-mass-assignment)

**Note:**

A Laravel collection is a PHP class that holds a list of models, whereas a MongoDB collection stores documents in a database.

### Change the MongoDB Collection Name

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

**Note:**

We recommend using the default collection naming behavior to keep the associations between models and collections straightforward.

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

```php
<?php

namespace App\Models;

use MongoDB\Laravel\Eloquent\Model;

class Planet extends Model
{
    protected $table = 'celestial_body';
}

```

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

### 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 `Illuminate\Database\Eloquent\SoftDeletes` trait as shown in the following code example:

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\SoftDeletes;
use MongoDB\Laravel\Eloquent\Model;

class Planet extends Model
{
    use SoftDeletes;
}

```

To learn about methods you can perform on models with soft deletes enabled, see [Eloquent Soft Deleting](https://laravel.com/docs/12.x/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](https://php.net/class.mongodb-bson-utcdatetime) type, to the Laravel `datetime` type.

```php
<?php

namespace App\Models;

use MongoDB\Laravel\Eloquent\Model;

class Planet extends Model
{
    protected $casts = [
        'discovery_dt' => 'datetime',
    ];
}

```

**Tip: Casts in Laravel 11**

Starting in Laravel 11, you can define a `casts()` method to specify data type conversions instead of using the `$casts` attribute. The following code performs the same conversion as the preceding example by using a `casts()` method:

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

To learn more, see [Attribute Casting](https://laravel.com/docs/12.x/eloquent-mutators#attribute-casting) in the Laravel documentation.

This conversion lets you use the PHP [DateTime](https://php.net/class.datetime) 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:

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

**Note: Carbon Date Class**

Starting in Laravel MongoDB v5.0, `UTCDateTime` BSON values in MongoDB are returned as [Carbon](https://carbon.nesbot.com/) date classes in query results. The Laravel Integration applies the default timezone when performing this conversion.

To learn more about MongoDB data types, see [BSON Types](https://www.mongodb.com/docs/manual/reference/bson-types/) in the Server manual.

To learn more about the Laravel casting helper and supported types, see [Attribute Casting](https://laravel.com/docs/12.x/eloquent-mutators#attribute-casting) in the Laravel docs.

**Important:**

Starting in Laravel MongoDB v5.8, the `array` cast type is deprecated. Using `array` as a cast type stores attribute values as JSON-encoded strings in MongoDB, which is not the native BSON format. Starting in v5.9, you can use the `AsBsonArray` and `AsBsonDocument` cast types instead. To learn more, including migration options, see [Version 5.8 Deprecations.](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/upgrade.md#std-label-laravel-deprecations-v5.8)

The following example shows how to use the `AsBsonDocument` and `AsBsonArray` cast types in the `$casts` property of a model:

```php
use MongoDB\Laravel\Eloquent\Casts\AsBsonArray;
use MongoDB\Laravel\Eloquent\Casts\AsBsonDocument;
use MongoDB\Laravel\Eloquent\Model;

class BsonCasting extends Model
{
    protected $connection = 'mongodb';
    protected $fillable = ['specs', 'variants'];

    protected $casts = [
        'specs' => AsBsonDocument::class,
        'variants' => AsBsonArray::class,
    ];
}
```

### 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

**Important:**

We recommend using `$fillable` instead of `$guarded` to protect against vulnerabilities. To learn more about this recommendation, see the [Security Release: Laravel 6.18.35, 7.24.0](https://blog.laravel.com/security-release-laravel-61835-7240) article on the Laravel site.

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

```php
<?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:

```php
$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](https://laravel.com/docs/12.x/eloquent#mass-assignment-exceptions) in the Laravel docs.

## Extend Third-Party Model Classes

You can use the Laravel Integration to extend a third-party model class by including the `DocumentModel` trait when defining your model class. By including this trait, you can make the third-party class compatible with MongoDB.

When you apply the `DocumentModel` trait to a model class, you must set the  `$keyType` property to `'string'` as the Laravel Integration casts MongoDB `ObjectId` values to type `string`.

### 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
<?php

namespace App\Models;

use MongoDB\Laravel\Eloquent\DocumentModel;
use ThirdPartyPackage\CelestialBody;

class Planet extends CelestialBody
{
    use DocumentModel;

    protected $fillable = ['name', 'diameter'];
    protected $keyType = 'string';
}

```

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

**Tip:**

To view another example that uses the `DocumentModel` trait, see the [Laravel Sanctum](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/current/integrations/user-authentication.md#std-label-laravel-user-auth-sanctum) section of the User Authentication guide.

## 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:

- `Illuminate\Database\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

**Note:**

When enabling soft deletes on a mass prunable model, you must import the following Laravel MongoDB packages:

- `Illuminate\Database\Eloquent\SoftDeletes`

- `MongoDB\Laravel\Eloquent\MassPrunable`

To learn more about the pruning feature, see [Pruning Models](https://laravel.com/docs/12.x/eloquent#pruning-models) in the Laravel docs.

### 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
<?php

namespace App\Models;

use MongoDB\Laravel\Eloquent\Model;
use Illuminate\Database\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
<?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);
    }
}

```

## Create a Versioned Model Schema

You can implement a schema versioning pattern into your application by using the `HasSchemaVersion` trait on an Eloquent model. You might choose to implement a schema version to organize or standardize a MongoDB collection that contains data with different schemas.

**Tip:**

To learn more about schema versioning, see the [Model Data for Schema Versioning](https://www.mongodb.com/docs/manual/tutorial/model-data-for-schema-versioning/) tutorial in the Server manual.

To use this feature with models that use MongoDB as a database, add the `MongoDB\Laravel\Eloquent\HasSchemaVersion` import to your model. Then, set the `SCHEMA_VERSION` constant to `1` to set the first schema version on your MongoDB collection. If the collection evolves to contain multiple schemas, you can update the value of the `SCHEMA_VERSION` constant in subsequent model classes.

When creating your model, you can define the `migrateSchema()` method to specify a migration to the current schema version upon retrieving a model. In this method, you can specify the changes to make to an older model to update it to match the current schema version.

When you save a model that does not have a schema version specified, the `HasSchemaVersion` trait assumes that it follows the latest schema version. When you retrieve a model that does not contain the `schema_version` field, the trait assumes that its schema version is `0` and performs the migration.

### Schema Versioning Example

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

```php
<?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 MongoDB 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
<?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, the Laravel Integration 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 the Laravel Integration assigns it the current schema version upon saving.

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

```php
// 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();
```

**Output:**

```none
[
  {
    "_id": ...,
    "name": "WASP-39 b",
    "type": "gas",
    "galaxy": "Milky Way",
    "schema_version": 2,
  },
  {
    "_id": ...,
    "name": "Saturn",
    "type": "gas",
    "schema_version": 2,
  }
]
```
