MongoDB\BSON\Document — Klasse · PHP-Referenz

Signatur

final class MongoDB\BSON\Document implements MongoDB\BSON\Type, IteratorAggregate, Serializable, JsonSerializable

Beschreibung

MongoDB\BSON\Document ist eine unveränderliche (immutable) Klasse, die ein rohes BSON-Dokument in serialisierter Binärform kapselt. Im Gegensatz zu einem PHP-Array oder -Objekt muss das Dokument nicht vollständig in PHP-Datenstrukturen umgewandelt werden, bevor auf einzelne Felder zugegriffen wird – dies macht die Klasse besonders geeignet, wenn nur ein Teil der Felder eines großen Dokuments benötigt wird.

Instanzen können aus einem BSON-Binärstring (fromBSON()), einem JSON-String (fromJSON()) oder einem PHP-Array bzw. -Objekt (fromPHP()) erzeugt werden. Über get() lassen sich einzelne Felder lesen, während toPHP() das Dokument in eine PHP-Datenstruktur (Standard-Objekt oder eigene Klasse) umwandelt. Mit dem IteratorAggregate-Interface kann das Dokument mit foreach durchlaufen werden.

Die Klasse ist besonders nützlich, wenn BSON-Daten zwischen Systemen ausgetauscht, zwischengespeichert oder in ihrer Rohform weitergegeben werden sollen, ohne den Overhead einer vollständigen PHP-Deserialisierung zu erzeugen. Da das Objekt unveränderlich ist, sind keine In-Place-Modifikationen möglich – Änderungen erfordern eine neue Instanz.

Über Serializable kann das Dokument mit serialize()/unserialize() persistiert werden, und JsonSerializable ermöglicht die direkte Ausgabe via json_encode() als Extended JSON.

Beispiele

Dokument aus PHP-Array erstellen und Felder lesen

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

use MongoDB\BSON\Document;
use MongoDB\BSON\ObjectId;

// Dokument aus PHP-Array erstellen
$doc = Document::fromPHP([
    '_id'   => new ObjectId(),
    'name'  => 'Max Mustermann',
    'email' => 'max@example.com',
    'age'   => 42,
]);

// Einzelnes Feld lesen
echo $doc->get('name');  // Max Mustermann

// Prüfen, ob ein Feld vorhanden ist
var_dump($doc->has('email')); // bool(true)

// Alle Felder mit foreach durchlaufen
foreach ($doc as $key => $value) {
    echo "$key => " . (is_object($value) ? get_class($value) : $value) . PHP_EOL;
}

Max Mustermann bool(true) _id => MongoDB\BSON\ObjectId name => Max Mustermann email => max@example.com age => 42

Dokument aus BSON-Binärdaten und Rückkonvertierung nach PHP

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

use MongoDB\BSON\Document;

// Aus JSON erstellen (Extended JSON)
$json = '{"status": "aktiv", "punkte": {"$numberInt": "100"}}';
$doc = Document::fromJSON($json);

// Als BSON-Binär serialisieren (z. B. für Cache)
$bson = (string) $doc;

// Aus BSON-Binär wiederherstellen
$restored = Document::fromBSON($bson);

// In PHP-Objekt umwandeln
$phpObj = $restored->toPHP();
echo $phpObj->status;   // aktiv
echo $phpObj->punkte;   // 100

// Als JSON ausgeben
echo json_encode($doc);

aktiv 100 {"status":"aktiv","punkte":100}

Verwendung mit dem MongoDB-Treiber und partieller Feldverarbeitung

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

use MongoDB\Client;
use MongoDB\BSON\Document;

$client = new Client('mongodb://localhost:27017');
$collection = $client->testdb->users;

// Dokument als rohe BSON\Document-Instanz empfangen
$cursor = $collection->find(
    ['active' => true],
    ['typeMap' => ['root' => 'bson']]
);

foreach ($cursor as $doc) {
    /** @var Document $doc */
    // Nur den Namen lesen, ohne vollständige Deserialisierung
    echo $doc->get('name') . PHP_EOL;

    // Verschachtelte Dokumente prüfen
    if ($doc->has('address')) {
        $address = $doc->get('address');
        echo $address->get('city') . PHP_EOL;
    }
}

// Wichtig · Fallstricke

Unveränderlichkeit: MongoDB\BSON\Document ist immutable – einmal erzeugt, können keine Felder geändert oder hinzugefügt werden. Für Modifikationen muss das Dokument nach PHP konvertiert, angepasst und neu serialisiert werden.

Klassen-Verfügbarkeit: Die Klasse ist erst ab Version 1.16.0 der mongodb-PECL-Extension verfügbar. Bei älteren Versionen steht nur die generische MongoDB\Model\BSONDocument-Klasse aus der PHP-Bibliothek zur Verfügung.

Typkarte (typeMap): Beim Abruf von Dokumenten aus MongoDB muss in der typeMap-Option explizit 'root' => 'bson' oder 'document' => 'bson' angegeben werden, um Document-Instanzen zu erhalten statt Standard-PHP-Objekte.

get() vs. ArrayAccess: Die Klasse implementiert kein ArrayAccess – Zugriff über $doc['key'] ist nicht möglich; verwende stets $doc->get('key').

Siehe auch

MongoDB\BSON\Array MongoDB\BSON\PackedArray MongoDB\BSON\Type MongoDB\BSON\Serializable MongoDB\BSON\Unserializable MongoDB\BSON\toPHP MongoDB\BSON\fromPHP