MongoDB\BSON\toCanonicalExtendedJSON — Funktion · PHP-Referenz

Signatur

MongoDB\BSON\toCanonicalExtendedJSON(string $bson): string

Beschreibung

MongoDB\BSON\toCanonicalExtendedJSON() nimmt einen rohen BSON-String (binäres Format) und gibt die entsprechende Canonical Extended JSON-Darstellung als String zurück. Das Canonical-Format bewahrt dabei Typinformationen vollständig und explizit, zum Beispiel werden 64-Bit-Integer als {"$numberLong": "42"} dargestellt, sodass eine verlustfreie Hin- und Rück-Konvertierung möglich ist.

Das Format eignet sich ideal für Interoperabilität und maschinelle Verarbeitung, bei der Typintegrität wichtig ist – etwa beim Exportieren von Daten, beim Debugging oder beim Austausch von BSON-Dokumenten zwischen Systemen. Im Gegensatz zur relaxed-Variante (toRelaxedExtendedJSON) nutzt Canonical immer die expliziteste Typdarstellung, was zu längeren, aber typgenaueren JSON-Strings führt.

Die Funktion ist Teil der mongodb-Erweiterung für PHP und setzt voraus, dass diese installiert ist. Der übergebene String muss ein gültiges BSON-Dokument oder -Wert sein; ein ungültiger BSON-Input führt zu einer MongoDB\Driver\Exception\UnexpectedValueException.

Häufige Anwendungsfälle sind das Protokollieren von BSON-Daten in menschenlesbarer Form, die Weitergabe von Dokumenten an REST-APIs sowie das Serialisieren von MongoDB-Abfrageergebnissen für externe Systeme, die das Extended JSON-Format verstehen.

Parameter

Name	Typ	Default	Beschreibung
$bson Pflicht	string		Ein gültiger BSON-String (binäres Format), wie er typischerweise von `MongoDB\BSON\fromPHP()` erzeugt wird. Bei einem ungültigen BSON-String wird eine Exception geworfen.

Rückgabewert

Typ

string

Beschreibung

Gibt den BSON-Wert als Canonical Extended JSON-String zurück. Der String ist UTF-8-kodiert und enthält alle Typinformationen in expliziter Form gemäß der MongoDB Extended JSON v2-Spezifikation.

Beispiele

BSON-Dokument in Canonical Extended JSON umwandeln

<?php
// Benötigt die mongodb-Erweiterung

$document = [
    '_id'   => new MongoDB\BSON\ObjectId(),
    'name'  => 'Max Mustermann',
    'alter' => new MongoDB\BSON\Int64(42),
    'erstellt' => new MongoDB\BSON\UTCDateTime(),
];

// PHP-Array zu BSON serialisieren
$bson = MongoDB\BSON\fromPHP($document);

// BSON zu Canonical Extended JSON konvertieren
$json = MongoDB\BSON\toCanonicalExtendedJSON($bson);

echo $json;

{"_id":{"$oid":"64f1a2b3c4d5e6f7a8b9c0d1"},"name":"Max Mustermann","alter":{"$numberLong":"42"},"erstellt":{"$date":{"$numberLong":"1693526707000"}}}

Vergleich Canonical vs. Relaxed Extended JSON

<?php
// Dokument mit verschiedenen numerischen Typen
$document = [
    'ganzzahl'   => new MongoDB\BSON\Int64(9007199254740993), // > Number.MAX_SAFE_INTEGER
    'dezimal'    => new MongoDB\BSON\Decimal128('3.14159265358979323846'),
    'doppel'     => 1.5,
];

$bson = MongoDB\BSON\fromPHP($document);

$canonical = MongoDB\BSON\toCanonicalExtendedJSON($bson);
$relaxed   = MongoDB\BSON\toRelaxedExtendedJSON($bson);

echo "Canonical:\n" . $canonical . "\n\n";
echo "Relaxed:\n"   . $relaxed   . "\n";

Canonical: {"ganzzahl":{"$numberLong":"9007199254740993"},"dezimal":{"$numberDecimal":"3.14159265358979323846"},"doppel":{"$numberDouble":"1.5"}} Relaxed: {"ganzzahl":{"$numberLong":"9007199254740993"},"dezimal":{"$numberDecimal":"3.14159265358979323846"},"doppel":1.5}

// Wichtig · Fallstricke

Typintegrität: Das Canonical-Format ist die einzige verlustfreie Option für den Datenaustausch: Jede BSON-Konvertierung mit anschließender Rückkonvertierung (fromRelaxedExtendedJSON oder fromCanonicalExtendedJSON) liefert exakt das ursprüngliche Dokument zurück. Beim Relaxed-Format kann bei 64-Bit-Integers und Doubles die genaue Typinformation verloren gehen.

Fehlerbehandlung: Bei ungültigem BSON-Input wird eine MongoDB\Driver\Exception\UnexpectedValueException geworfen. Der Input sollte daher stets mit MongoDB\BSON\fromPHP() oder aus einer vertrauenswürdigen MongoDB-Quelle stammen.

Performance: Das Canonical-Format erzeugt größere JSON-Strings als das Relaxed-Format, da alle Typen explizit kodiert werden. Für große Datensätze sollte dies bei der Wahl des Formats berücksichtigt werden.

Siehe auch

MongoDB\BSON\toRelaxedExtendedJSON MongoDB\BSON\fromPHP MongoDB\BSON\toPHP MongoDB\BSON\fromCanonicalExtendedJSON MongoDB\BSON\fromRelaxedExtendedJSON