Docs Menu
Docs Home
/ / /
Laravel MongoDB
/ /

Modify Documents

On this page

  • Overview
  • Sample Model
  • Update One Document
  • Update Multiple Documents
  • Update or Insert in a Single Operation
  • Upsert Method
  • Update Method
  • Update Arrays in a Document
  • Add Values to an Array Example
  • Remove Values From an Array Example
  • Update the Value of an Array Element Example
  • Additional Information

In this guide, you can learn how to modify documents in your MongoDB collection from your Laravel application by using Laravel MongoDB. Use update operations to modify existing documents or to insert a document if none match the search criteria.

You can persist changes on an instance of an Eloquent model or use Eloquent's fluent syntax to chain an update operation on methods that return a Laravel collection object.

This guide provides examples of the following update operations:

  • Update a document

  • Update multiple documents

  • Update or insert in a single operation

  • Update arrays in a document

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.

You can update a document in the following ways:

  • Modify an instance of the model and save the changes by calling the save() method.

  • Chain methods to retrieve an instance of a model and perform updates on it by calling the update() method.

The following example shows how to update a document by modifying an instance of the model and calling its save() method:

$concert = Concert::first();
$concert->venue = 'Manchester Arena';
$concert->ticketsSold = 9543;
$concert->save();

When the save() method succeeds, the model instance on which you called the method contains the updated values.

If the operation fails, the Laravel Integration assigns the model instance a null value.

The following example shows how to update a document by chaining methods to retrieve and update the first matching document:

$concert = Concert::where(['performer' => 'Brad Mehldau'])
->orderBy('id')
->first()
->update(['venue' => 'Manchester Arena', 'ticketsSold' => 9543]);

Note

The orderBy() call sorts the results by the _id field to guarantee a consistent sort order. To learn more about sorting in MongoDB, see the Natural order glossary entry in the Server manual.

When the update() method succeeds, the operation returns the number of documents updated.

If the retrieve part of the call does not match any documents, the Laravel Integration returns the following error:

Error: Call to a member function update() on null

To perform an update on one or more documents, chain the update() method to the results of a method that retrieves the documents as a Laravel collection object, such as where().

The following example shows how to chain calls to retrieve matching documents and update them:

Concert::whereIn('venue', ['Philharmonie de Paris', 'Soldier Field'])
->update(['venue' => 'Concertgebouw', 'ticketsSold' => 0]);

When the update() method succeeds, the operation returns the number of documents updated.

If the retrieve part of the call does not match any documents in the collection, the Laravel Integration returns the following error:

Error: Call to a member function update() on null

An upsert operation lets you perform an update or insert in a single operation. This operation streamlines the task of updating a document or inserting one if it does not exist.

Starting in v4.7, you can perform an upsert operation by using either of the following methods:

  • upsert(): When you use this method, you can perform a batch upsert to change or insert multiple documents in one operation.

  • update(): When you use this method, you must specify the upsert option to update all documents that match the query filter or insert one document if no documents are matched. Only this upsert method is supported in versions v4.6 and earlier.

The upsert() method accepts the following parameters:

  • $values: Array of fields and values that specify documents to update or insert.

  • $uniqueBy: One or more fields that uniquely identify documents in your first array parameter.

  • $update: Optional array of fields to update if a matching document exists. If you omit this parameter, the Laravel Integration updates all fields.

To specify an upsert in the upsert() method, pass the required parameters as shown in the following code example:

YourModel::upsert(
[/* documents to update or insert */],
'/* unique field */',
[/* fields to update */],
);

This example shows how to use the upsert() method to perform an update or insert in a single operation. Click the VIEW OUTPUT button to see the resulting data changes when there is a document in which the value of performer is 'Angel Olsen' in the collection already:

Concert::upsert([
['performer' => 'Angel Olsen', 'venue' => 'Academy of Music', 'ticketsSold' => 275],
['performer' => 'Darondo', 'venue' => 'Cafe du Nord', 'ticketsSold' => 300],
], 'performer', ['ticketsSold']);
{
"_id": "...",
"performer": "Angel Olsen",
"venue": "State Theatre",
"genres": [
"indie",
"rock"
],
"ticketsSold": 275,
"updated_at": ...
},
{
"_id": "...",
"performer": "Darondo",
"venue": "Cafe du Nord",
"ticketsSold": 300,
"updated_at": ...
}

