Insert Documents

On this page

Overview

Sample Model
Insert One Document
save() Method
create() Method
Insert Multiple Documents
Additional Information

Overview

In this guide, you can learn how to insert documents into MongoDB collections from your Laravel application by using Laravel MongoDB.

When you insert the documents, ensure the data does not violate any unique indexes on the collection. When inserting the first document of a collection or creating a new collection, MongoDB automatically creates a unique index on the _id field.

For more information on creating indexes on MongoDB collections by using the Laravel schema builder, see the Manage Indexes section of the Schema Builder documentation.

To learn more about Eloquent models in the Laravel Integration, see the Eloquent Models section.

Sample Model

The operations in this guide reference the following Eloquent model class:

Concert.php

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
class Concert extends Model
{
    protected $connection = 'mongodb';
    protected $fillable = ['performer', 'venue', 'genres', 'ticketsSold', 'performanceDate'];
    protected $casts = ['performanceDate' => 'datetime'];
}

Tip

The $fillable attribute lets you use Laravel mass assignment for insert operations. To learn more about mass assignment, see Customize Mass Assignment in the Eloquent Model Class documentation.

The $casts attribute instructs Laravel to convert attributes to common data types. To learn more, see Attribute Casting in the Laravel documentation.

Insert One Document

The examples in this section show how to use the save() and create() Eloquent methods to insert an instance of a Concert model as a MongoDB document.

save() Method

When the save() method succeeds, you can access the model instance on which you called the method.

If the operation fails, the model instance is assigned null.

This example code performs the following actions:

Creates a new instance of the Concert model
Assigns string values to the performer and venue fields
Assigns an array of strings to the genre field
Assigns a number to the ticketsSold field
Assigns a date to the performanceDate field by using the Carbon package
Inserts the document by calling the save() method

$concert = new Concert();
$concert->performer = 'Mitsuko Uchida';
$concert->venue = 'Carnegie Hall';
$concert->genres = ['classical'];
$concert->ticketsSold = 2121;
$concert->performanceDate = Carbon::create(2024, 4, 1, 20, 0, 0, 'EST');
$concert->save();

You can retrieve the inserted document's _id value by accessing the model's id member, as shown in the following code example:

$insertedId = $concert->id;

create() Method

If you enable mass assignment by defining either the $fillable or $guarded attributes, you can use the Eloquent model create() method to perform the insert in a single call, as shown in the following example:

$insertResult = Concert::create([
    'performer' => 'The Rolling Stones',
    'venue' => 'Soldier Field',
    'genres' => [ 'rock', 'pop', 'blues' ],
    'ticketsSold' => 59527,
    'performanceDate' => Carbon::create(2024, 6, 30, 20, 0, 0, 'CDT'),
]);

To learn more about the Carbon PHP API extension, see the Carbon GitHub repository.

Insert Multiple Documents

This example shows how to use the insert() Eloquent method to insert multiple instances of a Concert model as MongoDB documents. This bulk insert method reduces the number of calls your application needs to make to save the documents.

When the insert() method succeeds, it returns the value 1. If it fails, it throws an exception.

The following example saves multiple models in a single call by passing them as an array to the insert() method:

$data = [
    [
        'performer' => 'Brad Mehldau',
        'venue' => 'Philharmonie de Paris',
        'genres' => [ 'jazz', 'post-bop' ],
        'ticketsSold' => 5745,
        'performanceDate' => new UTCDateTime(Carbon::create(2025, 2, 12, 20, 0, 0, 'CET')),
    ],
    [
        'performer' => 'Billy Joel',
        'venue' => 'Madison Square Garden',
        'genres' => [ 'rock', 'soft rock', 'pop rock' ],
        'ticketsSold' => 12852,
        'performanceDate' => new UTCDateTime(Carbon::create(2025, 2, 12, 20, 0, 0, 'CET')),
    ],
];
Concert::insert($data);

Note

This example wraps the dates in the MongoDB\BSON\UTCDateTime class to convert it to a type MongoDB can serialize because Laravel skips attribute casting on bulk insert operations.

Additional Information

To view runnable code examples that demonstrate how to insert documents by using the Laravel Integration, see the following usage examples:

To learn how to modify data that is already in MongoDB, see the Modify Documents guide.

Back

Write Operations

Modify