DOCSP-43912: Improve change stream code examples (#264)

(cherry picked from commit 4129a38)

Author: mcmorisi

source/includes/read/change-streams.php

@@ -0,0 +1,38 @@
+<?php
+require 'vendor/autoload.php'; 
+
+// start-to-json
+function toJSON(object $document): string
+{
+    return MongoDB\BSON\Document::fromPHP($document)->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);
+
+// start-db-coll
+$collection = $client->sample_restaurants->restaurants;
+// end-db-coll
+
+// 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);
+$changeStream->rewind();
+
+while (true) {
+    $changeStream->next();
+
+    if ($changeStream->valid()) {
+        continue;
+    }
+
+    $event = $changeStream->current();
+    echo toJSON($event), PHP_EOL;
+
+    if ($changeStream->current()['operationType'] === 'invalidate') {
+        break;
+    }
+}
+// end-change-stream-post-image

source/includes/read/change-streams/change-stream-options.php

@@ -0,0 +1,46 @@
+<?php
+require 'vendor/autoload.php'; 
+
+// start-to-json
+function toJSON(object $document): string
+{
+    return MongoDB\BSON\Document::fromPHP($document)->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);
+
+// start-db-coll
+$collection = $client->sample_restaurants->restaurants;
+// end-db-coll
+
+// 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);
+$changeStream->rewind();
+
+while (true) {
+    $changeStream->next();
+
+    if ($changeStream->valid()) {
+        continue;
+    }
+
+    $event = $changeStream->current();
+    echo toJSON($event), PHP_EOL;
+
+    if ($changeStream->current()['operationType'] === 'invalidate') {
+        break;
+    }
+}
+// end-change-stream-pipeline

source/includes/read/change-streams/change-stream-pipeline.php

@@ -0,0 +1,45 @@
+<?php
+require 'vendor/autoload.php'; 
+
+// start-to-json
+function toJSON(object $document): string
+{
+    return MongoDB\BSON\Document::fromPHP($document)->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);
+
+// 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();
+$changeStream->rewind();
+
+while (true) {
+    $changeStream->next();
+
+    if ($changeStream->valid()) {
+        continue;
+    }
+
+    $event = $changeStream->current();
+    echo toJSON($event), PHP_EOL;
+
+    if ($changeStream->current()['operationType'] === 'invalidate') {
+        break;
+    }
+}
+// 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

source/includes/read/change-streams/change-stream.php

@@ -52,15 +52,19 @@
 // Data Changes
 // start-change-stream
 $changeStream = $collection->watch();
+$changeStream->rewind();
 
-for ($changeStream->rewind(); true; $changeStream->next()) {
-    if ( ! $changeStream->valid()) {
+while (true) {
+    $changeStream->next();
+
+    if ($changeStream->valid()) {
         continue;
     }
+
     $event = $changeStream->current();
     echo toJSON($event), PHP_EOL;
 
-    if ($event['operationType'] === 'invalidate') {
+    if ($changeStream->current()['operationType'] === 'invalidate') {
         break;
     }
 }

source/includes/usage-examples/read-code-examples.php

@@ -38,7 +38,7 @@ database from the :atlas:`Atlas sample datasets </sample-data>`. To access this
 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
+.. literalinclude:: /includes/read/change/streams/change-stream.php
    :language: php
    :dedent:
    :start-after: start-db-coll
@@ -53,7 +53,7 @@ Some examples use the ``toJSON()`` function to represent change events, which ar
 documents, as Extended JSON. To use this function, paste the following code into your
 application file:
 
-.. literalinclude:: /includes/read/change-streams.php
+.. literalinclude:: /includes/read/change-streams/change-stream.php
    :language: php
    :dedent:
    :start-after: start-to-json
@@ -74,7 +74,7 @@ classes:
 The following example opens a change stream on the ``restaurants`` collection
 and outputs changes as they occur:
 
-.. literalinclude:: /includes/read/change-streams.php
+.. literalinclude:: /includes/read/change-streams/change-stream.php
    :start-after: start-open-change-stream
    :end-before: end-open-change-stream
    :language: php
@@ -86,7 +86,7 @@ a document that has a ``name`` field value of ``'Blarney Castle'``:
 
 .. _php-change-stream-update:
 
-.. literalinclude:: /includes/read/change-streams.php
+.. literalinclude:: /includes/read/change-streams/change-stream.php
    :start-after: start-update-for-change-stream
    :end-before: end-update-for-change-stream
    :language: php
@@ -123,7 +123,7 @@ The following example passes a pipeline that includes the ``$match`` stage to th
 ``watch()`` method. This instructs the ``watch()`` method to output events only
 when update operations occur:
 
-.. literalinclude:: /includes/read/change-streams.php
+.. literalinclude:: /includes/read/change-streams/change-stream-pipeline.php
    :start-after: start-change-stream-pipeline
    :end-before: end-change-stream-pipeline
    :language: php
@@ -223,7 +223,7 @@ one of the following values:
 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
+.. literalinclude:: /includes/read/change-streams/change-stream-options.php
    :start-after: start-change-stream-post-image
    :end-before: end-change-stream-post-image
    :language: php