Signatur
Beschreibung
MongoDB\Driver\Cursor ist eine nicht direkt instanziierbare Klasse, die von Methoden wie MongoDB\Driver\Manager::executeQuery() oder MongoDB\Driver\Manager::executeCommand() zurückgegeben wird. Sie kapselt die vom MongoDB-Server gelieferten Ergebnisdokumente und stellt sie als iterierbare Sequenz zur Verfügung.
Die Klasse implementiert das Iterator-Interface, sodass Cursor-Objekte direkt in foreach-Schleifen verwendet werden können. Standardmäßig werden die Dokumente als stdClass-Objekte zurückgegeben; mit setTypeMap() lässt sich jedoch steuern, in welchen PHP-Typ (z. B. assoziatives Array) die Dokumente umgewandelt werden.
Cursors können serverseitig oder clientseitig sein. Bei großen Ergebnismengen werden die Dokumente in Batches vom Server abgerufen (Tailable Cursors). Das Objekt hält dabei intern die Verbindung zum Server aufrecht, bis alle Dokumente abgerufen oder der Cursor explizit geschlossen wurde.
- Mit
toArray()können alle Dokumente auf einmal als PHP-Array geladen werden. - Mit
getId()lässt sich die serverseitige Cursor-ID abrufen. - Mit
setTypeMap()wird das Deserialisierungsverhalten gesteuert.
Beispiele
Einfache Abfrage mit foreach über einen Cursor
<?php
use MongoDB\Driver\Manager;
use MongoDB\Driver\Query;
$manager = new Manager('mongodb://localhost:27017');
$filter = ['status' => 'active'];
$options = ['limit' => 10, 'sort' => ['name' => 1]];
$query = new Query($filter, $options);
$cursor = $manager->executeQuery('mydb.users', $query);
// Cursor als Iterator verwenden
foreach ($cursor as $document) {
echo $document->name . ' — ' . $document->email . PHP_EOL;
}TypeMap setzen und alle Dokumente als Array laden
<?php
use MongoDB\Driver\Manager;
use MongoDB\Driver\Query;
$manager = new Manager('mongodb://localhost:27017');
$query = new Query([], ['limit' => 5]);
$cursor = $manager->executeQuery('mydb.products', $query);
// Dokumente als assoziative PHP-Arrays statt stdClass-Objekte
$cursor->setTypeMap([
'root' => 'array',
'document' => 'array',
'array' => 'array',
]);
$documents = $cursor->toArray();
foreach ($documents as $doc) {
echo $doc['name'] . ': ' . $doc['price'] . ' EUR' . PHP_EOL;
}Cursor-ID abrufen und prüfen ob serverseitiger Cursor offen ist
<?php
use MongoDB\Driver\Manager;
use MongoDB\Driver\Query;
$manager = new Manager('mongodb://localhost:27017');
$query = new Query([], ['batchSize' => 3]);
$cursor = $manager->executeQuery('mydb.logs', $query);
$cursorId = $cursor->getId();
echo 'Cursor-ID: ' . $cursorId . PHP_EOL;
// Dokumente der ersten Seite lesen
$batch = [];
foreach ($cursor as $doc) {
$batch[] = $doc;
if (count($batch) >= 3) break;
}
echo 'Dokumente im ersten Batch: ' . count($batch) . PHP_EOL;// Wichtig · Fallstricke
Cursor kann nur einmal iteriert werden: Ein Cursor-Objekt kann nach vollständigem Durchlauf nicht zurückgespult werden. Wenn die Dokumente mehrfach benötigt werden, sollte toArray() verwendet und das Ergebnis zwischengespeichert werden.
Speicherverbrauch: toArray() lädt alle Dokumente auf einmal in den Speicher. Bei sehr großen Ergebnismengen empfiehlt sich stattdessen das iterative Verarbeiten mit foreach, um den Speicherverbrauch gering zu halten.
Tailable Cursors: Für capped Collections kann mit der Option cursorType => MongoDB\Driver\Query::TAILABLE ein tailable Cursor erstellt werden, der auf neue Dokumente wartet. In diesem Fall blockiert der Cursor, bis neue Daten eintreffen oder das Timeout erreicht ist.
Fehlerbehandlung: Bei Netzwerkproblemen oder Timeout wirft der Cursor eine MongoDB\Driver\Exception\RuntimeException. Cursors sollten in try/catch-Blöcken verwendet werden.