The MongoCursor class

Introduction

A cursor is used to iterate through the results of a database query. For
example, to query the database and see all results, you could do:

Example #1 MongoCursor basic usage

<?php

$cursor = $collection->find();var_dump(iterator_to_array($cursor));

?>

You don't generally create cursors using the
MongoCursor constructor, you get a new cursor by
calling MongoCollection::find() (as shown above).

Suppose that, in the example above, $collection was a
50GB collection. We certainly wouldn't want to load that into memory all
at once, which is what a cursor is for: allowing the client to access the
collection in dribs and drabs.

If we have a large result set, we can iterate through it, loading a few
megabytes of results into memory at a time. For example, we could do:

Example #2 Iterating over MongoCursor

<?php

$cursor = $collection->find();

foreach ($cursor as $doc) {// do something to each document}

?>

This will go through each document in the collection, loading and garbage
collecting documents as needed.

Note that this means that a cursor does not "contain" the database results,
it just manages them. Thus, if you print a cursor (with, say,
var_dump() or print_r()), you'll just
get the cursor object, not your documents. To get the documents themselves,
you can use one of the methods shown above.

Cursor Stages

A MongoCursor has two "life stages": pre- and post-
query. When a cursor is created, it has not yet contacted the database, so
it is in its pre-query state. In this state, the client can further specify
what they want the query to do, including adding limits, skips, sorts, and
more advanced options.

When the client attempts to get a result (by calling
MongoCursor::next(), directly or indirectly), the cursor
moves into the post-query stage. At this point, the query has been executed
by the database and cannot be modified anymore.

Example #3 Adding options to MongoCursor

<?php

$cursor = $collection->find()->limit(10);

// database has not yet been queried, so more search options can be added$cursor = $cursor->sort(array("a" => 1));

var_dump($cursor->getNext());// now database has been queried and more options cannot be added

Set timeout in milliseconds for all database responses. Use
-1 to wait forever. Can be overridden with
MongoCursor::timeout(). This does not cause the
MongoDB server to cancel the operation; it only instructs the driver to
stop waiting for a response and throw a
MongoCursorTimeoutException after a set time.