Skip to content

Commit 2873fe4

Browse files
jmikolajmikola
committed
Merge pull request #495 
2 parents 521fd64 + 9a7f85e commit 2873fe4

16 files changed

+794
-6
lines changed

‎source/reference.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,5 +13,6 @@ Reference
1313
/reference/class/MongoDBCollection
1414
/reference/class/MongoDBGridFSBucket
1515
/reference/write-result-classes
16+
/reference/result-classes
1617
/reference/enumeration-classes
1718
/reference/exception-classes

‎source/reference/method/MongoDBChangeStream-current.txt‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
================================
2+
MongoDB\\ChangeStream::current()
3+
================================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
Definition
14+
----------
15+
16+
.. phpmethod:: MongoDB\\ChangeStream::current()
17+
18+
Returns the current event in the change stream.
19+
20+
.. code-block:: php
21+
22+
function current(): array|object|null
23+
24+
The structure of each event document will vary based on the operation type.
25+
See :manual:`Change Events </reference/change-events/>` in the MongoDB manual
26+
for more information.
27+
28+
Return Values
29+
-------------
30+
31+
An array or object for the current event in the change stream, or ``null`` if
32+
there is no current event (i.e. :phpmethod:`MongoDB\\ChangeStream::valid()`
33+
returns ``false``). The return type will depend on the ``typeMap`` option for
34+
:phpmethod:`MongoDB\\Collection::watch()`.
35+
36+
Examples
37+
--------
38+
39+
This example reports events while iterating a change stream.
40+
41+
.. code-block:: php
42+
43+
<?php
44+
45+
$uri = 'mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet';
46+
47+
$collection = (new MongoDB\Client($uri))->test->inventory;
48+
49+
$changeStream = $collection->watch();
50+
51+
for ($changeStream->rewind(); true; $changeStream->next()) {
52+
if ( ! $changeStream->valid()) {
53+
continue;
54+
}
55+
56+
$event = $changeStream->current();
57+
58+
$ns = sprintf('%s.%s', $event['ns']['db'], $event['ns']['coll']);
59+
$id = json_encode($event['documentKey']['_id']);
60+
61+
switch ($event['operationType']) {
62+
case 'delete':
63+
printf("Deleted document in %s with _id: %s\n\n", $ns, $id);
64+
break;
65+
66+
case 'insert':
67+
printf("Inserted new document in %s\n", $ns);
68+
echo json_encode($event['fullDocument']), "\n\n";
69+
break;
70+
71+
case 'replace':
72+
printf("Replaced new document in %s with _id: %s\n", $ns, $id);
73+
echo json_encode($event['fullDocument']), "\n\n";
74+
break;
75+
76+
case 'update':
77+
printf("Updated document in %s with _id: %s\n", $ns, $id);
78+
echo json_encode($event['updateDescription']), "\n\n";
79+
break;
80+
}
81+
}
82+
83+
Assuming that a document was inserted, updated, and deleted while the above
84+
script was iterating the change stream, the output would then resemble:
85+
86+
.. code-block:: none
87+
88+
Inserted new document in test.inventory
89+
{"_id":{"$oid":"5a81fc0d6118fd1af1790d32"},"name":"Widget","quantity":5}
90+
91+
Updated document in test.inventory with _id: {"$oid":"5a81fc0d6118fd1af1790d32"}
92+
{"updatedFields":{"quantity":4},"removedFields":[]}
93+
94+
Deleted document in test.inventory with _id: {"$oid":"5a81fc0d6118fd1af1790d32"}
95+
96+
See Also
97+
--------
98+
99+
- :phpmethod:`MongoDB\\Collection::watch()`
100+
- :php:`Iterator::current() <iterator.current>`
101+
- :ref:`Tailable Cursor Iteration <php-tailable-cursor>`
102+
- :manual:`Change Streams </changeStreams>` documentation in the MongoDB manual
103+
- :manual:`Change Events </reference/change-events/>` documentation in the
104+
MongoDB manual

‎source/reference/method/MongoDBChangeStream-getCursorId.txt‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
====================================
2+
MongoDB\\ChangeStream::getCursorId()
3+
====================================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
Definition
14+
----------
15+
16+
.. phpmethod:: MongoDB\\ChangeStream::getCursorId()
17+
18+
Returns the change stream cursor's ID.
19+
20+
.. code-block:: php
21+
22+
function getCursorId(): MongoDB\Driver\CursorId
23+
24+
Return Values
25+
-------------
26+
27+
A :php:`MongoDB\\Driver\\CursorId <class.mongodb-driver-cursorid>` object.
28+
29+
Examples
30+
--------
31+
32+
This example reports the cursor ID for a change stream.
33+
34+
.. code-block:: php
35+
36+
<?php
37+
38+
$uri = 'mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet';
39+
40+
$collection = (new MongoDB\Client($uri))->test->inventory;
41+
42+
$changeStream = $collection->watch();
43+
44+
var_dump($changeStream->getCursorId());
45+
46+
The output would then resemble::
47+
48+
object(MongoDB\Driver\CursorId)#5 (1) {
49+
["id"]=>
50+
int(8462642181784669708)
51+
}
52+
53+
See Also
54+
--------
55+
56+
- :phpmethod:`MongoDB\\Collection::watch()`
57+
- :php:`MongoDB\\Driver\\CursorId <class.mongodb-driver-cursorid>`
58+
- :php:`MongoDB\\Driver\\Cursor::getId() <manual/en/mongodb-driver-cursor.getid.php>`

