Modify Documents

Overview

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

<?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'];
}

Update One Document

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]);

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

Update Multiple Documents

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

Update or Insert in a Single Operation

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.

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

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": ...
}

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

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": ...
}

Update Arrays in a Document

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

• Add values to an array

• Remove values from an array

• Update the value of an array element

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

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

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

Concert::where('performer', 'Mitsuko Uchida')
    ->push(
        'genres',
        ['baroque'],
    );

{
  "_id": "660eb...",
  "performer": "Mitsuko Uchida",
  "genres": [
      "classical",
      "dance-pop",
  ],
  "updated_at": ...,
  "created_at": ...
}

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

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

{
  "_id": "660e...",
  "performer": "Mitsuko Uchida",
  "genres": [],
  "updated_at": ...,
  "created_at": ...
}

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

$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": ...
}

Additional Information

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

• Update a Document

• Update Multiple Documents

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