文档菜单
文档首页
/
语言
/
PHP
/
PHP 库手册
/
API 文档
/
MongoDB\Collection

MongoDB\Collection::watch()

本页内容

  • 定义
  • 参数
  • 返回值
  • 错误/异常
  • 示例
  • 另请参阅

新增在版本1.3.

定义

MongoDB\Collection::watch()

执行变更流操作。可以监视集合级别的更改。

function watch(
    array $pipeline = [],
    array $options = []
): MongoDB\ChangeStream

参数

$pipeline : 数组|对象
要附加到初始 $changeStream 阶段的阶段流程。
$options : 数组

指定所需选项的数组。

名称
类型
描述
batchSize
整数

指定游标的批大小，这将应用于初始 aggregate 命令和任何后续 getMore 命令。这决定了服务器每次响应中返回的更改事件的最多数量。

无论 batchSize 选项如何，更改流初始 aggregate 命令响应通常不包含任何文档，除非使用其他选项配置其起始点（例如 startAfter）。

codec
MongoDB\Codec\DocumentCodec

用于编码或解码文档的codec。此选项与 typeMap 选项互斥。

默认为集合的 codec。默认 codec 选项的继承优先于 typeMap 选项。

新增在版本1.17.

collation
数组|对象

Collation 允许用户指定字符串比较的语言特定规则，例如字母大小写和重音符号的规则。指定校对时，必须指定 locale 字段；所有其他校对字段都是可选的。有关字段的说明，请参阅 Collation Document。

从 MongoDB 4.2 开始，如果省略，则默认为简单的二进制比较。在早期版本中，在单个集合上打开的更改流将继承集合的默认校对。

comment
混合

允许用户指定任意注释，以帮助通过 database profiler、currentOp 输出和 logs 追踪操作。

从 MongoDB 4.4 开始，注释可以是任何有效的 BSON 类型。早期服务器版本仅支持字符串值。

新增在版本1.13.

fullDocument
字符串

确定对于更新操作，如何填充 fullDocument 响应字段。

默认情况下，更改流仅返回更新操作的字段增量（通过一个updateDescription字段）并省略fullDocument。插入和替换操作始终包含fullDocument字段。删除操作省略字段，因为文档不再存在。

指定“updateLookup”以返回更新文档的当前多数提交版本。

MongoDB 6.0+ 允许在集合启用了changeStreamPreAndPostImages时返回修改文档的后续图像。指定“whenAvailable”以返回可用的后续图像或不可用时返回null值。指定“required”以在可用的前提下返回后续图像，如果不可用则引发错误。

以下值受支持：

  • MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP

  • MongoDB\Operation\Watch::FULL_DOCUMENT_WHEN_AVAILABLE

  • MongoDB\Operation\Watch::FULL_DOCUMENT_REQUIRED

这是$changeStream管道阶段的选项。

fullDocumentBeforeChange
字符串

确定如何填充响应字段fullDocumentBeforeChange。默认情况下，该字段被省略。

MongoDB 6.0+ 允许在集合启用了changeStreamPreAndPostImages时返回修改文档的先前的图像。指定“whenAvailable”以在可用的前提下返回先前的图像，如果不可用则返回null值。指定“required”以在可用的前提下返回先前的图像，如果不可用则引发错误。

以下值受支持：

  • MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_WHEN_AVAILABLE

  • MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_REQUIRED

这是$changeStream管道阶段的选项。

新增在版本1.13.

maxAwaitTimeMS
整数

表示服务器在无数据可用时阻塞getMore操作的毫秒时间限制的正整数。

readConcern

读关注用于操作。默认情况下为集合的读关注。

readPreference

读偏好用于操作。默认情况下为集合的读偏好。

这用于初始更改流聚合以及自动恢复期间的自动服务器选择。

resumeAfter
数组|对象

指定新更改流的逻辑起始点。更改流返回的文档中的_id字段可以在此处使用。

使用此选项与startAfter和/或startAtOperationTime将导致服务器错误。这些选项是互斥的。

