DOCSP-41981: Change streams

source/includes/read/change-streams.php

@@ -0,0 +1,47 @@
+<?php
+require 'vendor/autoload.php'; 
+
+$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);
+
+// start-db-coll
+$collection = $client->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' => MongoDB\Operation\Watch::FULL_DOCUMENT_UPDATE_LOOKUP];
+$changeStream = $collection->watch([], $options);
+
+foreach ($changeStream as $event) {
+    echo json_encode($event) . PHP_EOL;
+}
+// end-change-stream-post-image
+

source/read.txt

@@ -10,4 +10,5 @@ Read Data from MongoDB
 
    /read/retrieve
    /read/project
+   /read/change-streams
 

source/read/change-streams.txt

@@ -0,0 +1,254 @@
+.. _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 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.
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
+database from the :atlas:`Atlas sample datasets </sample-data>`. 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 </getting-started>` guide.
+
+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 instances of 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 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.
+       | This option 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.
+       | This option is mutually exclusive with ``resumeAfter`` and ``startAtOperationTime``.
+
+   * - ``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.
+
+For a full list of ``watch()`` options, see `MongoDB\\Collection::watch()
+<{+api+}/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`` option
+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
+  {+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`` option to
+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.
+- ``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.
+
+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
+<php-change-stream-update>` prints a change event resembling the following
+code:
+
+.. code-block:: bash
+   :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":[]}}
+
+.. tip::
+
+   To learn more about pre-images and post-images, see 
+   :manual:`Change Streams with Document Pre- and Post-Images </changeStreams#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
+</changeStreams>` 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/>`__