MongoDB\BSON\toJSON — Funktion · PHP-Referenz

Signatur

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

Beschreibung

MongoDB\BSON\toJSON() nimmt einen rohen, binär kodierten BSON-String entgegen und gibt die zugehörige Legacy Extended JSON-Darstellung als PHP-String zurück. Diese Funktion ist nützlich, wenn BSON-Daten zur Inspektion, Protokollierung oder zur Weitergabe an andere Systeme in ein lesbares Textformat umgewandelt werden sollen.

Das erzeugte Format entspricht der Legacy Extended JSON-Spezifikation von MongoDB (auch bekannt als Strict Mode JSON). Für das neuere Canonical Extended JSON oder Relaxed Extended JSON (gemäß EJSON v2) stehen die Methoden MongoDB\BSON\Document::toCanonicalExtendedJSON() bzw. MongoDB\BSON\Document::toRelaxedExtendedJSON() zur Verfügung.

Die Funktion ist in erster Linie für Debugging-Zwecke gedacht. In produktivem Code ist es häufig sinnvoller, BSON-Werte über die entsprechenden Objekte der MongoDB\BSON-Erweiterung zu deserialisieren (MongoDB\BSON\toPHP()) und dort weiterzuverarbeiten.

Der übergebene $bson-Parameter muss ein gültiger, vollständiger BSON-Dokument-String sein – andernfalls wird eine MongoDB\Driver\Exception\UnexpectedValueException ausgelöst.

Parameter

Name	Typ	Default	Beschreibung
$bson Pflicht	string		Ein binärer BSON-kodierter String, der ein gültiges BSON-Dokument repräsentiert. Kann z. B. mit `MongoDB\BSON\fromPHP()` erzeugt werden.

Rückgabewert

Typ

string

Beschreibung

Gibt die Legacy Extended JSON-Darstellung des BSON-Dokuments als PHP-String zurück. Bei ungültigem BSON-Input wird eine MongoDB\Driver\Exception\UnexpectedValueException geworfen.

Beispiele

BSON-Dokument in Legacy Extended JSON umwandeln

<?php
// BSON aus einem PHP-Array erzeugen
$bson = MongoDB\BSON\fromPHP([
    'name'      => 'Alice',
    'age'       => 30,
    'createdAt' => new MongoDB\BSON\UTCDateTime(new DateTime('2024-01-15 12:00:00')),
]);

// BSON in Legacy Extended JSON umwandeln
$json = MongoDB\BSON\toJSON($bson);

echo $json . PHP_EOL;

{ "name" : "Alice", "age" : 30, "createdAt" : { "$date" : 1705320000000 } }

BSON-Daten debuggen und inspizieren

<?php
// Angenommen, $rawBson wird von einem Cursor oder einer Datei gelesen
$data = [
    '_id'    => new MongoDB\BSON\ObjectId(),
    'status' => 'active',
    'score'  => new MongoDB\BSON\Decimal128('99.5'),
];

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

// Zur Inspektion/Protokollierung als JSON ausgeben
error_log('Gespeichertes BSON: ' . MongoDB\BSON\toJSON($bson));

// Rückumwandlung in PHP-Objekt
$phpObject = MongoDB\BSON\toPHP($bson);
var_dump($phpObject->status);

string(6) "active"

// Wichtig · Fallstricke

Deprecation-Hinweis: MongoDB\BSON\toJSON() erzeugt das ältere Legacy Extended JSON-Format, das von MongoDB 4.x und früher verwendet wurde. Für neue Projekte empfiehlt MongoDB die Verwendung von Extended JSON v2, das durch MongoDB\BSON\Document::toCanonicalExtendedJSON() oder MongoDB\BSON\Document::toRelaxedExtendedJSON() bereitgestellt wird.

Der Eingabe-String muss ein vollständiges, gültiges BSON-Dokument sein. Ungültige oder abgeschnittene BSON-Daten führen zu einer MongoDB\Driver\Exception\UnexpectedValueException. Es empfiehlt sich daher, den Aufruf in einem try/catch-Block abzusichern, wenn die Datenherkunft nicht vollständig kontrolliert werden kann.

Beim direkten Einbetten des Rückgabewerts in HTML-Ausgaben sollte htmlspecialchars() verwendet werden, um XSS-Angriffe zu vermeiden, da der JSON-String Sonderzeichen enthalten kann.

Siehe auch

MongoDB\BSON\fromJSON MongoDB\BSON\fromPHP MongoDB\BSON\toPHP MongoDB\BSON\Document::toCanonicalExtendedJSON MongoDB\BSON\Document::toRelaxedExtendedJSON