写入操作

示例模型

本指南中的写入操作引用了以下 Eloquent 模型类：

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

插入文档示例

这些示例展示了如何使用save() Eloquent 方法将Concert模型的实例作为 MongoDB 文档插入。

当save()方法成功时，您可以访问权限调用该方法的模型实例。

如果操作失败，则会为模型实例分配null 。

此示例代码执行以下操作：

• 创建Concert模型的新实例

• 为 performer 和 venue 字段分配string值

• 将字符串数组赋值给genre字段

• 为ticketsSold字段分配一个数字

• 使用Carbon包为performanceDate字段分配日期

• 通过调用save()方法插入文档

$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();

您可以通过访问模型的id成员来检索插入文档的_id值，如以下代码示例所示：

$insertedId = $concert->id;

如果通过定义$fillable或$guarded属性来启用批量分配，则可以使用 Eloquent 模型的create()方法在单次调用中执行插入，如以下示例所示：

$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'),
]);

要了解有关CarbonPHPAPI 扩展的更多信息，请参阅 CarbonGithub 存储库。

插入多个文档示例

此示例演示如何使用insert() Eloquent 方法将Concert模型的多个实例作为MongoDB文档插入。 这种批量插入方法减少了应用程序为保存文档所需进行的调用次数。

当insert()方法成功时，将返回值1 。

如果失败，则会引发异常。

示例代码将多个模型作为数组传递给insert()方法，从而在一次调用中保存多个模型：

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

更新文档示例

您可以通过以下方式更新文档：

• 修改模型实例，并通过调用save()方法保存更改。

• 用于检索模型实例并通过调用update()方法对其执行更新的链式方法。

以下示例展示了如何通过修改模型实例并调用其save()方法来更新文档：

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

当save()方法成功时，调用该方法的模型实例将包含更新的值。

如果操作失败，Laravel 集成将为模型实例分配null值。

以下示例展示了如何通过链接检索和更新第一个匹配文档的方法来更新文档：

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

当update()方法成功时，该操作将返回已更新的文档数。

如果调用的检索部分与任何文档都不匹配，Laravel 集成将返回以下错误：

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

更新多个文档示例

要对一个或多个文档执行更新，请将update()方法链接到将文档检索为 Laravel 集合对象的方法的结果，例如where() 。

以下示例展示了如何链式调用以检索和更新匹配文档：

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

当update()方法成功时，该操作将返回已更新的文档数。

如果调用的检索部分与集合中的任何文档都不匹配，则 Laravel 集成将返回以下错误：

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

更新或插入方法

upsert(array $values, array|string $uniqueBy, array|null $update) 方法接受以下参数：

• $values：指定要更新或插入的文档的字段和值的数组。

• $uniqueBy：唯一标识第一个大量参数中的文档的字段列表。

• $update：存在匹配文档时要更新的可选字段列表。 如果省略此参数，Laravel 集成将更新所有字段。

要在upsert()方法中指定更新或插入（upsert）或插入，请按以下代码示例所示设立参数：

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

更新方法

要在update()方法中指定更新或插入，请将upsert选项设置为true ，如以下代码示例所示：

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

当update()方法链接到查询时，它会执行以下操作之一：

• 如果查询与文档匹配，则update()方法会修改匹配的文档。

• 如果查询匹配零个文档，则update()方法将插入一个包含更新数据和等值匹配条件数据的文档。

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

向数组添加值示例

本部分介绍如何使用push()方法向 MongoDB 文档中的数组添加值。 您可以传递一个或多个要添加的值，并将可选参数unique设置为true ，以跳过在数组中添加任何重复值的过程。 以下代码示例显示了push()方法调用的结构：

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

以下示例演示如何将值"baroque"添加到匹配文档的genres数组字段。 单击VIEW OUTPUT按钮查看更新后的文档：

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

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

从数组中删除值示例

本部分介绍如何使用pull()方法从 MongoDB 文档的数组中删除值。 您可以传递一个或多个要从数组中删除的值。 以下代码示例显示了pull()方法调用的结构：

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

以下示例演示如何从genres数组字段中删除数组值"classical"和"dance-pop" 。 单击VIEW OUTPUT按钮查看更新后的文档：

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

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

更新数组元素值示例

本部分介绍如何使用$位置运算符更新 MongoDB 文档中的特定数组元素。 $操作符表示与查询匹配的第一个数组元素。 以下代码示例显示了对单个匹配文档进行位置操作符更新调用的结构：

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

以下示例演示如何在genres数组字段中将数组值"dance-pop"替换为"contemporary" 。 单击VIEW OUTPUT按钮查看更新后的文档：

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

要了解有关数组更新操作符的更多信息，请参阅 MongoDB Server手册中的 数组更新操作符 。

删除文档示例

您可以通过以下方式删除一个文档：

• 对模型的实例调用$model->delete()方法。

• 在模型上调用Model::destroy($id)方法，向其传递要删除的文档的 ID。

• 通过调用delete()方法来检索和删除模型实例的链式方法。

以下示例展示了如何通过对该模型的实例调用$model->delete()来删除文档：

$concert = Concert::first();
$concert->delete();

当delete()方法成功时，该操作将返回已删除的文档数。

如果调用的检索部分与集合中的任何文档都不匹配，则该操作将返回0 。

以下示例展示了如何通过将文档 ID 的值传递给Model::destroy($id)方法来删除除文档：

$id = 'MSG-0212252000';
Concert::destroy($id);

当destroy()方法成功时，它会返回已删除的文档数。

如果ID值与任何文档都不匹配，则 destroy() 方法返回 0。

以下示例展示了如何链式调用以检索第一个匹配文档并将其删除：

Concert::where('venue', 'Carnegie Hall')
    ->limit(1)
    ->delete();

当delete()方法成功时，它会返回已删除的文档数。

如果where()方法未匹配任何文档， delete()方法将返回0 。

删除多个文档示例

您可以通过以下方式删除多个文档：

• 调用Model::destroy($ids)方法，传递要删除的文档或模型实例的 ID 列表。

• 链式方法以检索引用多个对象的 Laravel 集合对象，并通过调用delete()方法删除它们。

以下示例展示了如何通过将由 $ids 表示的ID值大量传递给 destroy() 方法来删除除文档：

$ids = [3, 5, 7, 9];
Concert::destroy($ids);

当destroy()方法成功时，它会返回已删除的文档数。

如果 ID 值与任何文档都不匹配，则destroy()方法返回0 。

以下示例展示了如何链式调用以检索匹配的文档并将其删除：

Concert::where('ticketsSold', '>', 7500)
    ->delete();

当delete()方法成功时，它会返回已删除的文档数。

如果where()方法未匹配任何文档， delete()方法将返回0 。