MongoDB\BSON\toRelaxedExtendedJSON — Funktion · PHP-Referenz

Signatur

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

Beschreibung

MongoDB\BSON\toRelaxedExtendedJSON() konvertiert einen rohen BSON-Binärstring in das Relaxed Extended JSON-Format (Version 2). Dieses Format wurde von MongoDB spezifiziert und stellt BSON-Typen als menschenlesbare JSON-Objekte dar, wobei nativen JSON-Typen (z. B. Zahlen) Vorrang vor typbehafteten Wrapper-Objekten eingeräumt wird. So wird etwa ein BSON-Int32 als einfache JSON-Zahl ausgegeben, nicht als { "$numberInt": "42" }.

Im Vergleich zum Canonical Extended JSON-Format (siehe MongoDB\BSON\toCanonicalExtendedJSON()) ist das Relaxed-Format kompakter und besser lesbar, bewahrt aber keine vollständige Typgenauigkeit für alle BSON-Typen. Es eignet sich daher besonders für Debugging, Logging und den Datenaustausch mit Systemen, bei denen exakte BSON-Typinformation nicht zwingend erforderlich ist.

Die Funktion erwartet einen rohen BSON-Binärstring, wie er beispielsweise von MongoDB\BSON\fromPHP() erzeugt wird. Der Rückgabewert ist immer ein gültiger UTF-8-JSON-String. Ungültige BSON-Eingaben führen zu einer MongoDB\Driver\Exception\UnexpectedValueException.

Geeignet für: Logging, Debugging, Export in lesbare Formate
Nicht geeignet für: verlustfreie Rundtrips aller BSON-Typen (dafür Canonical verwenden)

Parameter

Name	Typ	Default	Beschreibung
$bson Pflicht	string		Ein roher BSON-Binärstring, wie er z. B. von `MongoDB\BSON\fromPHP()` erzeugt wird. Ungültige BSON-Daten führen zu einer Exception.

Rückgabewert

Typ

string

Beschreibung

Gibt einen UTF-8-kodierten JSON-String im Relaxed Extended JSON v2-Format zurück, der die BSON-Daten repräsentiert.

Beispiele

PHP-Array zu BSON und dann zu Relaxed Extended JSON

<?php
// PHP-Array in BSON umwandeln
$phpDoc = [
    'name'    => 'Max Mustermann',
    'alter'   => 42,
    'aktiv'   => true,
    'erstellt' => new MongoDB\BSON\UTCDateTime(new DateTimeImmutable('2024-01-15')),
];

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

// BSON in Relaxed Extended JSON umwandeln
$json = MongoDB\BSON\toRelaxedExtendedJSON($bson);

echo $json;

{"name":"Max Mustermann","alter":42,"aktiv":true,"erstellt":{"$date":"2024-01-15T00:00:00Z"}}

Vergleich: Relaxed vs. Canonical Extended JSON

<?php
$phpDoc = [
    'zahl'    => 123,
    'id'      => new MongoDB\BSON\ObjectId('507f1f77bcf86cd799439011'),
];

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

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

echo "Relaxed:   " . $relaxed   . PHP_EOL;
echo "Canonical: " . $canonical . PHP_EOL;

Relaxed: {"zahl":123,"id":{"$oid":"507f1f77bcf86cd799439011"}} Canonical: {"zahl":{"$numberInt":"123"},"id":{"$oid":"507f1f77bcf86cd799439011"}}

// Wichtig · Fallstricke

Typpräzision: Das Relaxed-Format verzichtet auf explizite Typauszeichnung für native JSON-Typen (Integers, Doubles, Booleans, Strings). Wer BSON-Daten verlustfrei re-importieren muss, sollte MongoDB\BSON\toCanonicalExtendedJSON() verwenden und anschließend MongoDB\BSON\fromCanonicalExtendedJSON() zum Einlesen nutzen.

Fehlerbehandlung: Bei ungültigem BSON-Input wird eine MongoDB\Driver\Exception\UnexpectedValueException geworfen. Eingaben sollten daher stets aus vertrauenswürdigen Quellen stammen oder zuvor validiert werden.

Verfügbarkeit: Diese Funktion ist Teil der mongodb-PECL-Extension und nicht im Standard-PHP enthalten. Sie erfordert die Extension in Version 1.2.0 oder höher.

Siehe auch

MongoDB\BSON\toCanonicalExtendedJSON MongoDB\BSON\fromPHP MongoDB\BSON\toPHP MongoDB\BSON\fromRelaxedExtendedJSON MongoDB\BSON\fromCanonicalExtendedJSON