MongoDB\BSON\Symbol — Klasse · PHP-Referenz

Signatur

final class MongoDB\BSON\Symbol implements MongoDB\BSON\Type, Serializable, JsonSerializable, Stringable

Beschreibung

MongoDB\BSON\Symbol ist eine finale PHP-Klasse, die den veralteten BSON-Datentyp Symbol abbildet. Dieser Typ war ursprünglich für Bezeichner aus Programmiersprachen mit Konzept für Symbole (z. B. JavaScript-Symbole) vorgesehen und wurde in frühen MongoDB-Versionen verwendet. Er ist funktional nahezu identisch mit einem String, wird jedoch als eigener BSON-Typ kodiert.

In der Praxis wird Symbol heutzutage kaum noch erzeugt. Er kann jedoch auftreten, wenn ältere MongoDB-Daten gelesen werden, die diesen Typ noch enthalten. Die Klasse ermöglicht es, solche Dokumente korrekt zu deserialisieren und den ursprünglichen Symbolwert als PHP-String über __toString() oder getValue() abzurufen.

Wichtig: Da der BSON-Typ Symbol als deprecated gilt, sollte er in neuen Anwendungen nicht mehr aktiv genutzt werden. Stattdessen sollte der reguläre BSON-String-Typ verwendet werden. Die Klasse ist als final deklariert und kann daher nicht erweitert werden.

Objekte dieser Klasse werden beim Lesen älterer BSON-Dokumente automatisch vom MongoDB-Treiber erzeugt. Ein manuelles Anlegen ist zwar möglich, jedoch nur für Legacy-Zwecke sinnvoll.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	string		Der Symbolwert als PHP-String, der intern als BSON-Symbol gespeichert wird.

Rückgabewert

Typ

Beispiele

Symbol-Objekt erzeugen und Wert auslesen

<?php
use MongoDB\BSON\Symbol;

// Manuelles Erstellen eines Symbol-Objekts (nur für Legacy-Zwecke)
$symbol = new Symbol('meinSymbol');

// Wert als String abrufen
echo $symbol->getValue(); // meinSymbol
echo (string) $symbol;    // meinSymbol
?>

meinSymbol meinSymbol

Deserialisierung eines BSON-Dokuments mit Symbol-Typ

<?php
use MongoDB\BSON\Symbol;
use MongoDB\Driver\Manager;
use MongoDB\Driver\Query;

// Verbindung zu MongoDB herstellen
$manager = new Manager('mongodb://localhost:27017');

// Dokumente abfragen, die möglicherweise veraltete Symbol-Felder enthalten
$query = new Query([]);
$cursor = $manager->executeQuery('meineDb.alteKollection', $query);

foreach ($cursor as $dokument) {
    // Symbol-Felder erkennen und verarbeiten
    if (isset($dokument->legacyFeld) && $dokument->legacyFeld instanceof Symbol) {
        echo 'Symbol-Wert: ' . $dokument->legacyFeld->getValue() . PHP_EOL;
    }
}
?>

JSON-Serialisierung eines Symbol-Objekts

<?php
use MongoDB\BSON\Symbol;

$symbol = new Symbol('beispielSymbol');

// JSON-Repräsentation ausgeben
$json = json_encode($symbol);
echo $json;
?>

{"$symbol":"beispielSymbol"}

// Wichtig · Fallstricke

Deprecation: Der BSON-Typ Symbol ist veraltet und sollte in neuen Projekten nicht mehr verwendet werden. MongoDB empfiehlt stattdessen den Einsatz regulärer BSON-Strings. Bestehende Daten mit Symbol-Typ sollten bei Gelegenheit auf den String-Typ migriert werden.

Da die Klasse final ist, kann sie nicht durch Vererbung erweitert werden. Die Serialisierungsunterstützung über Serializable und JsonSerializable ermöglicht eine korrekte Einbindung in PHP-Serialisierungsmechanismen.

Siehe auch

MongoDB\BSON\Type MongoDB\BSON\Binary MongoDB\BSON\Javascript MongoDB\BSON\toPHP