MongoDB\Client::watch()

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

MongoDB\Client::watch()

New in version 1.4

Definition

Executes a change stream operation on the client. The change stream can be watched for cluster-level changes.

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

Parameters

$pipeline : array|object

The pipeline of stages to append to an initial $changeStream stage.

$options : array

An array specifying the desired options.

Return Values

A [MongoDB\ChangeStream](https://www.mongodb.com/docs/php-library/current/reference/class/mongodbchangestream.md#mongodb-phpclass-phpclass.MongoDB-ChangeStream object, which allows for iteration of events in the change stream via the Iterator interface.

Errors/Exceptions

[MongoDB\Exception\UnexpectedValueException](https://www.mongodb.com/docs/php-library/current/reference/exception-classes.md#mongodb-phpclass-phpclass.MongoDB-Exception-UnexpectedValueException if the command response from the server was malformed.

[MongoDB\Exception\UnsupportedException](https://www.mongodb.com/docs/php-library/current/reference/exception-classes.md#mongodb-phpclass-phpclass.MongoDB-Exception-UnsupportedException if options are used and not supported by the selected server (e.g. collation, readConcern, writeConcern).

[MongoDB\Exception\InvalidArgumentException](https://www.mongodb.com/docs/php-library/current/reference/exception-classes.md#mongodb-phpclass-phpclass.MongoDB-Exception-InvalidArgumentException for errors related to the parsing of parameters or options.

MongoDB\Driver\Exception\RuntimeException for other errors at the extension level (e.g. connection errors).

Examples

This example reports events while iterating a change stream.

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

Assuming that a document was inserted, updated, and deleted while the above script was iterating the change stream, the output would then resemble:

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

See Also

• [MongoDB\Collection::watch()](https://www.mongodb.com/docs/php-library/current/reference/method/mongodbcollection-watch.md#mongodb-phpmethod-phpmethod.MongoDB-Collection--watch--

• [MongoDB\Database::watch()](https://www.mongodb.com/docs/php-library/current/reference/method/mongodbdatabase-watch.md#mongodb-phpmethod-phpmethod.MongoDB-Database--watch--

• Aggregation Pipeline documentation in the MongoDB Manual

• Change Streams documentation in the MongoDB manual

• Change Events documentation in the MongoDB manual