PHPLIB-351: Documentation for watch() methods

docs/includes/apiargs-MongoDBClient-common-option.yaml

+arg_name: option
+name: readConcern
+type: :php:`MongoDB\\Driver\\ReadConcern <class.mongodb-driver-readconcern>`
+description: |
+   :manual:`Read concern </reference/read-concern>` to use for the operation.
+   Defaults to the client's read concern.
+
+   This is not supported for server versions prior to 3.2 and will result in an
+   exception at execution time if used.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: readPreference
+type: :php:`MongoDB\\Driver\\ReadPreference <class.mongodb-driver-readpreference>`
+description: |
+   :manual:`Read preference </reference/read-preference>` to use for the
+   operation. Defaults to the client's read preference.
+interface: phpmethod
+operation: ~
+optional: true
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: typeMap
+---
+arg_name: option
+name: writeConcern
+type: :php:`MongoDB\\Driver\\WriteConcern <class.mongodb-driver-writeconcern>`
+description: |
+   :manual:`Write concern </reference/write-concern>` to use for the operation.
+   Defaults to the client's write concern.
+interface: phpmethod
+operation: ~
+optional: true
+...

docs/includes/apiargs-MongoDBClient-method-dropDatabase-option.yaml

@@ -10,16 +10,10 @@ source:
 post: |
   This will be used for the returned command result document.
 ---
-arg_name: option
-name: writeConcern
-type: :php:`MongoDB\\Driver\\WriteConcern <class.mongodb-driver-writeconcern>`
-description: |
-  :manual:`Write concern </reference/write-concern>` to use for the operation.
-  Defaults to the client's write concern.
-
+source:
+  file: apiargs-MongoDBClient-common-option.yaml
+  ref: writeConcern
+post: |
   This is not supported for server versions prior to 3.4 and will result in an
   exception at execution time if used.
-interface: phpmethod
-operation: ~
-optional: true
 ...

docs/includes/apiargs-MongoDBClient-method-watch-option.yaml

+---
+source:
+  file: apiargs-method-watch-option.yaml
+  ref: batchSize
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: collation
+---
+source:
+  file: apiargs-method-watch-option.yaml
+  ref: fullDocument
+---
+source:
+  file: apiargs-method-watch-option.yaml
+  ref: maxAwaitTimeMS
+---
+source:
+  file: apiargs-MongoDBClient-common-option.yaml
+  ref: readConcern
+---
+source:
+  file: apiargs-MongoDBClient-common-option.yaml
+  ref: readPreference
+post: |
+  This is used for both the initial change stream aggregation and for
+  server selection during an automatic resume.
+---
+source:
+  file: apiargs-method-watch-option.yaml
+  ref: resumeAfter
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: session
+---
+source:
+  file: apiargs-method-watch-option.yaml
+  ref: startAtOperationTime
+---
+source:
+  file: apiargs-MongoDBClient-common-option.yaml
+  ref: typeMap
+...

docs/includes/apiargs-MongoDBClient-method-watch-param.yaml

+source:
+  file: apiargs-method-watch-param.yaml
+  ref: $pipeline
+---
+source:
+  file: apiargs-method-watch-param.yaml
+  ref: $options
+...

docs/includes/apiargs-MongoDBCollection-common-option.yaml

@@ -24,27 +24,14 @@ interface: phpmethod
 operation: ~
 optional: true
 ---
-arg_name: option
-name: collation
-type: array|object
-description: |
-   :manual:`Collation </reference/collation>` allows users to specify
-   language-specific rules for string comparison, such as rules for lettercase
-   and accent marks. When specifying collation, the ``locale`` field is
-   mandatory; all other collation fields are optional. For descriptions of the
-   fields, see :manual:`Collation Document
-   </reference/collation/#collation-document>`.
-
+source:
+  file: apiargs-common-option.yaml
+  ref: collation
+post: |
    If the collation is unspecified but the collection has a default collation,
    the operation uses the collation specified for the collection. If no
    collation is specified for the collection or for the operation, MongoDB uses
    the simple binary comparison used in prior versions for string comparisons.
-
-   This option is available in MongoDB 3.4+ and will result in an exception at
-   execution time if specified for an older server version.
-interface: phpmethod
-operation: ~
-optional: true
 ---
 arg_name: option
 name: readConcern

docs/includes/apiargs-MongoDBCollection-method-watch-option.yaml

 ---
-arg_name: option
-name: batchSize
-type: integer
-description: |
-  Specifies the maximum number of change events to return in each batch of the
-  response from the MongoDB cluster.
-interface: phpmethod
-operation: ~
-optional: true
+source:
+  file: apiargs-method-watch-option.yaml
+  ref: batchSize
 ---
 source:
