MongoDB\Collection::findOneAndReplace()

本页面内容

定义

参数
返回值
错误/异常
行为
示例
另请参阅

定义

MongoDB\Collection::findOneAndReplace()

查找匹配查询的单个文档并替换它。

function findOneAndReplace(
    array|object $filter,
    array|object $replacement,
    array $options = []
): object|null

参数

$filter : array|object

指定要替换的文档的过滤条件。

$replacement : array|object

替换文档。

$options : array

指定所需选项的数组。

名称	类型	描述
bypassDocumentValidation	布尔型	如果为 `true`，允许写操作绕过文档级别验证。默认为 `false`。
codec	MongoDB\Codec\DocumentCodec	用于编码或解码文档的编解码器。此选项与 `typeMap` 选项互斥。默认为集合的编解码器。默认 `codec` 选项的继承优先于 `typeMap` 选项。新功能版本1.17.
collation	array\|object	排序规则允许用户指定特定语言的字符串比较规则，例如字母大小写和重音符号的规则。在指定排序规则时，`locale`字段是必需的；所有其他排序规则字段都是可选的。有关字段的说明，请参阅排序规则文档。如果未指定排序规则，但集合有默认排序规则，则操作使用集合指定的排序规则。如果集合或操作未指定排序规则，MongoDB将使用先前版本中用于字符串比较的简单二进制比较。
注释	混合	启用用户指定任意注释以帮助通过数据库分析器、当前操作输出和日志追踪操作。此选项自MongoDB 4.4起可用，如果为旧服务器版本指定，则在执行时将引发异常。新功能版本1.13.
提示	字符串\|数组\|对象	要使用的索引。指定索引名称作为字符串或索引键模式作为文档。如果指定，则查询系统将仅考虑使用提示索引的计划。此选项自MongoDB 4.4起可用，如果为旧服务器版本指定，则在执行时将引发异常。新功能版本1.7.
let	array\|object	参数名称和值的映射。值必须是常量或封闭表达式，不能引用文档字段。参数然后可以作为聚合表达式上下文中的变量访问（例如，`$$var`）。此功能不支持旧于5.0的服务器版本，如果使用则会在执行时引发异常。新功能版本1.13.
maxTimeMS	整数	处理游标上的操作的总时间限制（以毫秒为单位）。MongoDB将在最早的中断点后终止操作。
投影	array\|object	确定返回文档中包含哪些字段的投影规范。请参阅MongoDB手册中的从查询结果中投影字段和投影运算符。
returnDocument	整数	指定是否在应用替换前或应用替换后返回文档。`returnDocument`支持以下值 `MongoDB\Operation\FindOneAndReplace::RETURN_DOCUMENT_BEFORE` （默认值） `MongoDB\Operation\FindOneAndReplace::RETURN_DOCUMENT_AFTER`
会话	MongoDB\Driver\Session	与操作关联的客户端会话。新功能版本1.3.
排序	array\|object	结果的排序规范。
typeMap	数组	将类型映射应用于游标，这决定了BSON文档如何转换为PHP值。默认为集合的类型映射。这将用于返回的结果文档。
upsert	布尔型	如果设置为`true`，当没有文档匹配查询条件时创建新文档。默认值是`false`，表示当没有找到匹配项时不会插入新文档。
writeConcern	MongoDB\Driver\WriteConcern	写入关注用于操作的。默认为集合的写入关注。在事务中无法为单个操作指定写入关注。相反，在开始事务时设置`writeConcern`选项。

返回值

一个数组对象，表示原始文档或替换的文档，具体取决于 returnDocument 选项指定的值。默认情况下，返回原始文档。如果没有文档与查询匹配，则返回 null。返回类型将取决于 typeMap 选项。

错误/异常

MongoDB\Exception\UnexpectedValueException 如果服务器命令响应格式不正确。

MongoDB\Exception\UnsupportedException 如果使用了所选服务器不支持选项（例如 collation、readConcern、writeConcern）。

MongoDB\Exception\InvalidArgumentException 与参数或选项解析相关的错误。

MongoDB\Driver\Exception\RuntimeException用于扩展级别的其他错误（例如连接错误）。

行为

When evaluating query criteria, MongoDB compares types and values according to its own comparison rules for BSON types, which differs from PHP's comparison and type juggling rules. When matching a special BSON type the query criteria should use the respective BSON class in the extension (e.g. use MongoDB\BSON\ObjectId to match an ObjectId).

示例

以下示例在restaurants集合和test数据库中

{
  "_id" : ObjectId("576023c7b02fa9281da4139e"),
  "address" : {
    "building" : "977",
    "coord" : [
      -74.06940569999999,
      40.6188443
    ],
    "street" : "Bay Street",
    "zipcode" : "10305"
  },
  "borough" : "Staten Island",
  "cuisine" : "French",
  "grades" : [
    {
      "date" : ISODate("2014-08-15T00:00:00Z"),
      "grade" : "A",
      "score" : 7
    },
    {
      "date" : ISODate("2014-02-13T00:00:00Z"),
      "grade" : "A",
      "score" : 5
    },
    {
      "date" : ISODate("2013-06-07T00:00:00Z"),
      "grade" : "A",
      "score" : 11
    }
  ],
  "name" : "Zest",
  "restaurant_id" : "41220906"
}

以下操作用新文档替换具有restaurant_id为"41220906"的文档

<?php
$collection = (new MongoDB\Client)->teset->restaurants;
$replacedRestaurant = $collection->findOneAndReplace(
    [ 'restaurant_id' => '41220906' ],
    [
        'Borough' => 'Staten Island',
        'cuisine' => 'Italian',
        'grades' => [],
        'name' => 'Staten Island Pastaria',
        'restaurant_id' => '999999999',
    ],
    [ 'returnDocument' => MongoDB\Operation\FindOneAndReplace::RETURN_DOCUMENT_AFTER ]
);
var_dump($replacedRestaurant);

输出结果将类似

object(MongoDB\Model\BSONDocument)#18 (1) {
  ["storage":"ArrayObject":private]=>
  array(6) {
    ["_id"]=>
    object(MongoDB\BSON\ObjectId)#11 (1) {
      ["oid"]=>
      string(24) "594d5ef380a846852a4b5837"
    }
    ["Borough"]=>
    string(13) "Staten Island"
    ["cuisine"]=>
    string(7) "Italian"
    ["grades"]=>
    object(MongoDB\Model\BSONArray)#17 (1) {
      ["storage":"ArrayObject":private]=>
      array(0) {
      }
    }
    ["name"]=>
    string(22) "Staten Island Pastaria"
    ["restaurant_id"]=>
    string(9) "999999999"
  }
}

另请参阅

MongoDB Collection::findOneAndDelete()
MongoDB Collection::findOneAndUpdate()
findAndModify 命令参考，MongoDB 手册

findOneAndDelete()

findOneAndUpdate()