这是$changeStream管道阶段的选项。

session

将与此操作关联的客户端会话。

showExpandedEvents
布尔值

如果为真，指示服务器在更改流中包含额外的DDL事件。可能包含的附加事件有

  • createIndexes

  • dropIndexes

  • modify

  • create

  • shardCollection

  • reshardCollection（服务器6.1+）

  • refineCollectionShardKey（服务器6.1+）

此选项不支持服务器版本低于6.0，如果在执行时使用，将引发异常。

这是$changeStream管道阶段的选项。

新增在版本1.13.

startAfter
数组|对象

指定新更改流的逻辑起始点。更改流返回的文档中的_id字段可以在此处使用。与resumeAfter不同，此选项可以使用来自“invalidate”事件的恢复令牌。

使用此选项与resumeAfter和/或startAtOperationTime将导致服务器错误。这些选项是互斥的。

此选项不支持服务器版本低于4.2，如果在执行时使用，将引发异常。

这是$changeStream管道阶段的选项。

新增在版本1.5.

startAtOperationTime

如果指定，更改流将仅提供在指定时间戳或之后发生的更改。MongoDB 4.0+ 服务器的命令响应包括一个 operationTime，可以在此处使用。默认情况下，如果可用，将使用初始 aggregate 命令返回的 operationTime。

使用此选项与 resumeAfter 和/或 startAfter 一起将导致服务器错误。这些选项是互斥的。

此功能不支持 4.0 版本之前的服务器版本，如果使用它，将在执行时引发异常。

这是$changeStream管道阶段的选项。

typeMap
array

使用 类型映射 应用到游标中，它确定 BSON 文档如何转换为 PHP 值。默认为集合的类型映射。

返回值

一个 MongoDB\ChangeStream 对象，它允许通过 迭代器 接口来遍历更改流中的事件。

错误/异常

如果服务器的命令响应格式不正确，将抛出MongoDB\Exception\UnexpectedValueException异常。

如果使用选项但所选服务器不支持这些选项（例如，collation、readConcern、writeConcern），则抛出MongoDB\Exception\UnsupportedException异常。

对于与参数或选项解析相关的错误，抛出MongoDB\Exception\InvalidArgumentException异常。

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

示例

此示例在迭代更改流时报告事件。

<?php
$uri = 'mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet';
$collection = (new MongoDB\Client($uri))->test->inventory;
$changeStream = $collection->watch();
for ($changeStream->rewind(); true; $changeStream->next()) {
    if ( ! $changeStream->valid()) {
        continue;
    }
    $event = $changeStream->current();
    if ($event['operationType'] === 'invalidate') {
        break;
    }
    $ns = sprintf('%s.%s', $event['ns']['db'], $event['ns']['coll']);
    $id = json_encode($event['documentKey']['_id']);
    switch ($event['operationType']) {
        case 'delete':
            printf("Deleted document in %s with _id: %s\n\n", $ns, $id);
            break;
        case 'insert':
            printf("Inserted new document in %s\n", $ns);
            echo json_encode($event['fullDocument']), "\n\n";
            break;
        case 'replace':
            printf("Replaced new document in %s with _id: %s\n", $ns, $id);
            echo json_encode($event['fullDocument']), "\n\n";
            break;
        case 'update':
            printf("Updated document in %s with _id: %s\n", $ns, $id);
            echo json_encode($event['updateDescription']), "\n\n";
            break;
    }
}

假设在上述脚本迭代更改流时，文档被插入、更新和删除，那么输出将类似于

Inserted new document in test.user
{"_id":{"$oid":"5b329c4874083047cc05e60a"},"username":"bob"}
Inserted new document in test.products
{"_id":{"$oid":"5b329c4d74083047cc05e60b"},"name":"Widget","quantity":5}
Updated document in test.user with _id: {"$oid":"5b329a4f74083047cc05e603"}
{"updatedFields":{"username":"robert"},"removedFields":[]}

另请参阅

返回

updateSearchIndex()

下一页

withOptions()