-  file: apiargs-MongoDBCollection-common-option.yaml
+  file: apiargs-common-option.yaml
   ref: collation
 ---
-arg_name: option
-name: fullDocument
-type: string
-description: |
-  Allowed values are 'default' and 'updateLookup'. Defaults to 'default'.
-  When set to 'updateLookup', the change notification for partial updates will
-  include both a delta describing the changes to the document, as well as a
-  copy of the entire document that was changed from some time after the change
-  occurred. The following values are supported:
-
-  - ``MongoDB\Operation\Watch::FULL_DOCUMENT_DEFAULT`` (*default*)
-  - ``MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP``
-
-  .. note::
-
-     This is an option of the ``$changeStream`` pipeline stage.
-interface: phpmethod
-operation: ~
-optional: true
+source:
+  file: apiargs-method-watch-option.yaml
+  ref: fullDocument
 ---
-arg_name: option
-name: maxAwaitTimeMS
-type: integer
-description: |
-  Positive integer denoting the time limit in milliseconds for the server to
-  block a getMore operation if no data is available.
-interface: phpmethod
-operation: ~
-optional: true
+source:
+  file: apiargs-method-watch-option.yaml
+  ref: maxAwaitTimeMS
 ---
 source:
   file: apiargs-MongoDBCollection-common-option.yaml
@@ -54,23 +26,20 @@ post: |
   This is used for both the initial change stream aggregation and for
   server selection during an automatic resume.
 ---
-arg_name: option
-name: resumeAfter
-type: array|object
-description: |
-  Specifies the logical starting point for the new change stream.
-
-  .. note::
-
-     This is an option of the ``$changeStream`` pipeline stage.
-interface: phpmethod
-operation: ~
-optional: true
+source:
+  file: apiargs-method-watch-option.yaml
+  ref: resumeAfter
 ---
 source:
   file: apiargs-common-option.yaml
   ref: session
 ---
+source:
+  file: apiargs-method-watch-option.yaml
+  ref: startAtOperationTime
+post: |
+  .. versionadded:: 1.4
+---
 source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: typeMap

docs/includes/apiargs-MongoDBCollection-method-watch-param.yaml

-arg_name: param
-name: $pipeline
-type: array|object
-description: |
-  The pipeline of stages to append to an initial ``$changeStream`` stage.
-interface: phpmethod
-operation: ~
-optional: true
+source:
+  file: apiargs-method-watch-param.yaml
+  ref: $pipeline
 ---
 source:
-  file: apiargs-common-param.yaml
+  file: apiargs-method-watch-param.yaml
   ref: $options
 ...

docs/includes/apiargs-MongoDBDatabase-common-option.yaml

+arg_name: option
+name: readConcern
+type: :php:`MongoDB\\Driver\\ReadConcern <class.mongodb-driver-readconcern>`
+description: |
+   :manual:`Read concern </reference/read-concern>` to use for the operation.
+   Defaults to the database's read concern.
+
+   This is not supported for server versions prior to 3.2 and will result in an
+   exception at execution time if used.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: readPreference
+type: :php:`MongoDB\\Driver\\ReadPreference <class.mongodb-driver-readpreference>`
+description: |
+   :manual:`Read preference </reference/read-preference>` to use for the
+   operation. Defaults to the database's read preference.
+interface: phpmethod
+operation: ~
+optional: true
+---
 source:
   file: apiargs-common-option.yaml
   ref: typeMap

docs/includes/apiargs-MongoDBDatabase-method-createCollection-option.yaml

@@ -28,7 +28,7 @@ operation: ~
 optional: true
 ---
 source:
-  file: apiargs-MongoDBCollection-common-option.yaml
+  file: apiargs-common-option.yaml
   ref: collation
 pre: |
   Specifies the :manual:`collation

docs/includes/apiargs-MongoDBDatabase-method-watch-option.yaml

+---
+source:
+  file: apiargs-method-watch-option.yaml
+  ref: batchSize
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: collation
+---
+source:
+  file: apiargs-method-watch-option.yaml
+  ref: fullDocument
+---
+source:
+  file: apiargs-method-watch-option.yaml
+  ref: maxAwaitTimeMS
+---
+source:
+  file: apiargs-MongoDBDatabase-common-option.yaml
+  ref: readConcern
+---
+source:
+  file: apiargs-MongoDBDatabase-common-option.yaml
+  ref: readPreference
+post: |
+  This is used for both the initial change stream aggregation and for
+  server selection during an automatic resume.
+---
+source:
+  file: apiargs-method-watch-option.yaml
+  ref: resumeAfter
+---
+source:
+  file: apiargs-common-option.yaml
+  ref: session
+---
+source:
+  file: apiargs-method-watch-option.yaml
+  ref: startAtOperationTime
+---
+source:
+  file: apiargs-MongoDBDatabase-common-option.yaml
+  ref: typeMap
+...

docs/includes/apiargs-MongoDBDatabase-method-watch-param.yaml

+source:
+  file: apiargs-method-watch-param.yaml
+  ref: $pipeline
+---
+source:
+  file: apiargs-method-watch-param.yaml
+  ref: $options
+...

docs/includes/apiargs-common-option.yaml

 arg_name: option
+name: collation
+type: array|object
+description: |
+   :manual:`Collation </reference/collation>` allows users to specify
+   language-specific rules for string comparison, such as rules for lettercase
+   and accent marks. When specifying collation, the ``locale`` field is
+   mandatory; all other collation fields are optional. For descriptions of the
+   fields, see :manual:`Collation Document
+   </reference/collation/#collation-document>`.
+
+   This option is available in MongoDB 3.4+ and will result in an exception at
+   execution time if specified for an older server version.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
 name: maxTimeMS
 type: integer
 description: |

