From 6e0dcb630db52f7a851d1d065fb2a3d72fe9c551 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 21 Aug 2024 14:59:18 -0400 Subject: [PATCH 01/10] DOCSP-41980: Cursor guide --- snooty.toml | 1 + source/includes/read/cursor.php | 63 +++++++++++ source/read.txt | 3 +- source/read/cursor.txt | 178 ++++++++++++++++++++++++++++++++ 4 files changed, 244 insertions(+), 1 deletion(-) create mode 100644 source/includes/read/cursor.php create mode 100644 source/read/cursor.txt diff --git a/snooty.toml b/snooty.toml index 507f09d6..04139ce2 100644 --- a/snooty.toml +++ b/snooty.toml @@ -25,3 +25,4 @@ php-library = "MongoDB PHP Library" [constants] php-library = "MongoDB PHP Library" api = "https://www.mongodb.com/docs/php-library/current/reference" +php-manual = "https://www.php.net/manual/en" diff --git a/source/includes/read/cursor.php b/source/includes/read/cursor.php new file mode 100644 index 00000000..a66b95f3 --- /dev/null +++ b/source/includes/read/cursor.php @@ -0,0 +1,63 @@ +sample_restaurants->restaurants; +// end-db-coll + +// Iterates over and prints all documents that have a "name" value of "Dunkin' Donuts" +// start-cursor-iterate +$cursor = $collection->find(['name' => 'Dunkin\' Donuts']); +foreach ($cursor as $doc) { + echo json_encode($doc) . PHP_EOL; +} +// end-cursor-iterate + +// Retrieves and prints the first document stored in the cursor +// start-cursor-first +$cursor = $collection->find(['name' => 'Dunkin\' Donuts']); +echo json_encode($cursor->current()); +// end-cursor-first + +// Converts the documents stored in a cursor to an array +// start-cursor-array +$cursor = $collection->find(['name' => 'Dunkin\' Donuts']); +$array_results = $cursor->toArray(); +// end-cursor-array + +// Creates a collection with a maximum size and inserts documents representing vegetables +// start-capped-coll +$db = $client->db; +$collection = $db->createCollection( + 'vegetables', + ['capped' => true, 'size' => 1024 * 1024] +); + +$vegetables = [ + ['name' => 'cauliflower'], + ['name' => 'zucchini'] +]; + +$result = $collection->insertMany($vegetables); +// end-capped-coll + +// Iterates over the initial query results and continues iterating until three documents are stored in the cursor +// by using a tailable cursor +// start-tailable +$cursor = $collection->find([], ['cursorType' => 'tailable']); + +$docs_found = 0; +while ($docs_found < 3) { + foreach ($cursor as $doc) { + echo json_encode($doc) . PHP_EOL; + $docs_found++; + } + + // Sleeps for 100 milliseconds before trying to access more documents + usleep(100000); // 100 milliseconds +} +// end-tailable + diff --git a/source/read.txt b/source/read.txt index eb974b7f..c92db516 100644 --- a/source/read.txt +++ b/source/read.txt @@ -8,4 +8,5 @@ Read Data from MongoDB :titlesonly: :maxdepth: 1 - /read/retrieve \ No newline at end of file + /read/retrieve + /read/cursor \ No newline at end of file diff --git a/source/read/cursor.txt b/source/read/cursor.txt new file mode 100644 index 00000000..e1ebb10a --- /dev/null +++ b/source/read/cursor.txt @@ -0,0 +1,178 @@ +.. _php-cursors: + +========================= +Access Data From a Cursor +========================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: read, results, oplog + +Overview +-------- + +In this guide, you can learn how to access data from a **cursor** by using the +{+php-library+}. + +A cursor is a mechanism that returns the results of a read operation in iterable +batches. Cursors reduce both memory consumption and network bandwidth usage by holding +only a subset of documents at any given time rather than returning all documents at +once. + +Whenever the {+php-library+} performs a read operation by using the ``MongoDB\Collection::find()`` +method, it returns the matching documents in a ``MongoDB\Driver\Cursor`` instance. + +Sample Data +~~~~~~~~~~~ + +The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` +database from the :atlas:`Atlas sample datasets `. 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/distinct.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 ` guide. + +.. _php-cursors-iterate: + +Access Cursor Contents Iteratively +---------------------------------- + +To iterate over the contents of a ``MongoDB\Driver\Cursor`` instance, use a ``foreach`` loop. + +The following example uses the ``MongoDB\Collection::find()`` method to retrieve all documents +in which the ``name`` value is ``'Dunkin' Donuts'``. It then prints each document from the +cursor returned by the ``find()`` method: + +.. io-code-block:: + :copyable: + + .. input:: /includes/read/cursor.php + :start-after: start-cursor-iterate + :end-before: end-cursor-iterate + :language: php + :dedent: + + .. output:: + :visible: false + + { "_id" : { "$oid" : "..." }, ... "name" : "Dunkin' Donuts", "restaurant_id" : "40379573" } + { "_id" : { "$oid" : "..." }, ... "name" : "Dunkin' Donuts", "restaurant_id" : "40363098" } + { "_id" : { "$oid" : "..." }, ... "name" : "Dunkin' Donuts", "restaurant_id" : "40395071" } + ... + +Retrieve Documents Individually +------------------------------- + +To retrieve an individual document from a cursor, call the ``current()`` method on +a ``MongoDB\Driver\Cursor`` instance. This method returns the document that the cursor +currently points to. You can continue to advance the cursor by calling the ``next()`` +method, which instructs the cursor to point to the next retrieved document. + +The following example finds all documents in a collection that have a ``name`` value +of ``'Dunkin' Donuts'``. Then, it prints the first retrieved document by calling the +``current()`` method on a cursor: + +.. io-code-block:: + :copyable: + + .. input:: /includes/read/cursor.php + :start-after: start-cursor-first + :end-before: end-cursor-first + :language: php + :dedent: + + .. output:: + + { "_id" : { "$oid" : "..." }, ... "name" : "Dunkin' Donuts", "restaurant_id" : "40379573" } + +Retrieve All Documents +---------------------- + +.. warning:: + + If the number and size of documents returned by your query exceeds available + application memory, your program will crash. If you expect a large result + set, :ref:`access your cursor iteratively `. + +To retrieve all documents from a cursor, convert the cursor into an array as +shown in the following example: + +.. literalinclude:: /includes/read/cursor.php + :language: php + :dedent: + :start-after: start-cursor-array + :end-before: end-cursor-array + +Tailable Cursors +---------------- + +When querying on a :manual:`capped collection `, you +can use a **tailable cursor** that remains open after the client exhausts the +results in a cursor. To create a tailable cursor, set the ``cursorType`` option to +``tailable`` in an array. Then, pass the array as an options parameter to +the ``MongoDB\Collection::find()`` method. + +For example, you can create a capped collection called ``vegetables`` that stores +documents representing vegetables, as shown in the following code: + +.. literalinclude:: /includes/read/cursor.php + :language: php + :dedent: + :start-after: start-capped-coll + :end-before: end-capped-coll + +The following code uses a tailable cursor to retrieve all documents in the ``vegetables`` +collection. After the cursor is exhausted, it remains open until retrieving three documents: + +.. io-code-block:: + :copyable: + + .. input:: /includes/read/cursor.php + :start-after: start-tailable + :end-before: end-tailable + :language: php + :dedent: + + .. output:: + + { "_id" : { "$oid" : "..." }, "name" : "cauliflower" } + { "_id" : { "$oid" : "..." }, "name" : "zucchini" } + +If you insert another document into the ``vegetables`` collection, the preceding code prints +the new document and closes the ``while`` loop. + +To learn more about tailable cursors, see the :manual:`Tailable Cursors guide +` in the {+mdb-server+} manual. + +Additional Information +---------------------- + +To learn more about read operations, see the :ref:`php-retrieve` guide. + +To learn more about cursors, see the following pages in the PHP manual: + +- `MongoDB\Driver\Cursor <{+php-manual+}/class.mongodb-driver-cursor.php>`__ +- `MongoDB\Driver\Cursor::current() <{+php-manual+}/mongodb-driver-cursor.current.php>`__ +- `MongoDB\Driver\Cursor::toArray() <{+php-manual+}/mongodb-driver-cursor.toarray.php>`__ + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about the ``find()`` method, see `MongoDB\\Collection::find() +<{+api+}/method/MongoDBCollection-find/>`__ in the API documentation. \ No newline at end of file From 1564f6195d675b1f215834e6c0f6140f1edd934f Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 21 Aug 2024 15:04:03 -0400 Subject: [PATCH 02/10] edits --- source/read/cursor.txt | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/source/read/cursor.txt b/source/read/cursor.txt index e1ebb10a..3a047e24 100644 --- a/source/read/cursor.txt +++ b/source/read/cursor.txt @@ -15,7 +15,7 @@ Access Data From a Cursor :values: reference .. meta:: - :keywords: read, results, oplog + :keywords: read, results, code example Overview -------- @@ -39,7 +39,7 @@ database from the :atlas:`Atlas sample datasets `. 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/distinct.php +.. literalinclude:: /includes/read/cursor.php :language: php :dedent: :start-after: start-db-coll @@ -71,9 +71,9 @@ cursor returned by the ``find()`` method: .. output:: :visible: false - { "_id" : { "$oid" : "..." }, ... "name" : "Dunkin' Donuts", "restaurant_id" : "40379573" } - { "_id" : { "$oid" : "..." }, ... "name" : "Dunkin' Donuts", "restaurant_id" : "40363098" } - { "_id" : { "$oid" : "..." }, ... "name" : "Dunkin' Donuts", "restaurant_id" : "40395071" } + {"_id":{"$oid":"..."},..."name":"Dunkin' Donuts","restaurant_id":"40379573"} + {"_id":{"$oid":"..."},..."name":"Dunkin' Donuts","restaurant_id":"40363098"} + {"_id":{"$oid":"..."},..."name":"Dunkin' Donuts","restaurant_id":"40395071"} ... Retrieve Documents Individually @@ -99,7 +99,7 @@ of ``'Dunkin' Donuts'``. Then, it prints the first retrieved document by calling .. output:: - { "_id" : { "$oid" : "..." }, ... "name" : "Dunkin' Donuts", "restaurant_id" : "40379573" } + {"_id":{"$oid":"..."},..."name":"Dunkin' Donuts","restaurant_id":"40379573"} Retrieve All Documents ---------------------- @@ -151,8 +151,8 @@ collection. After the cursor is exhausted, it remains open until retrieving thre .. output:: - { "_id" : { "$oid" : "..." }, "name" : "cauliflower" } - { "_id" : { "$oid" : "..." }, "name" : "zucchini" } + {"_id":{"$oid":"..."},"name":"cauliflower"} + {"_id":{"$oid":"..."},"name":"zucchini"} If you insert another document into the ``vegetables`` collection, the preceding code prints the new document and closes the ``while`` loop. @@ -167,9 +167,9 @@ To learn more about read operations, see the :ref:`php-retrieve` guide. To learn more about cursors, see the following pages in the PHP manual: -- `MongoDB\Driver\Cursor <{+php-manual+}/class.mongodb-driver-cursor.php>`__ -- `MongoDB\Driver\Cursor::current() <{+php-manual+}/mongodb-driver-cursor.current.php>`__ -- `MongoDB\Driver\Cursor::toArray() <{+php-manual+}/mongodb-driver-cursor.toarray.php>`__ +- `MongoDB\\Driver\\Cursor <{+php-manual+}/class.mongodb-driver-cursor.php>`__ +- `MongoDB\\Driver\\Cursor::current() <{+php-manual+}/mongodb-driver-cursor.current.php>`__ +- `MongoDB\\Driver\\Cursor::toArray() <{+php-manual+}/mongodb-driver-cursor.toarray.php>`__ API Documentation ~~~~~~~~~~~~~~~~~ From 9f8d700a5e23963c5b0144d36bff015b82e9295f Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 21 Aug 2024 15:20:12 -0400 Subject: [PATCH 03/10] code edits --- source/includes/read/cursor.php | 7 ++++--- source/read/cursor.txt | 4 ++-- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/source/includes/read/cursor.php b/source/includes/read/cursor.php index a66b95f3..5cae4836 100644 --- a/source/includes/read/cursor.php +++ b/source/includes/read/cursor.php @@ -31,7 +31,7 @@ // Creates a collection with a maximum size and inserts documents representing vegetables // start-capped-coll $db = $client->db; -$collection = $db->createCollection( +$create_coll = $db->createCollection( 'vegetables', ['capped' => true, 'size' => 1024 * 1024] ); @@ -41,13 +41,14 @@ ['name' => 'zucchini'] ]; +$collection = $db->vegetables; $result = $collection->insertMany($vegetables); // end-capped-coll // Iterates over the initial query results and continues iterating until three documents are stored in the cursor // by using a tailable cursor // start-tailable -$cursor = $collection->find([], ['cursorType' => 'tailable']); +$cursor = $collection->find([], ['cursorType' => MongoDB\Operation\Find::TAILABLE]); $docs_found = 0; while ($docs_found < 3) { @@ -57,7 +58,7 @@ } // Sleeps for 100 milliseconds before trying to access more documents - usleep(100000); // 100 milliseconds + usleep(100000); } // end-tailable diff --git a/source/read/cursor.txt b/source/read/cursor.txt index 3a047e24..995ccf92 100644 --- a/source/read/cursor.txt +++ b/source/read/cursor.txt @@ -125,8 +125,8 @@ Tailable Cursors When querying on a :manual:`capped collection `, you can use a **tailable cursor** that remains open after the client exhausts the results in a cursor. To create a tailable cursor, set the ``cursorType`` option to -``tailable`` in an array. Then, pass the array as an options parameter to -the ``MongoDB\Collection::find()`` method. +``MongoDB\Operation\Find::TAILABLE`` in an array. Then, pass the array as an options +parameter to the ``MongoDB\Collection::find()`` method. For example, you can create a capped collection called ``vegetables`` that stores documents representing vegetables, as shown in the following code: From 1f24caface973ea770eac3c48aa5d717433fa221 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 21 Aug 2024 15:27:21 -0400 Subject: [PATCH 04/10] output --- source/read/cursor.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/read/cursor.txt b/source/read/cursor.txt index 995ccf92..49ee1618 100644 --- a/source/read/cursor.txt +++ b/source/read/cursor.txt @@ -150,7 +150,8 @@ collection. After the cursor is exhausted, it remains open until retrieving thre :dedent: .. output:: - + :visible: false + {"_id":{"$oid":"..."},"name":"cauliflower"} {"_id":{"$oid":"..."},"name":"zucchini"} From 1ce380173094e7047e5b186d6c1e6504db313b16 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 21 Aug 2024 15:29:22 -0400 Subject: [PATCH 05/10] vale fix --- source/read/cursor.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/read/cursor.txt b/source/read/cursor.txt index 49ee1618..3128d401 100644 --- a/source/read/cursor.txt +++ b/source/read/cursor.txt @@ -81,7 +81,7 @@ Retrieve Documents Individually To retrieve an individual document from a cursor, call the ``current()`` method on a ``MongoDB\Driver\Cursor`` instance. This method returns the document that the cursor -currently points to. You can continue to advance the cursor by calling the ``next()`` +initially points to. You can continue to advance the cursor by calling the ``next()`` method, which instructs the cursor to point to the next retrieved document. The following example finds all documents in a collection that have a ``name`` value @@ -151,7 +151,7 @@ collection. After the cursor is exhausted, it remains open until retrieving thre .. output:: :visible: false - + {"_id":{"$oid":"..."},"name":"cauliflower"} {"_id":{"$oid":"..."},"name":"zucchini"} From 0bac6cf7117c31794c1a0528a21affbd9184023b Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 22 Aug 2024 10:29:15 -0400 Subject: [PATCH 06/10] MM feedback --- source/read/cursor.txt | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/source/read/cursor.txt b/source/read/cursor.txt index 3128d401..9a5ed399 100644 --- a/source/read/cursor.txt +++ b/source/read/cursor.txt @@ -24,9 +24,9 @@ In this guide, you can learn how to access data from a **cursor** by using the {+php-library+}. A cursor is a mechanism that returns the results of a read operation in iterable -batches. Cursors reduce both memory consumption and network bandwidth usage by holding -only a subset of documents at any given time rather than returning all documents at -once. +batches. Cursors reduce both memory consumption and the number of server requests +by holding only a subset of documents at any given time, rather than returning all +documents at once. Whenever the {+php-library+} performs a read operation by using the ``MongoDB\Collection::find()`` method, it returns the matching documents in a ``MongoDB\Driver\Cursor`` instance. @@ -56,7 +56,7 @@ Access Cursor Contents Iteratively To iterate over the contents of a ``MongoDB\Driver\Cursor`` instance, use a ``foreach`` loop. The following example uses the ``MongoDB\Collection::find()`` method to retrieve all documents -in which the ``name`` value is ``'Dunkin' Donuts'``. It then prints each document from the +in which the ``name`` field value is ``'Dunkin' Donuts'``. It then prints each document from the cursor returned by the ``find()`` method: .. io-code-block:: @@ -84,8 +84,8 @@ a ``MongoDB\Driver\Cursor`` instance. This method returns the document that the initially points to. You can continue to advance the cursor by calling the ``next()`` method, which instructs the cursor to point to the next retrieved document. -The following example finds all documents in a collection that have a ``name`` value -of ``'Dunkin' Donuts'``. Then, it prints the first retrieved document by calling the +The following example finds all documents in which the ``name`` field value is +``'Dunkin' Donuts'``. Then, it prints the first retrieved document by calling the ``current()`` method on a cursor: .. io-code-block:: @@ -110,8 +110,8 @@ Retrieve All Documents application memory, your program will crash. If you expect a large result set, :ref:`access your cursor iteratively `. -To retrieve all documents from a cursor, convert the cursor into an array as -shown in the following example: +To retrieve all documents from a cursor, convert the cursor into an array. The following +example calls the ``toArray()`` method on a cursor to store its results in an array: .. literalinclude:: /includes/read/cursor.php :language: php @@ -158,7 +158,7 @@ collection. After the cursor is exhausted, it remains open until retrieving thre If you insert another document into the ``vegetables`` collection, the preceding code prints the new document and closes the ``while`` loop. -To learn more about tailable cursors, see the :manual:`Tailable Cursors guide +To learn more about tailable cursors, see :manual:`Tailable Cursors ` in the {+mdb-server+} manual. Additional Information @@ -175,5 +175,5 @@ To learn more about cursors, see the following pages in the PHP manual: API Documentation ~~~~~~~~~~~~~~~~~ -To learn more about the ``find()`` method, see `MongoDB\\Collection::find() -<{+api+}/method/MongoDBCollection-find/>`__ in the API documentation. \ No newline at end of file +To learn more about the ``find()`` method, see the API documentation for +`MongoDB\\Collection::find() <{+api+}/method/MongoDBCollection-find/>`__. \ No newline at end of file From 692b09c7517044c527f409ce505d71db474930e0 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 22 Aug 2024 10:30:50 -0400 Subject: [PATCH 07/10] edit --- source/read/cursor.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/read/cursor.txt b/source/read/cursor.txt index 9a5ed399..df10053e 100644 --- a/source/read/cursor.txt +++ b/source/read/cursor.txt @@ -98,7 +98,8 @@ The following example finds all documents in which the ``name`` field value is :dedent: .. output:: - + :visible: false + {"_id":{"$oid":"..."},..."name":"Dunkin' Donuts","restaurant_id":"40379573"} Retrieve All Documents From b2d600ed4cc5284557935e7a493127afc0bf131a Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 3 Sep 2024 16:41:28 -0400 Subject: [PATCH 08/10] fix code ex --- source/includes/read/cursor.php | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/source/includes/read/cursor.php b/source/includes/read/cursor.php index 5cae4836..75e27a36 100644 --- a/source/includes/read/cursor.php +++ b/source/includes/read/cursor.php @@ -5,7 +5,8 @@ $client = new MongoDB\Client($uri); // start-db-coll -$collection = $client->sample_restaurants->restaurants; +$db = $client->sample_restaurants; +$collection = $db->restaurants; // end-db-coll // Iterates over and prints all documents that have a "name" value of "Dunkin' Donuts" @@ -19,6 +20,7 @@ // Retrieves and prints the first document stored in the cursor // start-cursor-first $cursor = $collection->find(['name' => 'Dunkin\' Donuts']); +$cursor->rewind(); echo json_encode($cursor->current()); // end-cursor-first @@ -49,16 +51,15 @@ // by using a tailable cursor // start-tailable $cursor = $collection->find([], ['cursorType' => MongoDB\Operation\Find::TAILABLE]); +$cursor->rewind(); $docs_found = 0; while ($docs_found < 3) { - foreach ($cursor as $doc) { + if ($cursor->valid()) { + $doc = $cursor->current(); echo json_encode($doc) . PHP_EOL; $docs_found++; } - - // Sleeps for 100 milliseconds before trying to access more documents - usleep(100000); + $cursor->next(); } // end-tailable - From fcecd1ff025bf8dda6403b83347daf840e896985 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 3 Sep 2024 16:43:04 -0400 Subject: [PATCH 09/10] edit --- source/includes/read/cursor.php | 3 +-- source/read/cursor.txt | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/source/includes/read/cursor.php b/source/includes/read/cursor.php index 75e27a36..7747a52c 100644 --- a/source/includes/read/cursor.php +++ b/source/includes/read/cursor.php @@ -5,8 +5,7 @@ $client = new MongoDB\Client($uri); // start-db-coll -$db = $client->sample_restaurants; -$collection = $db->restaurants; +$collection = $client->sample_restaurants->restaurants; // end-db-coll // Iterates over and prints all documents that have a "name" value of "Dunkin' Donuts" diff --git a/source/read/cursor.txt b/source/read/cursor.txt index df10053e..5fd52b4c 100644 --- a/source/read/cursor.txt +++ b/source/read/cursor.txt @@ -37,7 +37,7 @@ Sample Data The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` database from the :atlas:`Atlas sample datasets `. 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: +and assign the following value to your ``$collection`` variable: .. literalinclude:: /includes/read/cursor.php :language: php From f8fa613b38f734d979f938a29d5c55691786a599 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 9 Sep 2024 14:36:37 -0400 Subject: [PATCH 10/10] JT feedback --- source/read/cursor.txt | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/source/read/cursor.txt b/source/read/cursor.txt index 5fd52b4c..1fb36fb6 100644 --- a/source/read/cursor.txt +++ b/source/read/cursor.txt @@ -53,7 +53,8 @@ To learn how to create a free MongoDB Atlas cluster and load the sample datasets Access Cursor Contents Iteratively ---------------------------------- -To iterate over the contents of a ``MongoDB\Driver\Cursor`` instance, use a ``foreach`` loop. +The ``MongoDB\Driver\Cursor`` class implements the ``Iterator`` interface, so you +can use a ``foreach`` loop to iterate through its contents. The following example uses the ``MongoDB\Collection::find()`` method to retrieve all documents in which the ``name`` field value is ``'Dunkin' Donuts'``. It then prints each document from the @@ -111,8 +112,14 @@ Retrieve All Documents application memory, your program will crash. If you expect a large result set, :ref:`access your cursor iteratively `. -To retrieve all documents from a cursor, convert the cursor into an array. The following -example calls the ``toArray()`` method on a cursor to store its results in an array: +To retrieve all documents from a cursor, convert the cursor into an array by using +either of the following methods: + +- ``MongoDB\\Driver\\Cursor::toArray()``: Call on a ``MongoDB\Driver\Cursor`` object +- ``iterator_to_array()``: Pass a ``MongoDB\Driver\Cursor`` object as a parameter + +The following example calls the ``toArray()`` method on a cursor to store its results +in an array: .. literalinclude:: /includes/read/cursor.php :language: php @@ -172,6 +179,7 @@ To learn more about cursors, see the following pages in the PHP manual: - `MongoDB\\Driver\\Cursor <{+php-manual+}/class.mongodb-driver-cursor.php>`__ - `MongoDB\\Driver\\Cursor::current() <{+php-manual+}/mongodb-driver-cursor.current.php>`__ - `MongoDB\\Driver\\Cursor::toArray() <{+php-manual+}/mongodb-driver-cursor.toarray.php>`__ +- `iterator_to_array() <{+php-manual+}/function.iterator-to-array.php>`__ API Documentation ~~~~~~~~~~~~~~~~~