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

MongoDB\Client::watch()

本页面内容

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

新增在版本1.4.

定义

MongoDB\Client::watch()

执行客户端的change stream操作。change stream 可以用于监视集群级别的变更。

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

参数

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

指定所需选项的数组。

名称
类型
描述
batchSize
整数

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

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

codec
MongoDB\Codec\DocumentCodec

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

新增在版本1.17.

collation
数组|对象

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

comment
混合

允许用户指定任意注释，通过数据库分析器、当前操作输出和日志。来帮助跟踪操作。

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

新增在版本1.13.

fullDocument
字符串

确定在更新操作中如何填充fullDocument响应字段。

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

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

MongoDB 6.0+允许在集合启用了changeStreamPreAndPostImages的情况下返回修改文档的后像。指定"whenAvailable"以返回后像（如果可用）或空值（如果不可用）。指定"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"以返回前像（如果可用）或空值（如果不可用）。指定"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
布尔值

如果为true，指示服务器在更改流中包含额外的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 如果服务器命令响应格式不正确。

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

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

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

示例

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

<?php
$uri = 'mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet';
$client = new MongoDB\Client($uri);
$changeStream = $client->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 app.user
{"_id":{"$oid":"5b329b6674083047cc05e607"},"username":"bob"}
Inserted new document in app.products
{"_id":{"$oid":"5b329b6a74083047cc05e608"},"name":"Widget","quantity":5}
Inserted new document in logs.messages
{"_id":{"$oid":"5b329b7374083047cc05e609"},"msg":"bob purchased a widget"}

另请参阅

返回

startSession()

下一页

MongoDB\Database