MongoDB\BSON\toPHP — Funktion · PHP-Referenz

Signatur

MongoDB\BSON\toPHP(string $bson, array $typeMap = []): object

Beschreibung

MongoDB\BSON\toPHP() wandelt einen rohen BSON-Byte-String zurück in eine PHP-Struktur. Die Funktion ist das Gegenstück zu MongoDB\BSON\fromPHP() und wird typischerweise genutzt, wenn BSON-Daten außerhalb des regulären Treiber-Workflows manuell verarbeitet werden müssen – z. B. beim Debuggen, beim Testen oder beim direkten Parsen gespeicherter Binärdaten.

Über den optionalen Parameter typeMap lässt sich steuern, in welche PHP-Klassen oder -Typen (array, object, stdClass oder eigene Klassen, die MongoDB\BSON\Unserializable implementieren) einzelne BSON-Strukturen deserialisiert werden. Die drei Schlüssel sind root (oberste Ebene), document (eingebettete Dokumente) und array (BSON-Arrays).

Wird keine typeMap übergeben, wird das Dokument als stdClass-Objekt zurückgegeben, wobei eingebettete Dokumente ebenfalls als stdClass deserialisiert werden. BSON-Arrays hingegen werden standardmäßig als PHP-Array dargestellt.

Die Funktion ist Teil des mongodb-PECL-Erweiterung (nicht des veralteten mongo-Treibers) und steht ab Treiber-Version 1.0.0 zur Verfügung.

Parameter

Name	Typ	Default	Beschreibung
$bson Pflicht	string		Ein gültiger BSON-kodierter Byte-String, wie er z. B. von `MongoDB\BSON\fromPHP()` erzeugt wird.
$typeMap	array	[]	Optionale Typ-Zuordnungstabelle. Erlaubte Schlüssel sind `root`, `document` und `array`. Erlaubte Werte sind `'array'`, `'object'` (Alias für `stdClass`), `'stdClass'` oder ein vollständig qualifizierter Klassenname einer Klasse, die `MongoDB\BSON\Unserializable` implementiert.

Rückgabewert

Typ

object

Beschreibung

Gibt ein PHP-object zurück (standardmäßig stdClass), das die deserialisierte BSON-Struktur repräsentiert. Über die typeMap kann auch eine eigene Klasse oder ein Array zurückgegeben werden.

Beispiele

Einfaches Roundtrip-Beispiel: fromPHP → toPHP

<?php
use MongoDB\BSON;

$data = ['name' => 'Alice', 'age' => 30, 'active' => true];

// Serialisieren
$bson = BSON\fromPHP($data);

// Deserialisieren
$result = BSON\toPHP($bson);

var_dump($result->name);   // string(5) "Alice"
var_dump($result->age);    // int(30)
var_dump($result->active); // bool(true)

string(5) "Alice" int(30) bool(true)

typeMap: Eingebettete Dokumente als eigene Klasse deserialisieren

<?php
use MongoDB\BSON;

class Address implements BSON\Unserializable
{
    public string $city = '';
    public string $country = '';

    public function bsonUnserialize(array $data): void
    {
        $this->city    = $data['city']    ?? '';
        $this->country = $data['country'] ?? '';
    }
}

$raw = BSON\fromPHP([
    'user'    => 'Bob',
    'address' => ['city' => 'Berlin', 'country' => 'DE'],
]);

$typeMap = [
    'root'     => 'stdClass',
    'document' => Address::class,
];

$result = BSON\toPHP($raw, $typeMap);

echo $result->user;            // Bob
echo $result->address->city;   // Berlin
echo $result->address->country; // DE

Bob Berlin DE

typeMap: Alles als verschachteltes PHP-Array

<?php
use MongoDB\BSON;

$bson = BSON\fromPHP(['foo' => ['bar' => 42]]);

$result = BSON\toPHP($bson, [
    'root'     => 'array',
    'document' => 'array',
]);

var_dump($result['foo']['bar']); // int(42)

int(42)

// Wichtig · Fallstricke

Achtung: Der übergebene $bson-String muss ein gültiges BSON-Dokument sein. Bei einem beschädigten oder ungültigen Byte-String wirft die Funktion eine MongoDB\Driver\Exception\UnexpectedValueException. Es empfiehlt sich daher, den Aufruf in einem try/catch-Block abzusichern.

Die typeMap-Schlüssel root und document beziehen sich auf BSON-Dokumente; der Schlüssel array bezieht sich auf BSON-Arrays (d. h. Dokumente mit fortlaufenden numerischen Schlüsseln). Werden eigene Klassen angegeben, müssen diese MongoDB\BSON\Unserializable implementieren, sonst wird eine Exception geworfen.

Ab PHP-Treiber-Version 1.16 ist diese Funktion als deprecated markiert und kann in zukünftigen Versionen entfernt werden. Stattdessen sollte die Methode MongoDB\BSON\Document::toPHP() verwendet werden.

Siehe auch

MongoDB\BSON\fromPHP MongoDB\BSON\Document::toPHP MongoDB\BSON\Unserializable MongoDB\BSON\toJSON MongoDB\BSON\fromJSON