(PECL mongo >=1.5.0)
A command cursor is used to iterate through the results of a database command. A command cursor is similar to a normal MongoCursor except that you use it for iterating through the result of a server command instead of a the result of a query.
You don't generally create cursors using the MongoCommandCursor constructor, you get a new cursor by calling MongoCollection::commandCursor().
Using a command cursor instead of MongoDB::command() means that you can iterate over a much larger resultset as the return of MongoDB::command() is limited to the maximum document size (currently 16MB).
Note that the cursor does not "contain" the database command 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.
A MongoCommandCursor 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 configuring the batch size.
When the client attempts to get a result (by calling MongoCommandCursor::next(), directly or indirectly), the cursor moves into the post-command stage. At this point, the command has been executed by the database and only its batch size can be configured.
Example #1 Adding options to MongoCommandCursor
<?php
$cursor = new MongoCommandCursor(...);
// database has not yet been queried, so more options can be added
$cursor = $cursor->batchSize( 4 );
var_dump($cursor->getNext());
// now database has been queried and more options cannot be added
?>
$connection
, string $hash
, array $document
)