MongoDB\Driver\CursorInterface — Interface · PHP-Referenz

Signatur

interface CursorInterface extends Traversable

Beschreibung

MongoDB\Driver\CursorInterface ist ein Interface aus dem offiziellen MongoDB-PHP-Treiber (mongodb-Extension), das die Grundstruktur für Cursor-Objekte festlegt. Cursor kapseln Abfrageergebnisse, die vom MongoDB-Server zurückgeliefert werden, und erlauben das iterative Durchlaufen großer Ergebnismengen, ohne alle Dokumente auf einmal in den Speicher laden zu müssen.

Das Interface erweitert Traversable, sodass implementierende Klassen direkt in foreach-Schleifen verwendet werden können. Es schreibt Methoden wie getId(), setTypeMap() und toArray() vor, die das Verhalten eines Cursors beschreiben: Identifikation des serverseitigen Cursors, Typkonvertierung der zurückgegebenen Dokumente sowie das vollständige Einlesen aller Ergebnisse.

In der Praxis begegnet man diesem Interface vor allem indirekt über die Klasse MongoDB\Driver\Cursor, die das Interface implementiert und von Methoden wie MongoDB\Driver\Manager::executeQuery() zurückgegeben wird. Eigene Implementierungen des Interfaces sind möglich, wenn man z. B. Mock-Objekte für Tests erstellen oder einen dekorativen Cursor-Wrapper bauen möchte.

Zu beachten ist, dass ein Cursor nach dem vollständigen Durchlauf nicht neu gestartet werden kann – er ist ein einmal lesbarer Stream. Soll die Ergebnismenge mehrfach iteriert werden, empfiehlt sich der Aufruf von toArray(), um alle Dokumente als PHP-Array zu materialisieren.

Beispiele

Abfrageergebnisse mit foreach iterieren

<?php
use MongoDB\Driver\Manager;
use MongoDB\Driver\Query;

$manager = new Manager('mongodb://localhost:27017');
$query = new Query(['status' => 'aktiv'], ['limit' => 10]);

// executeQuery() gibt ein Objekt zurück, das CursorInterface implementiert
$cursor = $manager->executeQuery('meineDatenbank.benutzer', $query);

// Typ-Map setzen: Dokumente als PHP-Array statt stdClass zurückgeben
$cursor->setTypeMap(['root' => 'array', 'document' => 'array', 'array' => 'array']);

foreach ($cursor as $dokument) {
    echo $dokument['name'] . PHP_EOL;
}

Eigene Test-Implementierung von CursorInterface

<?php
use MongoDB\Driver\CursorId;
use MongoDB\Driver\CursorInterface;

class FakeCursor implements CursorInterface
{
    private array $dokumente;
    private int $position = 0;

    public function __construct(array $dokumente)
    {
        $this->dokumente = $dokumente;
    }

    public function getId(): CursorId
    {
        return new CursorId(0);
    }

    public function getServer(): \MongoDB\Driver\Server
    {
        throw new \LogicException('Kein Server in FakeCursor vorhanden.');
    }

    public function isDead(): bool
    {
        return $this->position >= count($this->dokumente);
    }

    public function setTypeMap(array $typemap): void
    {
        // Im Fake ignorieren wir die Type-Map
    }

    public function toArray(): array
    {
        return $this->dokumente;
    }

    // Traversable via Iterator
    public function current(): mixed { return $this->dokumente[$this->position]; }
    public function key(): int { return $this->position; }
    public function next(): void { $this->position++; }
    public function rewind(): void { $this->position = 0; }
    public function valid(): bool { return isset($this->dokumente[$this->position]); }
}

$cursor = new FakeCursor([
    ['name' => 'Anna'],
    ['name' => 'Ben'],
]);

foreach ($cursor as $doc) {
    echo $doc['name'] . PHP_EOL;
}

Anna Ben

// Wichtig · Fallstricke

Cursor sind einmalig lesbar: Sobald ein echter MongoDB\Driver\Cursor vollständig iteriert wurde, kann er nicht mehr zurückgespult werden. Rufe toArray() auf, wenn du die Ergebnismenge mehrfach benötigst.

Speicherverbrauch: toArray() lädt alle Dokumente auf einmal in den PHP-Speicher. Bei sehr großen Ergebnismengen ist das schrittweise Iterieren via foreach zu bevorzugen.

Extension erforderlich: MongoDB\Driver\CursorInterface ist Teil der mongodb-PECL-Extension und nicht im veralteten mongo-Treiber vorhanden.

Siehe auch

MongoDB\Driver\Cursor MongoDB\Driver\Manager::executeQuery MongoDB\Driver\CursorId