Signatur
Beschreibung
MongoDB\BSON\Binary kapselt rohe Binärdaten, die im BSON-Format gespeichert oder übertragen werden sollen. BSON unterstützt binäre Felder nativ; ohne diese Klasse müssten Binärdaten base64-kodiert als String gespeichert werden, was Platz verschwendet und Typ-Informationen verliert.
Jede Instanz trägt einen Subtyp (ein Byte), der die Art der Binärdaten klassifiziert. MongoDB kennt vordefinierte Subtypen wie Binary::TYPE_GENERIC (0x00), Binary::TYPE_UUID (0x04) oder Binary::TYPE_MD5 (0x05). Benutzerdefinierte Subtypen liegen im Bereich 0x80–0xFF.
Typische Einsatzgebiete sind das Speichern von Datei-Inhalten, kryptografischen Hashes, UUIDs oder beliebigen Byte-Folgen in MongoDB-Dokumenten. Bei UUID-Werten sollte stets Binary::TYPE_UUID verwendet werden, damit andere Treiber und Tools den Wert korrekt interpretieren können.
Die Klasse ist final und kann nicht erweitert werden. Instanzen sind unveränderlich; es gibt keine Setter-Methoden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $data Pflicht | string | Die rohen Binärdaten als PHP-String (Byte-String). Kann beliebige Bytes (inkl. Null-Bytes) enthalten. | |
| $type | int | 0 | Der BSON-Subtyp als Integer (0–255). Verwende die Klassen-Konstanten wie Binary::TYPE_GENERIC, Binary::TYPE_UUID usw. Standard ist Binary::TYPE_GENERIC (0x00). |
Rückgabewert
Beispiele
Binärdaten (Dateiinhalt) in MongoDB speichern
<?php
use MongoDB\BSON\Binary;
use MongoDB\Client;
$client = new Client('mongodb://localhost:27017');
$collection = $client->mydb->files;
$rawData = file_get_contents('/pfad/zur/datei.bin');
$binary = new Binary($rawData, Binary::TYPE_GENERIC);
$collection->insertOne([
'name' => 'datei.bin',
'content' => $binary,
'size' => strlen($rawData),
]);
echo 'Datei erfolgreich gespeichert.';
UUID als BSON-Binary speichern und auslesen
<?php
use MongoDB\BSON\Binary;
use MongoDB\Client;
$client = new Client('mongodb://localhost:27017');
$collection = $client->mydb->sessions;
// UUID v4 als rohe 16 Bytes erzeugen
$uuidHex = str_replace('-', '', '550e8400-e29b-41d4-a716-446655440000');
$uuidRaw = hex2bin($uuidHex);
$binary = new Binary($uuidRaw, Binary::TYPE_UUID);
$insertResult = $collection->insertOne(['session_id' => $binary]);
$id = $insertResult->getInsertedId();
// Wieder auslesen
$doc = $collection->findOne(['_id' => $id]);
/** @var Binary $sessionBin */
$sessionBin = $doc['session_id'];
echo 'Subtyp: ' . $sessionBin->getType() . PHP_EOL;
echo 'Hex-UUID: ' . bin2hex($sessionBin->getData()) . PHP_EOL;
Verfügbare Subtyp-Konstanten ausgeben
<?php
use MongoDB\BSON\Binary;
$konstanten = [
'TYPE_GENERIC' => Binary::TYPE_GENERIC,
'TYPE_FUNCTION' => Binary::TYPE_FUNCTION,
'TYPE_OLD_BINARY' => Binary::TYPE_OLD_BINARY,
'TYPE_OLD_UUID' => Binary::TYPE_OLD_UUID,
'TYPE_UUID' => Binary::TYPE_UUID,
'TYPE_MD5' => Binary::TYPE_MD5,
'TYPE_ENCRYPTED' => Binary::TYPE_ENCRYPTED,
'TYPE_COLUMN' => Binary::TYPE_COLUMN,
'TYPE_USER_DEFINED' => Binary::TYPE_USER_DEFINED,
];
foreach ($konstanten as $name => $wert) {
printf("Binary::%-24s = 0x%02X (%d)\n", $name, $wert, $wert);
}
// Wichtig · Fallstricke
Subtyp-Kompatibilität: Verwende für UUIDs stets Binary::TYPE_UUID (0x04) und niemals den veralteten TYPE_OLD_UUID (0x03), da Letzterer je nach Treiber die Byte-Reihenfolge unterschiedlich interpretiert und zu Interoperabilitätsproblemen führen kann.
Große Binärdaten: BSON-Dokumente sind auf 16 MB begrenzt. Für größere Binärdaten sollte GridFS (MongoDB\GridFS\Bucket) verwendet werden, das Dateien automatisch in Chunks aufteilt.
Benutzerdefinierte Subtypen: Werte im Bereich 0x80–0xFF sind für Anwendungen reserviert. Nutze Binary::TYPE_USER_DEFINED (0x80) als Ausgangspunkt und dokumentiere deine eigene Subtyp-Semantik, da MongoDB diese Bytes nicht interpretiert.
Serialisierung: Binary implementiert Serializable und JsonSerializable. Bei JSON-Serialisierung wird das Extended-JSON-Format ausgegeben ({"$binary": {"base64": "...", "subType": "00"}}), nicht der rohe Binärwert.