MongoDB\BSON\BinaryInterface — Interface · PHP-Referenz

Signatur

interface BinaryInterface

Beschreibung

MongoDB\BSON\BinaryInterface definiert das Vertragsinterface für Klassen, die einen BSON-Binary-Wert kapseln. BSON Binary ist ein spezieller Datentyp in MongoDB, der beliebige Binärdaten zusammen mit einem Subtyp-Byte speichert – beispielsweise für UUIDs, verschlüsselte Felder oder rohe Byte-Sequenzen.

Alle konformen Implementierungen müssen die Methoden getData() und getType() bereitstellen. getData() liefert die rohen Binärdaten als PHP-String, getType() den numerischen Subtyp (0–255) als Integer. Der Subtyp gibt an, wie die Binärdaten zu interpretieren sind (z. B. 0 = generisch, 3/4 = UUID, 5 = MD5).

Das Interface wird primär im Zusammenspiel mit dem offiziellen MongoDB PHP-Treiber (mongodb/mongodb) genutzt. Die Standardimplementierung ist MongoDB\BSON\Binary. Durch das Interface lassen sich eigene Klassen schreiben, die nahtlos in die BSON-Serialisierung eingebunden werden, ohne direkt von Binary abhängen zu müssen.

Typischerweise trifft man dieses Interface beim Lesen von Dokumenten aus MongoDB an, wenn Felder als BinaryInterface-Instanzen deserialisiert werden, oder beim Schreiben, wenn man UUID-Felder oder verschlüsselte Werte typsicher übergeben möchte.

Beispiele

Subtyp und Daten eines Binary-Feldes auslesen

<?php
use MongoDB\BSON\Binary;
use MongoDB\BSON\BinaryInterface;

// Beispielwert: UUID (Subtyp 4)
$binary = new Binary(\hex2bin('550e8400e29b41d4a716446655440000'), Binary::TYPE_UUID);

function describeBinary(BinaryInterface $bin): void {
    $subtype = $bin->getType();
    $data    = $bin->getData();

    echo sprintf(
        "Subtyp: %d, Länge: %d Bytes, Hex: %s\n",
        $subtype,
        strlen($data),
        bin2hex($data)
    );
}

describeBinary($binary);

Subtyp: 4, Länge: 16 Bytes, Hex: 550e8400e29b41d4a716446655440000

Eigene Implementierung von BinaryInterface

<?php
use MongoDB\BSON\BinaryInterface;

class EncryptedField implements BinaryInterface
{
    private string $ciphertext;
    private int    $subtype;

    public function __construct(string $ciphertext, int $subtype = 0)
    {
        $this->ciphertext = $ciphertext;
        $this->subtype    = $subtype;
    }

    public function getData(): string
    {
        return $this->ciphertext;
    }

    public function getType(): int
    {
        return $this->subtype;
    }

    public function serialize(): string
    {
        return base64_encode($this->ciphertext);
    }

    public function unserialize(string $data): void
    {
        $this->ciphertext = base64_decode($data);
    }
}

$field = new EncryptedField('geheimeBytes', 128);
echo 'Subtyp: ' . $field->getType() . PHP_EOL;
echo 'Daten:  ' . $field->getData() . PHP_EOL;

Subtyp: 128 Daten: geheimeBytes

// Wichtig · Fallstricke

Subtypen: MongoDB reserviert Subtypwerte 0–127 für eigene Zwecke. Eigene Anwendungssubtypes sollten im Bereich 128–255 liegen, um Konflikte zu vermeiden.

UUID-Kompatibilität: Die Subtypes 3 (Legacy UUID) und 4 (UUID gemäß RFC 4122) haben unterschiedliche Byte-Reihenfolgen je nach Treiber. Beim Lesen von UUIDs sollte man sich auf den Subtyp 4 beschränken und ältere Subtypes explizit konvertieren.

Sicherheit: getData() liefert rohe Bytes zurück – bei der Ausgabe im Browser oder in Logs sollte bin2hex() oder base64_encode() verwendet werden, um unerwartetes Verhalten oder Datenlecks zu vermeiden.

Siehe auch

MongoDB\BSON\Binary MongoDB\BSON\Type MongoDB\BSON\Serializable MongoDB\BSON\Unserializable