docs/includes/apiargs-method-watch-option.yaml

+---
+arg_name: option
+name: batchSize
+type: integer
+description: |
+  Specifies the maximum number of change events to return in each batch of the
+  response from the MongoDB cluster.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: fullDocument
+type: string
+description: |
+  Allowed values are 'default' and 'updateLookup'. Defaults to 'default'.
+  When set to 'updateLookup', the change notification for partial updates will
+  include both a delta describing the changes to the document, as well as a
+  copy of the entire document that was changed from some time after the change
+  occurred. The following values are supported:
+
+  - ``MongoDB\Operation\Watch::FULL_DOCUMENT_DEFAULT`` (*default*)
+  - ``MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP``
+
+  .. note::
+
+     This is an option of the ``$changeStream`` pipeline stage.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: maxAwaitTimeMS
+type: integer
+description: |
+  Positive integer denoting the time limit in milliseconds for the server to
+  block a getMore operation if no data is available.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: resumeAfter
+type: array|object
+description: |
+  Specifies the logical starting point for the new change stream. The ``_id``
+  field in documents returned by the change stream may be used here.
+
+  Using this option in conjunction with ``startAtOperationTime`` will result in
+  a server error. The options are mutually exclusive.
+
+  .. note::
+
+     This is an option of the ``$changeStream`` pipeline stage.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: startAtOperationTime
+type: :php:`MongoDB\\BSON\\TimestampInterface <class.mongodb-bson-timestampinterface>`
+description: |
+  If specified, the change stream will only provide changes that occurred at or
+  after the specified timestamp. Command responses from a MongoDB 4.0+ server
+  include an ``operationTime`` that can be used here. By default, the
+  ``operationTime`` returned by the initial ``aggregate`` command will be used
+  if available.
+
+  Using this option in conjunction with ``resumeAfter`` will result in a server
+  error. The options are mutually exclusive.
+
+  This is not supported for server versions prior to 4.0 and will result in an
+  exception at execution time if used.
+
+  .. note::
+
+     This is an option of the ``$changeStream`` pipeline stage.
+interface: phpmethod
+operation: ~
+optional: true
+...

docs/includes/apiargs-method-watch-param.yaml

+arg_name: param
+name: $pipeline
+type: array|object
+description: |
+  The pipeline of stages to append to an initial ``$changeStream`` stage.
+interface: phpmethod
+operation: ~
+optional: true
+---
+source:
+  file: apiargs-common-param.yaml
+  ref: $options
+...

docs/reference/class/MongoDBClient.txt

@@ -40,3 +40,4 @@ Methods
    /reference/method/MongoDBClient-selectCollection
    /reference/method/MongoDBClient-selectDatabase
    /reference/method/MongoDBClient-startSession
+   /reference/method/MongoDBClient-watch

docs/reference/class/MongoDBDatabase.txt

@@ -59,5 +59,6 @@ Methods
    /reference/method/MongoDBDatabase-modifyCollection
    /reference/method/MongoDBDatabase-selectCollection
    /reference/method/MongoDBDatabase-selectGridFSBucket
+   /reference/method/MongoDBDatabase-watch
    /reference/method/MongoDBDatabase-withOptions
 

docs/reference/method/MongoDBClient-watch.txt

