MongoDB\BSON\Iterator — Klasse · PHP-Referenz

Signatur

interface MongoDB\BSON\Iterator extends Iterator

Beschreibung

MongoDB\BSON\Iterator ist ein Interface im MongoDB PHP-Treiber, das die Iteration über BSON-Arrays und BSON-Dokumente ermöglicht. Es erweitert das native PHP-Iterator-Interface und stellt sicher, dass BSON-Datenstrukturen mit foreach-Schleifen und anderen Iterator-Mechanismen durchlaufen werden können.

BSON (Binary JSON) ist das Datenformat, das MongoDB intern zur Speicherung von Dokumenten verwendet. Klassen wie MongoDB\BSON\Document und MongoDB\BSON\PackedArray implementieren dieses Interface, sodass ihre Felder und Elemente sequenziell ausgelesen werden können, ohne die gesamte Datenstruktur vorab in ein PHP-Array konvertieren zu müssen.

Das Interface eignet sich besonders dann, wenn große BSON-Strukturen speichereffizient verarbeitet werden sollen oder wenn ein einheitlicher Zugriff auf BSON-Dokumente und -Arrays über Typprüfungen (instanceof) benötigt wird. Durch die Erweiterung des Standard-PHP-Iterator-Interfaces sind alle üblichen Iterator-Methoden (current(), key(), next(), rewind(), valid()) verfügbar.

In der Praxis implementieren konkrete Klassen wie MongoDB\BSON\Document dieses Interface. Eigene Klassen können es ebenfalls implementieren, um BSON-kompatible Iterationslogik bereitzustellen.

Beispiele

Iteration über ein BSON-Dokument mit foreach

<?php
require 'vendor/autoload.php';

use MongoDB\BSON\Document;

// BSON-Dokument aus einem PHP-Array erstellen
$doc = Document::fromPHP([
    'name'  => 'Alice',
    'age'   => 30,
    'city'  => 'Berlin',
]);

// Sicherstellen, dass das Dokument das Iterator-Interface implementiert
if ($doc instanceof MongoDB\BSON\Iterator) {
    echo "Dokument ist iterierbar." . PHP_EOL;
}

// Mit foreach über alle Felder des Dokuments iterieren
foreach ($doc as $key => $value) {
    echo $key . ': ' . var_export($value, true) . PHP_EOL;
}

Dokument ist iterierbar. name: 'Alice' age: 30 city: 'Berlin'

Typgeprüfte Verarbeitung von BSON-Iterables

<?php
require 'vendor/autoload.php';

use MongoDB\BSON\Document;
use MongoDB\BSON\PackedArray;
use MongoDB\BSON\Iterator as BsonIterator;

function verarbeiteBsonIterable(BsonIterator $iterable): void {
    foreach ($iterable as $key => $value) {
        if ($value instanceof BsonIterator) {
            echo "[{$key}] => (verschachteltes Iterable)" . PHP_EOL;
            verarbeiteBsonIterable($value);
        } else {
            echo "[{$key}] => " . var_export($value, true) . PHP_EOL;
        }
    }
}

$doc = Document::fromPHP([
    'titel'   => 'Einführung',
    'tags'    => ['php', 'mongodb', 'bson'],
    'version' => 1,
]);

verarbeiteBsonIterable($doc);

[titel] => 'Einführung' [tags] => (verschachteltes Iterable) [0] => 'php' [1] => 'mongodb' [2] => 'bson' [version] => 1

// Wichtig · Fallstricke

Hinweis zur Verfügbarkeit: MongoDB\BSON\Iterator ist Bestandteil der MongoDB PHP-Extension (ext-mongodb). Es ist nicht Teil der höherstufigen MongoDB PHP Library, auch wenn beide häufig gemeinsam verwendet werden.

Unterschied zu IteratorAggregate: Das Interface erbt direkt von PHPs Iterator, nicht von IteratorAggregate. Klassen, die es implementieren, müssen daher alle fünf Iterator-Methoden (current, key, next, rewind, valid) selbst bereitstellen.

Einmalige Iteration: BSON-Iteratoren können je nach konkreter Implementierung nur einmalig oder nach einem rewind() erneut durchlaufen werden. Prüfe das Verhalten der jeweiligen konkreten Klasse.

Siehe auch

MongoDB\BSON\Document MongoDB\BSON\PackedArray MongoDB\BSON\Serializable MongoDB\BSON\Unserializable Iterator