From cc7851f37d42e0fc2734f0403ce7af8610ec5dbc Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 22 Aug 2024 16:27:47 -0400 Subject: [PATCH 01/13] DOCSP-41981: Change streams --- source/includes/read/change-streams.php | 47 +++++ source/read.txt | 1 + source/read/change-streams.txt | 257 ++++++++++++++++++++++++ 3 files changed, 305 insertions(+) create mode 100644 source/includes/read/change-streams.php create mode 100644 source/read/change-streams.txt diff --git a/source/includes/read/change-streams.php b/source/includes/read/change-streams.php new file mode 100644 index 00000000..885ab9f1 --- /dev/null +++ b/source/includes/read/change-streams.php @@ -0,0 +1,47 @@ +sample_restaurants->restaurants; +// end-db-coll + +// Monitors and prints changes to the "restaurants" collection +// start-open-change-stream +$changeStream = $collection->watch(); + +foreach ($changeStream as $event) { + echo json_encode($event), PHP_EOL; +} +// end-open-change-stream + +// Updates a document that has a "name" value of "Blarney Castle" +// start-update-for-change-stream +$result = $collection->updateOne( + ['name' => 'Blarney Castle'], + ['$set' => ['cuisine' => 'Irish']] +); +// end-update-for-change-stream + +// Passes a pipeline argument to watch() to monitor only update operations +// start-change-stream-pipeline +$pipeline = [['$match' => ['operationType' => 'update']]]; +$changeStream = $collection->watch($pipeline); + +foreach ($changeStream as $event) { + echo json_encode($event), PHP_EOL; +} +// end-change-stream-pipeline + +// Passes an options argument to watch() to include the post-image of updated documents +// start-change-stream-post-image +$options = ['fullDocument' => 'updateLookup']; +$changeStream = $collection->watch([], $options); + +foreach ($changeStream as $event) { + echo json_encode($event), PHP_EOL; +} +// end-change-stream-post-image + diff --git a/source/read.txt b/source/read.txt index a5c58482..31c57628 100644 --- a/source/read.txt +++ b/source/read.txt @@ -10,4 +10,5 @@ Read Data from MongoDB /read/retrieve /read/project + /read/change-streams diff --git a/source/read/change-streams.txt b/source/read/change-streams.txt new file mode 100644 index 00000000..fb0319ee --- /dev/null +++ b/source/read/change-streams.txt @@ -0,0 +1,257 @@ +.. _php-change-streams: + +==================== +Monitor Data Changes +==================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: watch, code example + +Overview +-------- + +In this guide, you can learn how to use a **change stream** to monitor real-time +changes to your database. A change stream is a {+mdb-server+} feature that +allows your application to subscribe to data changes on a collection, database, +or deployment. + +When using the {+driver-short+}, you can instantiate a ``MongoDB\ChangeStream`` to +monitor data changes. + +Sample Data +~~~~~~~~~~~ + +The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` +database from the :atlas:`Atlas sample datasets `. To access this collection +from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster +and assign the following value to your ``collection`` variable: + +.. literalinclude:: /includes/read/change-streams.php + :language: php + :dedent: + :start-after: start-db-coll + :end-before: end-db-coll + +To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` guide. + +Open a Change Stream +-------------------- + +To open a change stream, call the ``watch()`` method. The instance on which you +call the ``watch()`` method on determines the scope of events that the change +stream listens for. You can call the ``watch()`` method on the following +classes: + +- ``MongoDB\Client``: Monitor all changes in the MongoDB deployment +- ``MongoDB\Database``: Monitor changes in all collections in the database +- ``MongoDB\Collection``: Monitor changes in the collection + +The following example opens a change stream on the ``restaurants`` collection +and outputs changes as they occur: + +.. literalinclude:: /includes/read/change-streams.php + :start-after: start-open-change-stream + :end-before: end-open-change-stream + :language: php + :dedent: + +To begin watching for changes, run the preceding code. Then, in a separate +application or shell, modify the ``restaurants`` collection. The following +example updates a document that has a ``name`` field value of ``'Blarney Castle'``: + +.. _php-change-stream-update: + +.. literalinclude:: /includes/read/change-streams.php + :start-after: start-update-for-change-stream + :end-before: end-update-for-change-stream + :language: php + :dedent: + +When you update the collection, the change stream application prints the change +as it occurs. The printed change event resembles the following output: + +.. code-block:: bash + :copyable: false + + { "_id" : { "_data" : "..." }, "operationType" : "update", "clusterTime" : + { "$timestamp" : { ... }, "wallTime" : { "$date" : ... }, "ns" : + { "db" : "sample_restaurants", "coll" : "restaurants" }, "documentKey" : + { "_id" : { "$oid" : "..." } }, "updateDescription" : { "updatedFields" : + { "cuisine" : "Irish" }, "removedFields" : [ ], "truncatedArrays" : [ ] } } + +Modify the Change Stream Output +------------------------------- + +To modify the change stream output, you can pass pipeline stages in an array as a +parameter to the ``watch()`` method. You can include the following stages in the +array: + +- ``$addFields`` or ``$set``: Adds new fields to documents +- ``$match``: Filters the documents +- ``$project``: Projects a subset of the document fields +- ``$replaceWith`` or ``$replaceRoot``: Replaces the input document with the + specified document +- ``$redact``: Restricts the contents of the documents +- ``$unset``: Removes fields from documents + +The following passes a pipeline that includes the ``$match`` stage to the ``watch()`` +method. This instructs the ``watch()`` method to output only update operations: + +.. literalinclude:: /includes/read/change-streams.php + :start-after: start-change-stream-pipeline + :end-before: end-change-stream-pipeline + :language: php + :dedent: + +Modify ``watch()`` Behavior +--------------------------- + +To modify the behavior of the ``watch()`` method, you can pass an options array +as a parameter to ``watch()``. The following table describes some of the options +you can set in the array: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Option + - Description + + * - ``fullDocument`` + - | Specifies whether to show the full document after the change, rather + than showing only the changes made to the document. To learn more about + this option, see :ref:`php-change-stream-pre-post-image`. + + * - ``fullDocumentBeforeChange`` + - | Specifies whether to show the full document as it was before the change, rather + than showing only the changes made to the document. To learn more about + this option, see :ref:`php-change-stream-pre-post-image`. + + * - ``resumeAfter`` + - | Instructs ``watch()`` to resume returning changes after the + operation specified in the resume token. + | Each change stream event document includes a resume token as the ``_id`` + field. Pass the entire ``_id`` field of the change event document that + represents the operation you want to resume after. + | ``resume_after`` is mutually exclusive with ``startAfter`` and ``startAtOperationTime``. + + * - ``startAfter`` + - | Instructs ``watch()`` to start a new change stream after the + operation specified in the resume token. This field allows notifications to + resume after an invalidate event. + | Each change stream event document includes a resume token as the ``_id`` + field. Pass the entire ``_id`` field of the change event document that + represents the operation you want to resume after. + | ``start_after`` is mutually exclusive with ``resume_after`` and ``start_at_operation_time``. + + * - ``typeMap`` + - | Sets the maximum number of change events to return in each batch of the + response from the MongoDB cluster. + + * - ``collation`` + - | Sets the collation to use for the change stream cursor. + +For a full list of ``watch()`` options, see `MongoDB\\Collection::watch() +<{+api+}/reference/method/MongoDBCollection-watch/>`__ in the API +documentation. + +.. _php-change-stream-pre-post-image: + +Include Pre-Images and Post-Images +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. important:: + + You can enable pre-images and post-images on collections only if your + deployment uses MongoDB v6.0 or later. + +By default, when you perform an operation on a collection, the +corresponding change event includes only the delta of the fields +modified by that operation. To see the full document before or after a +change, specify the ``fullDocumentBeforeChange`` or the ``fullDocument`` +options in an array parameter to ``watch()``. + +The **pre-image** is the full version of a document *before* a change. To include the +pre-image in the change stream event, set the ``fullDocumentBeforeChange`` field +to one of the following strings: + +- ``MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_WHEN_AVAILABLE``: The change event includes + a pre-image of the modified document for change events. If the pre-image is not available, this + change event field has a ``null`` value. +- ``MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_REQUIRED``: The change event includes a pre-image + of the modified document for change events. If the pre-image is not available, the + {+driver-short+} raises an error. + +The **post-image** is the full version of a document *after* a change. To include the +post-image in the change stream event, set the ``fullDocument`` field to +one of the following strings: + +- ``MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP``: The change event includes a + copy of the entire changed document from some time after the change. +- ``MongoDB\Operation\Watch::FULL_DOCUMENT_WHEN_AVAILABLE``: The change event includes + a post-image of the modified document for change events only if the post-image is available. +- ``MongoDB\Operation\Watch::FULL_DOCUMENT_REQUIRED``: The change event includes a post-image + of the modified document for change events. If the post-image is not available, the + {+driver-short+} raises an error. + +The following example calls the ``watch()`` method on a collection and includes the post-image +of updated documents by setting the ``fullDocument`` option: + +.. literalinclude:: /includes/read/change-streams.php + :start-after: start-change-stream-post-image + :end-before: end-change-stream-post-image + :language: php + :dedent: + +With the change stream application running, updating a document in the +``restaurants`` collection by using the :ref:`preceding update example +` prints a change event resembling the following +code: + +.. code-block:: bash + :copyable: false + :emphasize-lines: 3,4,5,6 + + { "_id" : { "_data" : "..." }, "operationType" : "update", "clusterTime" : + { "$timestamp" : { ... } }, "wallTime" : { "$date" : ... }, + "fullDocument" : { "_id" : { "$oid" : "..." }, "address" : { "building" : "202-24", + "coord" : [ -73.925044200000002093, 40.559546199999999772 ], "street" : + "Rockaway Point Boulevard", "zipcode" : "11697" }, "borough" : "Queens", "cuisine" : + "Irish", "grades" : [ ... ], "name" : "Blarney Castle", "restaurant_id" : "40366356" }, + "ns" : { "db" : "sample_restaurants", "coll" : "restaurants" }, "documentKey" : + { "_id" : { "$oid" : "..." } }, "updateDescription" : { "updatedFields" : + { "cuisine" : "Irish" }, "removedFields" : [ ], "truncatedArrays" : [ ] } } + +.. tip:: + + To learn more about pre-images and post-images, see + :manual:`Change Streams with Document Pre- and Post-Images ` + in the {+mdb-server+} manual. + +Additional Information +---------------------- + +To learn more about change streams, see :manual:`Change Streams +` in the {+mdb-server+} manual. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + +- `MongoDB\\Client::watch() <{+api+}/method/MongoDBClient-watch/>`__ +- `MongoDB\\Database::watch() <{+api+}/method/MongoDBDatabase-watch/>`__ +- `MongoDB\\Collection::watch() <{+api+}/method/MongoDBCollection-watch/>`__ +- `MongoDB\\Collection::updateOne() <{+api+}/method/MongoDBCollection-updateOne/>`__ \ No newline at end of file From 617bab84e498b8b723cccbce6e9cb39676527b39 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 22 Aug 2024 16:50:56 -0400 Subject: [PATCH 02/13] edits --- source/read/change-streams.txt | 57 ++++++++++++++++------------------ 1 file changed, 27 insertions(+), 30 deletions(-) diff --git a/source/read/change-streams.txt b/source/read/change-streams.txt index fb0319ee..ccd25490 100644 --- a/source/read/change-streams.txt +++ b/source/read/change-streams.txt @@ -21,11 +21,11 @@ Overview -------- In this guide, you can learn how to use a **change stream** to monitor real-time -changes to your database. A change stream is a {+mdb-server+} feature that +changes to your data. A change stream is a {+mdb-server+} feature that allows your application to subscribe to data changes on a collection, database, or deployment. -When using the {+driver-short+}, you can instantiate a ``MongoDB\ChangeStream`` to +When using the {+php-library+}, you can instantiate a ``MongoDB\ChangeStream`` to monitor data changes. Sample Data @@ -49,8 +49,8 @@ Open a Change Stream -------------------- To open a change stream, call the ``watch()`` method. The instance on which you -call the ``watch()`` method on determines the scope of events that the change -stream listens for. You can call the ``watch()`` method on the following +call the ``watch()`` method determines the scope of events that the change +stream monitors. You can call the ``watch()`` method on the following classes: - ``MongoDB\Client``: Monitor all changes in the MongoDB deployment @@ -84,11 +84,10 @@ as it occurs. The printed change event resembles the following output: .. code-block:: bash :copyable: false - { "_id" : { "_data" : "..." }, "operationType" : "update", "clusterTime" : - { "$timestamp" : { ... }, "wallTime" : { "$date" : ... }, "ns" : - { "db" : "sample_restaurants", "coll" : "restaurants" }, "documentKey" : - { "_id" : { "$oid" : "..." } }, "updateDescription" : { "updatedFields" : - { "cuisine" : "Irish" }, "removedFields" : [ ], "truncatedArrays" : [ ] } } + {"_id":{"_data":"..."},"operationType":"update","clusterTime":{"$timestamp":{...}, + "wallTime":{"$date":...},"ns":{"db":"sample_restaurants","coll":"restaurants"}, + "documentKey":{"_id":{"$oid":"..."}},"updateDescription":{"updatedFields": + {"cuisine":"Irish"},"removedFields":[],"truncatedArrays":[]}}} Modify the Change Stream Output ------------------------------- @@ -144,7 +143,7 @@ you can set in the array: | Each change stream event document includes a resume token as the ``_id`` field. Pass the entire ``_id`` field of the change event document that represents the operation you want to resume after. - | ``resume_after`` is mutually exclusive with ``startAfter`` and ``startAtOperationTime``. + | This option is mutually exclusive with ``startAfter`` and ``startAtOperationTime``. * - ``startAfter`` - | Instructs ``watch()`` to start a new change stream after the @@ -153,17 +152,17 @@ you can set in the array: | Each change stream event document includes a resume token as the ``_id`` field. Pass the entire ``_id`` field of the change event document that represents the operation you want to resume after. - | ``start_after`` is mutually exclusive with ``resume_after`` and ``start_at_operation_time``. + | This option is mutually exclusive with ``resumeAfter`` and ``startAtOperationTime``. * - ``typeMap`` - - | Sets the maximum number of change events to return in each batch of the - response from the MongoDB cluster. + - | The type map to apply to cursors, which determines how BSON documents are converted + to PHP values. * - ``collation`` - | Sets the collation to use for the change stream cursor. For a full list of ``watch()`` options, see `MongoDB\\Collection::watch() -<{+api+}/reference/method/MongoDBCollection-watch/>`__ in the API +<{+api+}/method/MongoDBCollection-watch/>`__ in the API documentation. .. _php-change-stream-pre-post-image: @@ -184,26 +183,26 @@ options in an array parameter to ``watch()``. The **pre-image** is the full version of a document *before* a change. To include the pre-image in the change stream event, set the ``fullDocumentBeforeChange`` field -to one of the following strings: +to one of the following values: - ``MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_WHEN_AVAILABLE``: The change event includes a pre-image of the modified document for change events. If the pre-image is not available, this change event field has a ``null`` value. - ``MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_REQUIRED``: The change event includes a pre-image of the modified document for change events. If the pre-image is not available, the - {+driver-short+} raises an error. + {+php-library+} raises an error. The **post-image** is the full version of a document *after* a change. To include the post-image in the change stream event, set the ``fullDocument`` field to -one of the following strings: +one of the following values: - ``MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP``: The change event includes a - copy of the entire changed document from some time after the change. + copy of the entire changed document from some time after the change. - ``MongoDB\Operation\Watch::FULL_DOCUMENT_WHEN_AVAILABLE``: The change event includes a post-image of the modified document for change events only if the post-image is available. - ``MongoDB\Operation\Watch::FULL_DOCUMENT_REQUIRED``: The change event includes a post-image of the modified document for change events. If the post-image is not available, the - {+driver-short+} raises an error. + {+php-library+} raises an error. The following example calls the ``watch()`` method on a collection and includes the post-image of updated documents by setting the ``fullDocument`` option: @@ -221,17 +220,15 @@ code: .. code-block:: bash :copyable: false - :emphasize-lines: 3,4,5,6 - - { "_id" : { "_data" : "..." }, "operationType" : "update", "clusterTime" : - { "$timestamp" : { ... } }, "wallTime" : { "$date" : ... }, - "fullDocument" : { "_id" : { "$oid" : "..." }, "address" : { "building" : "202-24", - "coord" : [ -73.925044200000002093, 40.559546199999999772 ], "street" : - "Rockaway Point Boulevard", "zipcode" : "11697" }, "borough" : "Queens", "cuisine" : - "Irish", "grades" : [ ... ], "name" : "Blarney Castle", "restaurant_id" : "40366356" }, - "ns" : { "db" : "sample_restaurants", "coll" : "restaurants" }, "documentKey" : - { "_id" : { "$oid" : "..." } }, "updateDescription" : { "updatedFields" : - { "cuisine" : "Irish" }, "removedFields" : [ ], "truncatedArrays" : [ ] } } + :emphasize-lines: 2-5 + + {"_id":{"_data":"..."},"operationType":"update","clusterTime":...},"wallTime":{"$date":...}, + "fullDocument":{"_id":{"$oid":"..."},"address": {"building":"202-24","coord": + [-73.925044200000002093,40.559546199999999772], "street":"Rockaway Point Boulevard", + "zipcode":"11697"},"borough":"Queens","cuisine":"Irish","grades":[...],"name":"Blarney Castle", + "restaurant_id":"40366356"},"ns":{"db":"sample_restaurants","coll":"restaurants"}, + "documentKey":{"_id":{"$oid":"..."}},"updateDescription":{"updatedFields":{"cuisine":"Irish"}, + "removedFields":[],"truncatedArrays":[]}} .. tip:: From a7d8c02dd9205f2745188d5d9eede85bec4faf41 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 22 Aug 2024 16:56:25 -0400 Subject: [PATCH 03/13] code edits, fixes --- source/includes/read/change-streams.php | 8 ++++---- source/read/change-streams.txt | 6 +++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/source/includes/read/change-streams.php b/source/includes/read/change-streams.php index 885ab9f1..ef1baf12 100644 --- a/source/includes/read/change-streams.php +++ b/source/includes/read/change-streams.php @@ -13,7 +13,7 @@ $changeStream = $collection->watch(); foreach ($changeStream as $event) { - echo json_encode($event), PHP_EOL; + echo json_encode($event) . PHP_EOL; } // end-open-change-stream @@ -31,17 +31,17 @@ $changeStream = $collection->watch($pipeline); foreach ($changeStream as $event) { - echo json_encode($event), PHP_EOL; + echo json_encode($event) . PHP_EOL; } // end-change-stream-pipeline // Passes an options argument to watch() to include the post-image of updated documents // start-change-stream-post-image -$options = ['fullDocument' => 'updateLookup']; +$options = ['fullDocument' => MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP]; $changeStream = $collection->watch([], $options); foreach ($changeStream as $event) { - echo json_encode($event), PHP_EOL; + echo json_encode($event) . PHP_EOL; } // end-change-stream-post-image diff --git a/source/read/change-streams.txt b/source/read/change-streams.txt index ccd25490..b18c9213 100644 --- a/source/read/change-streams.txt +++ b/source/read/change-streams.txt @@ -50,7 +50,7 @@ Open a Change Stream To open a change stream, call the ``watch()`` method. The instance on which you call the ``watch()`` method determines the scope of events that the change -stream monitors. You can call the ``watch()`` method on the following +stream monitors. You can call the ``watch()`` method on instances of the following classes: - ``MongoDB\Client``: Monitor all changes in the MongoDB deployment @@ -182,7 +182,7 @@ change, specify the ``fullDocumentBeforeChange`` or the ``fullDocument`` options in an array parameter to ``watch()``. The **pre-image** is the full version of a document *before* a change. To include the -pre-image in the change stream event, set the ``fullDocumentBeforeChange`` field +pre-image in the change stream event, set the ``fullDocumentBeforeChange`` option to one of the following values: - ``MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_WHEN_AVAILABLE``: The change event includes @@ -193,7 +193,7 @@ to one of the following values: {+php-library+} raises an error. The **post-image** is the full version of a document *after* a change. To include the -post-image in the change stream event, set the ``fullDocument`` field to +post-image in the change stream event, set the ``fullDocument`` option to one of the following values: - ``MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP``: The change event includes a From 9e6770ff3fb7a2cae46eaf7b4900d6f2e0797829 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 22 Aug 2024 16:58:59 -0400 Subject: [PATCH 04/13] vale fix --- source/read/change-streams.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/read/change-streams.txt b/source/read/change-streams.txt index b18c9213..56e0ed15 100644 --- a/source/read/change-streams.txt +++ b/source/read/change-streams.txt @@ -117,8 +117,8 @@ Modify ``watch()`` Behavior --------------------------- To modify the behavior of the ``watch()`` method, you can pass an options array -as a parameter to ``watch()``. The following table describes some of the options -you can set in the array: +as a parameter to ``watch()``. The following table describes some options you +can set in the array: .. list-table:: :widths: 30 70 From 7c95a9fba365fe5529334bfd090512a8e34606cc Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 27 Aug 2024 14:18:42 -0400 Subject: [PATCH 05/13] RR feedback --- source/read/change-streams.txt | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/source/read/change-streams.txt b/source/read/change-streams.txt index 56e0ed15..45a8fb34 100644 --- a/source/read/change-streams.txt +++ b/source/read/change-streams.txt @@ -25,8 +25,8 @@ changes to your data. A change stream is a {+mdb-server+} feature that allows your application to subscribe to data changes on a collection, database, or deployment. -When using the {+php-library+}, you can instantiate a ``MongoDB\ChangeStream`` to -monitor data changes. +When using the {+php-library+}, you can create an instance of ``MongoDB\ChangeStream`` to +monitor data changes, such as updates, insertions, and deletions. Sample Data ~~~~~~~~~~~ @@ -81,7 +81,7 @@ example updates a document that has a ``name`` field value of ``'Blarney Castle' When you update the collection, the change stream application prints the change as it occurs. The printed change event resembles the following output: -.. code-block:: bash +.. code-block:: none :copyable: false {"_id":{"_data":"..."},"operationType":"update","clusterTime":{"$timestamp":{...}, @@ -105,7 +105,8 @@ array: - ``$unset``: Removes fields from documents The following passes a pipeline that includes the ``$match`` stage to the ``watch()`` -method. This instructs the ``watch()`` method to output only update operations: +method. This instructs the ``watch()`` method to output events only when update +operations occur: .. literalinclude:: /includes/read/change-streams.php :start-after: start-change-stream-pipeline @@ -117,7 +118,7 @@ Modify ``watch()`` Behavior --------------------------- To modify the behavior of the ``watch()`` method, you can pass an options array -as a parameter to ``watch()``. The following table describes some options you +as a parameter to ``watch()``. The following table describes useful options you can set in the array: .. list-table:: @@ -130,7 +131,8 @@ can set in the array: * - ``fullDocument`` - | Specifies whether to show the full document after the change, rather than showing only the changes made to the document. To learn more about - this option, see :ref:`php-change-stream-pre-post-image`. + this option, see the :ref:`php-change-stream-pre-post-image` section of this + guide. * - ``fullDocumentBeforeChange`` - | Specifies whether to show the full document as it was before the change, rather @@ -154,6 +156,11 @@ can set in the array: represents the operation you want to resume after. | This option is mutually exclusive with ``resumeAfter`` and ``startAtOperationTime``. + * - ``startAtOperationTime`` + - | Instructs the change stream to only provide changes that occurred at or after + the specified timestamp. + | This option is mutually exclusive with ``startAfter`` and ``resumeAfter``. + * - ``typeMap`` - | The type map to apply to cursors, which determines how BSON documents are converted to PHP values. @@ -216,7 +223,7 @@ of updated documents by setting the ``fullDocument`` option: With the change stream application running, updating a document in the ``restaurants`` collection by using the :ref:`preceding update example ` prints a change event resembling the following -code: +output: .. code-block:: bash :copyable: false From fb90e5fdb395ce6b64cc345d346cd1b172b75106 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 27 Aug 2024 14:24:42 -0400 Subject: [PATCH 06/13] edit --- source/read/change-streams.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/read/change-streams.txt b/source/read/change-streams.txt index 45a8fb34..234be149 100644 --- a/source/read/change-streams.txt +++ b/source/read/change-streams.txt @@ -225,7 +225,7 @@ With the change stream application running, updating a document in the ` prints a change event resembling the following output: -.. code-block:: bash +.. code-block:: none :copyable: false :emphasize-lines: 2-5 From 32c9698fd6eaba680b2401a14c92423c0144fed9 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 3 Sep 2024 13:53:54 -0400 Subject: [PATCH 07/13] JM most feedback --- source/read/change-streams.txt | 25 ++++++++----------------- 1 file changed, 8 insertions(+), 17 deletions(-) diff --git a/source/read/change-streams.txt b/source/read/change-streams.txt index 234be149..6c46e4e7 100644 --- a/source/read/change-streams.txt +++ b/source/read/change-streams.txt @@ -25,8 +25,10 @@ changes to your data. A change stream is a {+mdb-server+} feature that allows your application to subscribe to data changes on a collection, database, or deployment. -When using the {+php-library+}, you can create an instance of ``MongoDB\ChangeStream`` to -monitor data changes, such as updates, insertions, and deletions. +When using the {+php-library+}, you can call the ``watch()`` method to return an +instance of ``MongoDB\ChangeStream``. Then, you can iterate through change events stored +in the ``MongoDB\ChangeStream`` instance to monitor data changes, such as updates, +insertions, and deletions. Sample Data ~~~~~~~~~~~ @@ -34,7 +36,7 @@ Sample Data The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` database from the :atlas:`Atlas sample datasets `. To access this collection from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster -and assign the following value to your ``collection`` variable: +and create a ``$collection`` variable: .. literalinclude:: /includes/read/change-streams.php :language: php @@ -138,14 +140,6 @@ can set in the array: - | Specifies whether to show the full document as it was before the change, rather than showing only the changes made to the document. To learn more about this option, see :ref:`php-change-stream-pre-post-image`. - - * - ``resumeAfter`` - - | Instructs ``watch()`` to resume returning changes after the - operation specified in the resume token. - | Each change stream event document includes a resume token as the ``_id`` - field. Pass the entire ``_id`` field of the change event document that - represents the operation you want to resume after. - | This option is mutually exclusive with ``startAfter`` and ``startAtOperationTime``. * - ``startAfter`` - | Instructs ``watch()`` to start a new change stream after the @@ -161,10 +155,6 @@ can set in the array: the specified timestamp. | This option is mutually exclusive with ``startAfter`` and ``resumeAfter``. - * - ``typeMap`` - - | The type map to apply to cursors, which determines how BSON documents are converted - to PHP values. - * - ``collation`` - | Sets the collation to use for the change stream cursor. @@ -206,10 +196,11 @@ one of the following values: - ``MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP``: The change event includes a copy of the entire changed document from some time after the change. - ``MongoDB\Operation\Watch::FULL_DOCUMENT_WHEN_AVAILABLE``: The change event includes - a post-image of the modified document for change events only if the post-image is available. + a post-image of the modified document for change events. If the post-image is not + available, this change event field has a ``null`` value. - ``MongoDB\Operation\Watch::FULL_DOCUMENT_REQUIRED``: The change event includes a post-image of the modified document for change events. If the post-image is not available, the - {+php-library+} raises an error. + server raises an error. The following example calls the ``watch()`` method on a collection and includes the post-image of updated documents by setting the ``fullDocument`` option: From f201d6ad729901e65232f1ef69d7e1e655be32e6 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 3 Sep 2024 14:54:46 -0400 Subject: [PATCH 08/13] code edits --- source/includes/read/change-streams.php | 29 +++++++++++++++++++----- source/read/change-streams.txt | 30 ++++++++++++++----------- 2 files changed, 40 insertions(+), 19 deletions(-) diff --git a/source/includes/read/change-streams.php b/source/includes/read/change-streams.php index ef1baf12..00585836 100644 --- a/source/includes/read/change-streams.php +++ b/source/includes/read/change-streams.php @@ -1,6 +1,11 @@ toRelaxedExtendedJSON(); +} + $uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset'); $client = new MongoDB\Client($uri); @@ -12,8 +17,12 @@ // start-open-change-stream $changeStream = $collection->watch(); -foreach ($changeStream as $event) { - echo json_encode($event) . PHP_EOL; +for ($changeStream->rewind(); true; $changeStream->next()) { + if ( ! $changeStream->valid()) { + continue; + } + $event = $changeStream->current(); + echo toJSON($event) . PHP_EOL; } // end-open-change-stream @@ -30,8 +39,12 @@ $pipeline = [['$match' => ['operationType' => 'update']]]; $changeStream = $collection->watch($pipeline); -foreach ($changeStream as $event) { - echo json_encode($event) . PHP_EOL; +for ($changeStream->rewind(); true; $changeStream->next()) { + if ( ! $changeStream->valid()) { + continue; + } + $event = $changeStream->current(); + echo toJSON($event) . PHP_EOL; } // end-change-stream-pipeline @@ -40,8 +53,12 @@ $options = ['fullDocument' => MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP]; $changeStream = $collection->watch([], $options); -foreach ($changeStream as $event) { - echo json_encode($event) . PHP_EOL; +for ($changeStream->rewind(); true; $changeStream->next()) { + if ( ! $changeStream->valid()) { + continue; + } + $event = $changeStream->current(); + echo toJSON($event) . PHP_EOL; } // end-change-stream-post-image diff --git a/source/read/change-streams.txt b/source/read/change-streams.txt index 6c46e4e7..5c884067 100644 --- a/source/read/change-streams.txt +++ b/source/read/change-streams.txt @@ -86,10 +86,11 @@ as it occurs. The printed change event resembles the following output: .. code-block:: none :copyable: false - {"_id":{"_data":"..."},"operationType":"update","clusterTime":{"$timestamp":{...}, - "wallTime":{"$date":...},"ns":{"db":"sample_restaurants","coll":"restaurants"}, - "documentKey":{"_id":{"$oid":"..."}},"updateDescription":{"updatedFields": - {"cuisine":"Irish"},"removedFields":[],"truncatedArrays":[]}}} + { "_id" : { "_data" : "..." }, "operationType" : "update", "clusterTime" : + { "$timestamp" : { ... } }, "wallTime" : { "$date" : "..." }, "ns" : { "db" : + "sample_restaurants", "coll" : "restaurants" }, "documentKey" : { "_id" : + { "$oid" : "..." } }, "updateDescription" : { "updatedFields" : { "cuisine" : "Irish" }, + "removedFields" : [ ], "truncatedArrays" : [ ] } } Modify the Change Stream Output ------------------------------- @@ -218,15 +219,18 @@ output: .. code-block:: none :copyable: false - :emphasize-lines: 2-5 - - {"_id":{"_data":"..."},"operationType":"update","clusterTime":...},"wallTime":{"$date":...}, - "fullDocument":{"_id":{"$oid":"..."},"address": {"building":"202-24","coord": - [-73.925044200000002093,40.559546199999999772], "street":"Rockaway Point Boulevard", - "zipcode":"11697"},"borough":"Queens","cuisine":"Irish","grades":[...],"name":"Blarney Castle", - "restaurant_id":"40366356"},"ns":{"db":"sample_restaurants","coll":"restaurants"}, - "documentKey":{"_id":{"$oid":"..."}},"updateDescription":{"updatedFields":{"cuisine":"Irish"}, - "removedFields":[],"truncatedArrays":[]}} + :emphasize-lines: 3-7 + + { "_id" : { "_data" : "..." }, "operationType" : "update", "clusterTime" : + { "$timestamp" : { ... } }, "wallTime" : { "$date" : "..." }, + "fullDocument" : { "_id" : { "$oid" : "..." }, "address" : { "building" : + "202-24", "coord" : [ -73.925044200000002093, 40.559546199999999772 ], "street" + : "Rockaway Point Boulevard", "zipcode" : "11697" }, "borough" : "Queens", + "cuisine" : "Irish", "grades" : [ ...], "name" : "Blarney Castle", "restaurant_id" : + "40366356", "blank" : "Irish" }, "ns" : { "db" : "sample_restaurants", "coll" : + "restaurants" }, "documentKey" : { "_id" : { "$oid" : "..." } }, "updateDescription" : + { "updatedFields" : { "cuisine" : "Irish" }, "removedFields" : [ ], "truncatedArrays" : + [ ] } } .. tip:: From 90236306aec9a2f712f6fa24041132649bdfe612 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 3 Sep 2024 14:59:33 -0400 Subject: [PATCH 09/13] rest of tech feedback --- source/includes/read/change-streams.php | 2 ++ source/read/change-streams.txt | 9 +++++++++ 2 files changed, 11 insertions(+) diff --git a/source/includes/read/change-streams.php b/source/includes/read/change-streams.php index 00585836..bf530deb 100644 --- a/source/includes/read/change-streams.php +++ b/source/includes/read/change-streams.php @@ -1,10 +1,12 @@ toRelaxedExtendedJSON(); } +// end-to-json $uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset'); $client = new MongoDB\Client($uri); diff --git a/source/read/change-streams.txt b/source/read/change-streams.txt index 5c884067..85bd8b61 100644 --- a/source/read/change-streams.txt +++ b/source/read/change-streams.txt @@ -47,6 +47,15 @@ and create a ``$collection`` variable: To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the :atlas:`Get Started with Atlas ` guide. +Some examples use the ``toJSON()`` function to format change events, which are BSON +documents. To use this function, paste the following code into your application file: + +.. literalinclude:: /includes/read/change-streams.php + :language: php + :dedent: + :start-after: start-to-json + :end-before: end-to-json + Open a Change Stream -------------------- From 22a882c755b7bcd70c05fe44b03b8e7d271ea442 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 3 Sep 2024 15:07:07 -0400 Subject: [PATCH 10/13] edits --- source/read/change-streams.txt | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/source/read/change-streams.txt b/source/read/change-streams.txt index 85bd8b61..fa88e0db 100644 --- a/source/read/change-streams.txt +++ b/source/read/change-streams.txt @@ -36,7 +36,7 @@ Sample Data The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` database from the :atlas:`Atlas sample datasets `. To access this collection from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster -and create a ``$collection`` variable: +and assign the following value to your ``collection`` variable: .. literalinclude:: /includes/read/change-streams.php :language: php @@ -44,11 +44,14 @@ and create a ``$collection`` variable: :start-after: start-db-coll :end-before: end-db-coll -To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the -:atlas:`Get Started with Atlas ` guide. +.. tip:: -Some examples use the ``toJSON()`` function to format change events, which are BSON -documents. To use this function, paste the following code into your application file: + To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the + :atlas:`Get Started with Atlas ` guide. + +Some examples use the ``toJSON()`` function to represent change events, which are BSON +documents, as Extended JSON. To use this function, paste the following code into your +application file: .. literalinclude:: /includes/read/change-streams.php :language: php From a0c484ac80b21b467db0f6aec9ed17a620e67775 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 3 Sep 2024 15:08:43 -0400 Subject: [PATCH 11/13] typo --- source/read/change-streams.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/read/change-streams.txt b/source/read/change-streams.txt index fa88e0db..c423882d 100644 --- a/source/read/change-streams.txt +++ b/source/read/change-streams.txt @@ -36,7 +36,7 @@ Sample Data The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` database from the :atlas:`Atlas sample datasets `. To access this collection from your PHP application, instantiate a ``MongoDB\Client`` that connects to an Atlas cluster -and assign the following value to your ``collection`` variable: +and assign the following value to your ``$collection`` variable: .. literalinclude:: /includes/read/change-streams.php :language: php From f265d0c8e3935db85052a81dcc2796bbdfbc9cc3 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 3 Sep 2024 15:10:26 -0400 Subject: [PATCH 12/13] fix output --- source/read/change-streams.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/read/change-streams.txt b/source/read/change-streams.txt index c423882d..5ae591c4 100644 --- a/source/read/change-streams.txt +++ b/source/read/change-streams.txt @@ -231,7 +231,7 @@ output: .. code-block:: none :copyable: false - :emphasize-lines: 3-7 + :emphasize-lines: 3-6 { "_id" : { "_data" : "..." }, "operationType" : "update", "clusterTime" : { "$timestamp" : { ... } }, "wallTime" : { "$date" : "..." }, @@ -239,10 +239,10 @@ output: "202-24", "coord" : [ -73.925044200000002093, 40.559546199999999772 ], "street" : "Rockaway Point Boulevard", "zipcode" : "11697" }, "borough" : "Queens", "cuisine" : "Irish", "grades" : [ ...], "name" : "Blarney Castle", "restaurant_id" : - "40366356", "blank" : "Irish" }, "ns" : { "db" : "sample_restaurants", "coll" : - "restaurants" }, "documentKey" : { "_id" : { "$oid" : "..." } }, "updateDescription" : - { "updatedFields" : { "cuisine" : "Irish" }, "removedFields" : [ ], "truncatedArrays" : - [ ] } } + "40366356" }, "ns" : { "db" : "sample_restaurants", "coll" : "restaurants" }, + "documentKey" : { "_id" : { "$oid" : "..." } }, "updateDescription" : + { "updatedFields" : { "cuisine" : "Irish" }, "removedFields" : [ ], + "truncatedArrays" : [ ] } } .. tip:: From 4dfb66c842af1f108c1d2cdae391bacc3c313c52 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 5 Sep 2024 11:01:29 -0400 Subject: [PATCH 13/13] JM feedback 2 --- source/includes/read/change-streams.php | 12 ++++++++++++ source/read/change-streams.txt | 22 +++++++++++----------- 2 files changed, 23 insertions(+), 11 deletions(-) diff --git a/source/includes/read/change-streams.php b/source/includes/read/change-streams.php index bf530deb..5b51d1a6 100644 --- a/source/includes/read/change-streams.php +++ b/source/includes/read/change-streams.php @@ -25,6 +25,10 @@ function toJSON(object $document): string } $event = $changeStream->current(); echo toJSON($event) . PHP_EOL; + + if ($event['operationType'] === 'invalidate') { + break; + } } // end-open-change-stream @@ -47,6 +51,10 @@ function toJSON(object $document): string } $event = $changeStream->current(); echo toJSON($event) . PHP_EOL; + + if ($event['operationType'] === 'invalidate') { + break; + } } // end-change-stream-pipeline @@ -61,6 +69,10 @@ function toJSON(object $document): string } $event = $changeStream->current(); echo toJSON($event) . PHP_EOL; + + if ($event['operationType'] === 'invalidate') { + break; + } } // end-change-stream-post-image diff --git a/source/read/change-streams.txt b/source/read/change-streams.txt index 5ae591c4..757c1e7b 100644 --- a/source/read/change-streams.txt +++ b/source/read/change-streams.txt @@ -26,8 +26,8 @@ allows your application to subscribe to data changes on a collection, database, or deployment. When using the {+php-library+}, you can call the ``watch()`` method to return an -instance of ``MongoDB\ChangeStream``. Then, you can iterate through change events stored -in the ``MongoDB\ChangeStream`` instance to monitor data changes, such as updates, +instance of ``MongoDB\ChangeStream``. Then, you can iterate through the +``MongoDB\ChangeStream`` instance to monitor data changes, such as updates, insertions, and deletions. Sample Data @@ -81,8 +81,8 @@ and outputs changes as they occur: :dedent: To begin watching for changes, run the preceding code. Then, in a separate -application or shell, modify the ``restaurants`` collection. The following -example updates a document that has a ``name`` field value of ``'Blarney Castle'``: +shell, modify the ``restaurants`` collection. The following example updates +a document that has a ``name`` field value of ``'Blarney Castle'``: .. _php-change-stream-update: @@ -119,9 +119,9 @@ array: - ``$redact``: Restricts the contents of the documents - ``$unset``: Removes fields from documents -The following passes a pipeline that includes the ``$match`` stage to the ``watch()`` -method. This instructs the ``watch()`` method to output events only when update -operations occur: +The following example passes a pipeline that includes the ``$match`` stage to the +``watch()`` method. This instructs the ``watch()`` method to output events only +when update operations occur: .. literalinclude:: /includes/read/change-streams.php :start-after: start-change-stream-pipeline @@ -200,7 +200,7 @@ to one of the following values: change event field has a ``null`` value. - ``MongoDB\Operation\Watch::FULL_DOCUMENT_BEFORE_CHANGE_REQUIRED``: The change event includes a pre-image of the modified document for change events. If the pre-image is not available, the - {+php-library+} raises an error. + server raises an error. The **post-image** is the full version of a document *after* a change. To include the post-image in the change stream event, set the ``fullDocument`` option to @@ -224,9 +224,9 @@ of updated documents by setting the ``fullDocument`` option: :language: php :dedent: -With the change stream application running, updating a document in the -``restaurants`` collection by using the :ref:`preceding update example -` prints a change event resembling the following +With the change stream application running in a separate shell, updating a +document in the ``restaurants`` collection by using the :ref:`preceding update +example ` prints a change event resembling the following output: .. code-block:: none