+========================
+MongoDB\\Client::watch()
+========================
+
+.. versionadded:: 1.4
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\Client::watch()
+
+   Executes a :manual:`change stream </changeStreams>` operation on the client.
+   The change stream can be watched for cluster-level changes.
+
+   .. code-block:: php
+
+      function watch(array $pipeline = [], array $options = []): MongoDB\ChangeStream
+
+   This method has the following parameters:
+
+   .. include:: /includes/apiargs/MongoDBClient-method-watch-param.rst
+
+   The ``$options`` parameter supports the following options:
+
+   .. include:: /includes/apiargs/MongoDBClient-method-watch-option.rst
+
+Return Values
+-------------
+
+A :phpclass:`MongoDB\\ChangeStream` object, which allows for iteration of
+events in the change stream via the :php:`Iterator <class.iterator>` interface.
+
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-unexpectedvalueexception.rst
+.. include:: /includes/extracts/error-unsupportedexception.rst
+.. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-runtimeexception.rst
+
+Examples
+--------
+
+This example reports events while iterating a change stream.
+
+.. code-block:: php
+
+   <?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:
+
+.. code-block:: none
+
+   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
+--------
+
+- :manual:`Aggregation Pipeline </core/aggregation-pipeline>` documentation in
+  the MongoDB Manual
+- :manual:`Change Streams </changeStreams>` documentation in the MongoDB manual
+- :manual:`Change Events </reference/change-events/>` documentation in the
+  MongoDB manual

docs/reference/method/MongoDBCollection-watch.txt

@@ -18,7 +18,7 @@ Definition
 .. phpmethod:: MongoDB\\Collection::watch()
 
    Executes a :manual:`change stream </changeStreams>` operation on the
-   collection.
+   collection. The change stream can be watched for collection-level changes.
 
    .. code-block:: php
 
@@ -68,6 +68,10 @@ This example reports events while iterating a change stream.
 
        $event = $changeStream->current();
 
+       if ($event['operationType'] === 'invalidate') {
+           break;
+       }
+
        $ns = sprintf('%s.%s', $event['ns']['db'], $event['ns']['coll']);
        $id = json_encode($event['documentKey']['_id']);
 
@@ -98,13 +102,14 @@ script was iterating the change stream, the output would then resemble:
 
 .. code-block:: none
 
-   Inserted new document in test.inventory
-   {"_id":{"$oid":"5a81fc0d6118fd1af1790d32"},"name":"Widget","quantity":5}
+   Inserted new document in test.user
+   {"_id":{"$oid":"5b329c4874083047cc05e60a"},"username":"bob"}
 
-   Updated document in test.inventory with _id: {"$oid":"5a81fc0d6118fd1af1790d32"}
-   {"updatedFields":{"quantity":4},"removedFields":[]}
+   Inserted new document in test.products
+   {"_id":{"$oid":"5b329c4d74083047cc05e60b"},"name":"Widget","quantity":5}
 
-   Deleted document in test.inventory with _id: {"$oid":"5a81fc0d6118fd1af1790d32"}
+   Updated document in test.user with _id: {"$oid":"5b329a4f74083047cc05e603"}
+   {"updatedFields":{"username":"robert"},"removedFields":[]}
 
 See Also
 --------

docs/reference/method/MongoDBDatabase-watch.txt

+==========================
+MongoDB\\Database::watch()
+==========================
+
+.. versionadded:: 1.4
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\Database::watch()
+
+   Executes a :manual:`change stream </changeStreams>` operation on the
+   database. The change stream can be watched for database-level changes.
+
+   .. code-block:: php
+
+      function watch(array $pipeline = [], array $options = []): MongoDB\ChangeStream
+
+   This method has the following parameters:
+
+   .. include:: /includes/apiargs/MongoDBDatabase-method-watch-param.rst
+
+   The ``$options`` parameter supports the following options:
+
+   .. include:: /includes/apiargs/MongoDBDatabase-method-watch-option.rst
+
+Return Values
+-------------
+
+A :phpclass:`MongoDB\\ChangeStream` object, which allows for iteration of
+events in the change stream via the :php:`Iterator <class.iterator>` interface.
+
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-unexpectedvalueexception.rst
+.. include:: /includes/extracts/error-unsupportedexception.rst
+.. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-runtimeexception.rst
+
+Examples
+--------
+
+This example reports events while iterating a change stream.
+
+.. code-block:: php
+
+   <?php
+
+   $uri = 'mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet';
+
+   $database = (new MongoDB\Client($uri))->test;
+
+   $changeStream = $database->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:
+
+.. code-block:: none
+
+   Inserted new document in test.inventory
+   {"_id":{"$oid":"5a81fc0d6118fd1af1790d32"},"name":"Widget","quantity":5}
+
+   Updated document in test.inventory with _id: {"$oid":"5a81fc0d6118fd1af1790d32"}
+   {"updatedFields":{"quantity":4},"removedFields":[]}
+
+   Deleted document in test.inventory with _id: {"$oid":"5a81fc0d6118fd1af1790d32"}
+
+See Also
+--------
+
+- :manual:`Aggregation Pipeline </core/aggregation-pipeline>` documentation in
+  the MongoDB Manual
+- :manual:`Change Streams </changeStreams>` documentation in the MongoDB manual
+- :manual:`Change Events </reference/change-events/>` documentation in the
+  MongoDB manual