‎source/reference/method/MongoDBChangeStream-key.txt‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
============================
2+
MongoDB\\ChangeStream::key()
3+
============================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
Definition
14+
----------
15+
16+
.. phpmethod:: MongoDB\\ChangeStream::key()
17+
18+
Returns the index of the current event in the change stream.
19+
20+
.. code-block:: php
21+
22+
function key(): integer|null
23+
24+
The index of the first event in a change stream starts at zero and will
25+
increment by one for each subsequent event.
26+
27+
Return Values
28+
-------------
29+
30+
The index of the current event in the change stream, or ``null`` if there is no
31+
current event (i.e. :phpmethod:`MongoDB\\ChangeStream::valid()` returns
32+
``false``).
33+
34+
Examples
35+
--------
36+
37+
This example reports the index of events while iterating a change stream.
38+
39+
.. code-block:: php
40+
41+
<?php
42+
43+
$uri = 'mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet';
44+
45+
$collection = (new MongoDB\Client($uri))->test->inventory;
46+
47+
$changeStream = $collection->watch();
48+
49+
for ($changeStream->rewind(); true; $changeStream->next()) {
50+
if ( ! $changeStream->valid()) {
51+
continue;
52+
}
53+
54+
$event = $changeStream->current();
55+
56+
printf("%d: %s\n", $changeStream->key(), $event['operationType']);
57+
}
58+
59+
Assuming that a document was inserted, updated, and deleted while the above
60+
script was iterating the change stream, the output would then resemble:
61+
62+
.. code-block:: none
63+
64+
0: insert
65+
1: update
66+
2: delete
67+
68+
See Also
69+
--------
70+
71+
- :phpmethod:`MongoDB\\Collection::watch()`
72+
- :php:`Iterator::key() <iterator.key>`
73+
- :ref:`Tailable Cursor Iteration <php-tailable-cursor>`
74+
- :manual:`Change Streams </changeStreams>` documentation in the MongoDB manual

‎source/reference/method/MongoDBChangeStream-next.txt‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
=============================
2+
MongoDB\\ChangeStream::next()
3+
=============================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
Definition
14+
----------
15+
16+
.. phpmethod:: MongoDB\\ChangeStream::next()
17+
18+
Advances the change stream and attempts to load the next event.
19+
20+
.. code-block:: php
21+
22+
function next(): void
23+
24+
.. note::
25+
26+
Advancing the change stream does not guarantee that there will be a
27+
current event to access. You should still call
28+
:phpmethod:`MongoDB\\ChangeStream::valid()` to check for a current event
29+
at each step of iteration.
30+
31+
Errors/Exceptions
32+
-----------------
33+
34+
.. include:: /includes/extracts/error-driver-runtimeexception.rst
35+
36+
See Also
37+
--------
38+
39+
- :phpmethod:`MongoDB\\Collection::watch()`
40+
- :php:`Iterator::next() <iterator.next>`
41+
- :ref:`Tailable Cursor Iteration <php-tailable-cursor>`
42+
- :manual:`Change Streams </changeStreams>` documentation in the MongoDB manual

‎source/reference/method/MongoDBChangeStream-rewind.txt‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
===============================
2+
MongoDB\\ChangeStream::rewind()
3+
===============================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
Definition
14+
----------
15+
16+
.. phpmethod:: MongoDB\\ChangeStream::rewind()
17+
18+
Rewinds the change stream and attempts to load the first event.
19+
20+
.. code-block:: php
21+
22+
function rewind(): void
23+
24+
This method should be called at the start of change stream iteration.
25+
26+
.. note::
27+
28+
Rewinding the change stream does not guarantee that there will be a
29+
current event to access. You should still call
30+
:phpmethod:`MongoDB\\ChangeStream::valid()` to check for a current event
31+
at each step of iteration. After initially rewinding the change stream,
32+
:phpmethod:`MongoDB\\ChangeStream::next()` should be used to iterate
33+
further.
34+
35+
Errors/Exceptions
36+
-----------------
37+
38+
:php:`MongoDB\\Driver\\Exception\\LogicException
39+
<mongodb-driver-exception-logicexception>` if this method is called after a call
40+
to :phpmethod:`MongoDB\\ChangeStream::next()` (i.e. the underlying
41+
:php:`MongoDB\\Driver\\Cursor <class.mongodb-driver-cursor>` has already been
42+
advanced).
43+
44+
.. include:: /includes/extracts/error-driver-runtimeexception.rst
45+
46+
See Also
47+
--------
48+
49+
- :phpmethod:`MongoDB\\Collection::watch()`
50+
- :php:`Iterator::rewind() <iterator.rewind>`
51+
- :ref:`Tailable Cursor Iteration <php-tailable-cursor>`
52+
- :manual:`Change Streams </changeStreams>` documentation in the MongoDB manual

‎source/reference/method/MongoDBChangeStream-valid.txt‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
==============================
2+
MongoDB\\ChangeStream::valid()
3+
==============================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
Definition
14+
----------
15+
16+
.. phpmethod:: MongoDB\\ChangeStream::valid()
17+
18+
Returns whether there is a current event in the change stream.
19+
20+
.. code-block:: php
21+
22+
function valid(): boolean
23+
24+
When manually iterating the change stream using
25+
:php:`Iterator </manual/en/class.iterator.php>` methods, this method should
26+
be used to determine if :phpmethod:`MongoDB\\ChangeStream::current()` and
27+
:phpmethod:`MongoDB\\ChangeStream::key()` can be called.
28+
29+
Return Values
30+
-------------
31+
32+
A boolean indicating whether there is a current event in the change stream.
33+
34+
See Also
35+
--------
36+
37+
- :phpmethod:`MongoDB\\Collection::watch()`
38+
- :php:`Iterator::valid() <iterator.valid>`
39+
- :ref:`Tailable Cursor Iteration <php-tailable-cursor>`
40+
- :manual:`Change Streams </changeStreams>` documentation in the MongoDB manual

0 commit comments

Comments
 (0)