Signatur
Beschreibung
MongoDB\BSON\Undefined bildet den veralteten BSON-Typ Undefined ab, der ursprünglich aus JavaScript stammt und dort dem undefined-Wert entspricht. Dieser Typ wurde in der BSON-Spezifikation als deprecated markiert und sollte in neuen Anwendungen nicht mehr eingesetzt werden. Stattdessen ist null (BSON-Typ 0x0A) die empfohlene Alternative.
Die Klasse existiert ausschließlich zur Rückwärtskompatibilität, damit ältere Dokumente, die noch den Undefined-Typ enthalten, korrekt deserialisiert und im PHP-Code repräsentiert werden können. Sie können Instanzen dieser Klasse nicht manuell erzeugen, da der Konstruktor keine öffentliche API bietet.
Beim Serialisieren nach JSON gibt jsonSerialize() einen leeren Wert zurück, da der BSON-Typ keinerlei Datenwert trägt. Für die PHP-Serialisierung implementiert die Klasse das Serializable-Interface, sodass Objekte dieses Typs korrekt eingefroren und wiederhergestellt werden können.
In der Praxis begegnet man Objekten dieser Klasse, wenn man MongoDB-Datenbanken liest, die von sehr alten Versionen (vor MongoDB 2.x) befüllt wurden. Beim Schreiben neuer Dokumente sollte stets null statt Undefined verwendet werden.
Beispiele
Undefined-Wert aus einem alten Dokument erkennen und behandeln
<?php
// Verbindung zur MongoDB-Datenbank herstellen
$client = new MongoDB\Client('mongodb://localhost:27017');
$collection = $client->testdb->legacyCollection;
// Ein Dokument abrufen, das möglicherweise einen Undefined-Wert enthält
$document = $collection->findOne(['_id' => new MongoDB\BSON\ObjectId('507f1f77bcf86cd799439011')]);
if ($document !== null) {
foreach ($document as $key => $value) {
if ($value instanceof MongoDB\BSON\Undefined) {
// Veralteten Undefined-Typ durch null ersetzen
echo "Feld '{$key}' enthält einen veralteten Undefined-Wert. Wird durch null ersetzt.\n";
$collection->updateOne(
['_id' => $document['_id']],
['$unset' => [$key => '']]
);
}
}
}Typprüfung auf Undefined beim Deserialisieren von BSON
<?php
use MongoDB\BSON\Undefined;
// Simuliertes BSON-Dokument dekodieren (enthält Undefined-Typ 0x06)
$bsonData = "\x12\x00\x00\x00\x06field\x00\x00"; // Vereinfachtes Beispiel
$document = MongoDB\BSON\toPHP($bsonData);
foreach ((array)$document as $field => $value) {
if ($value instanceof Undefined) {
echo "Warnung: Feld '{$field}' ist vom veralteten BSON-Typ Undefined.\n";
echo "JSON-Repräsentation: " . json_encode($value->jsonSerialize()) . "\n";
}
}// Wichtig · Fallstricke
Deprecated: Der BSON-Typ Undefined (0x06) ist in der aktuellen BSON-Spezifikation als veraltet markiert. Neue Dokumente sollten niemals Werte dieses Typs enthalten. Verwenden Sie stattdessen null oder lassen Sie das Feld gänzlich weg ($unset).
Da die Klasse als final deklariert ist, kann sie nicht erweitert werden. Es ist außerdem nicht möglich, Instanzen manuell über new Undefined() zu erzeugen – Objekte entstehen ausschließlich beim Deserialisieren von BSON-Daten, die diesen Typ enthalten.
Beim Migrieren alter Datenbanken empfiehlt es sich, alle Felder mit Undefined-Werten systematisch zu bereinigen, um spätere Kompatibilitätsprobleme zu vermeiden.