Skip to content

DOCSP-43912: Improve change stream code examples #264

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 0 additions & 78 deletions source/includes/read/change-streams.php

This file was deleted.

32 changes: 32 additions & 0 deletions source/includes/read/change-streams/change-stream-options.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
<?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();

do {
$changeStream->next();

if ($changeStream->valid()) {
$event = $changeStream->current();
echo toJSON($event), PHP_EOL;
}
} while (! $changeStream->valid() || $changeStream->current()['operationType'] !== 'invalidate');
Comment on lines +24 to +31
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On reflection, this notation is much more complex than the previous example.

In my original comment the idea was rather to use while(true) like this:

Suggested change
do {
$changeStream->next();
if ($changeStream->valid()) {
$event = $changeStream->current();
echo toJSON($event), PHP_EOL;
}
} while (! $changeStream->valid() || $changeStream->current()['operationType'] !== 'invalidate');
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
40 changes: 40 additions & 0 deletions source/includes/read/change-streams/change-stream-pipeline.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
<?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();

do {
$changeStream->next();

if ($changeStream->valid()) {
$event = $changeStream->current();
echo toJSON($event), PHP_EOL;
}
} while (! $changeStream->valid() || $changeStream->current()['operationType'] !== 'invalidate');
// end-change-stream-pipeline
39 changes: 39 additions & 0 deletions source/includes/read/change-streams/change-stream.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
<?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();

do {
$changeStream->next();

if ($changeStream->valid()) {
$event = $changeStream->current();
echo toJSON($event), PHP_EOL;
}
} while (! $changeStream->valid() || $changeStream->current()['operationType'] !== 'invalidate');
// 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing newline at EOF.

Suggested change
// end-update-for-change-stream
// end-update-for-change-stream

16 changes: 7 additions & 9 deletions source/includes/usage-examples/read-code-examples.php
Original file line number Diff line number Diff line change
Expand Up @@ -52,16 +52,14 @@
// Data Changes
// start-change-stream
$changeStream = $collection->watch();
$changeStream->rewind();

for ($changeStream->rewind(); true; $changeStream->next()) {
if ( ! $changeStream->valid()) {
continue;
}
$event = $changeStream->current();
echo toJSON($event), PHP_EOL;
do {
$changeStream->next();

if ($event['operationType'] === 'invalidate') {
break;
if ($changeStream->valid()) {
$event = $changeStream->current();
echo toJSON($event) . PHP_EOL;
}
}
} while (! $changeStream->valid() || $changeStream->current()['operationType'] !== 'invalidate');
// end-change-stream
12 changes: 6 additions & 6 deletions source/read/change-streams.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading