DOCSP-41981: Change streams

[norareidy]

Pull Request Info

PR Reviewing Guidelines

JIRA - https://jira.mongodb.org/browse/DOCSP-41981
Staging - https://preview-mongodbnorareidy.gatsbyjs.io/php-library/DOCSP-41981-change-streams/read/change-streams/

Self-Review Checklist

• Is this free of any warnings or errors in the RST?
• Did you run a spell-check?
• Did you run a grammar-check?
• Are all the links working?
• Are the facets and meta keywords accurate?

[rustagir]

a few small things!

[rustagir]

Suggested change

	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.

[rustagir]

S: change the type to none instead of bash, as this is output not a command. I think console might work too

[rustagir]

Suggested change

	The following passes a pipeline that includes the ``$match`` stage to the ``watch()``
	method. This instructs the ``watch()`` method to output only update operations:
	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:

[rustagir]

Suggested change

	as a parameter to ``watch()``. The following table describes some options you
	as a parameter to ``watch()``. The following table describes useful options you

[rustagir]

Suggested change

	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.

[rustagir]

S: since you mention startAtOperationTime, maybe you can include it in this table

[rustagir]

Suggested change

	code:
	output:

[rustagir]

lgtm!

[jmikola]

foreach loops are not suitable for iterating tailable cursors (such as those returned for change streams), as the loop will terminate as soon as there are no documents to consume. In other words, foreach prevents us from actually polling the cursor and waiting for additional data.

This is why the PHPLIB docs had a Tailable Cursor Iteration tutorial. The existing examples in the watch() API reference demonstrate an equivalent approach, with added code to break out of the loop should we receive an "invalidate" event.

I'm not sure if this script is ever intended to be executed in its entirety, or simply serve as an assortment of snippets to include in the rendered docs. But if you're using the proper approach to iterate the change stream, note that the first loop is unlikely to terminate on its own and that would prevent subsequent statements in the file from executing.

[norareidy]

I changed these loops to for loops and edited based on the examples you linked - let me know what you think

[jmikola]

New iteration examples look good. Thanks.

[jmikola]

Something that just occurred to me: should this tutorial advise users to run this PHP code through a shell/terminal? Users would likely run into issues trying to execute the watch() process through a web server.

I'm curious if there's language from other language tutorials (assuming this was adapted from existing content) we can use.

The most straightforward way to address this might be to consistently refer to "shell process" instead of "application or shell" for all of the code examples (no harm in using that for the update example as well).

[norareidy]

We use "application" pretty consistently across all docs, but I agree that it makes sense to suggest running the application from the shell. I updated all mentions of running the application on this page to clarify that

[jmikola]

I think "updating" should be "update".

Per my earlier comment about pointing users away from using a web server, the following might be clearer:

With the change stream application running in a separate shell, update a document...

[norareidy]

Added "in a separate shell" - "updating" makes more grammatical sense in this case

[jmikola]

"updating" makes more grammatical sense in this case

My mistake. I missed that the sentence continued with "prints a change event..." after the :ref: link.