In the document in which the value of performer is 'Angel Olsen', the venue field value is not updated, as the upsert specifies that the update applies only to the ticketsSold field.

To specify an upsert in an update() method, set the upsert option to true as shown in the following code example:

YourModel::where(/* match criteria */)
->update(
[/* update data */],
['upsert' => true]);

When the update() method is chained to a query, it performs one of the following actions:

  • If the query matches documents, the update() method modifies the matching documents.

  • If the query matches zero documents, the update() method inserts a document that contains the update data and the equality match criteria data.

This example shows how to pass the upsert option to the update() method to perform an update or insert in a single operation. Click the VIEW OUTPUT button to see the example document inserted when no matching documents exist:

Concert::where(['performer' => 'Jon Batiste', 'venue' => 'Radio City Music Hall'])
->update(
['genres' => ['R&B', 'soul'], 'ticketsSold' => 4000],
['upsert' => true],
);
{
"_id": "660c...",
"performer": "Jon Batiste",
"venue": "Radio City Music Hall",
"genres": [
"R&B",
"soul"
],
"ticketsSold": 4000,
"updated_at": ...
}

In this section, you can see examples of the following operations that update array values in a MongoDB document:

These examples modify the sample document created by the following insert operation:

Concert::create([
'performer' => 'Mitsuko Uchida',
'genres' => ['classical', 'dance-pop'],
]);

This section shows how to use the push() method to add values to an array in a MongoDB document. You can pass one or more values to add and set the optional parameter unique to true to skip adding any duplicate values in the array. The following code example shows the structure of a push() method call:

YourModel::where(<match criteria>)
->push(
<field name>,
[<values>], // array or single value to add
unique: true); // whether to skip existing values

The following example shows how to add the value "baroque" to the genres array field of a matching document. Click the VIEW OUTPUT button to see the updated document:

Concert::where('performer', 'Mitsuko Uchida')
->push(
'genres',
['baroque'],
);
{
"_id": "660eb...",
"performer": "Mitsuko Uchida",
"genres": [
"classical",
"dance-pop",
],
"updated_at": ...,
"created_at": ...
}

This section shows how to use the pull() method to remove values from an array in a MongoDB document. You can pass one or more values to remove from the array. The following code example shows the structure of a pull() method call:

YourModel::where(<match criteria>)
->pull(
<field name>,
[<values>]); // array or single value to remove

The following example shows how to remove array values "classical" and "dance-pop" from the genres array field. Click the VIEW OUTPUT button to see the updated document:

Concert::where('performer', 'Mitsuko Uchida')
->pull(
'genres',
['dance-pop', 'classical'],
);
{
"_id": "660e...",
"performer": "Mitsuko Uchida",
"genres": [],
"updated_at": ...,
"created_at": ...
}

This section shows how to use the $ positional operator to update specific array elements in a MongoDB document. The $ operator represents the first array element that matches the query. The following code example shows the structure of a positional operator update call on a single matching document:

Note

Currently, the Laravel Integration offers this operation only on the DB facade and not on the Eloquent ORM.

DB::connection('mongodb')
->getCollection(<collection name>)
->updateOne(
<match criteria>,
['$set' => ['<array field>.$' => <replacement value>]]);

The following example shows how to replace the array value "dance-pop" with "contemporary" in the genres array field. Click the VIEW OUTPUT button to see the updated document:

$match = ['performer' => 'Mitsuko Uchida', 'genres' => 'dance-pop'];
$update = ['$set' => ['genres.$' => 'contemporary']];
DB::connection('mongodb')
->getCollection('concerts')
->updateOne($match, $update);
{
"_id": "660e...",
"performer": "Mitsuko Uchida",
"genres": [
"classical",
"contemporary"
],
"updated_at": ...,
"created_at": ...
}

To learn more about array update operators, see Array Update Operators in the Server manual.

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

To learn how to insert documents into a MongoDB collection, see the Insert Documents guide.

Back

Insert