MongoDB\BSON\Decimal128 — Klasse · PHP-Referenz

Signatur

final class MongoDB\BSON\Decimal128 implements MongoDB\BSON\Decimal128Interface, MongoDB\BSON\Type, Serializable, JsonSerializable, Stringable

Beschreibung

MongoDB\BSON\Decimal128 kapselt den BSON-Datentyp Decimal128, der im IEEE-754-Standard für dezimale Gleitkommazahlen mit 128-Bit-Präzision definiert ist. Er bietet bis zu 34 signifikante Dezimalstellen und einen Exponenten im Bereich von −6143 bis +6144, was ihn besonders für finanzielle Berechnungen geeignet macht, bei denen binäre Gleitkommazahlen (wie float) unzureichende Präzision besitzen.

Im Gegensatz zum PHP-nativen float-Typ, der auf dem binären IEEE-754-Standard basiert und Rundungsfehler bei Dezimalzahlen wie 0.1 + 0.2 aufweist, speichert Decimal128 Zahlen exakt in Dezimaldarstellung. Das ist besonders wichtig beim Umgang mit Währungsbeträgen, Steuern oder anderen numerisch sensiblen Daten in MongoDB.

Die Klasse lässt sich nahtlos in die MongoDB-PHP-Bibliothek integrieren: BSON-Dokumente, die Decimal128-Felder enthalten, werden automatisch als Instanzen dieser Klasse deserialisiert, sofern kein abweichendes Typ-Mapping konfiguriert ist. Über __toString() lässt sich der Zahlenwert als String zurückgewinnen.

Für arithmetische Operationen direkt in PHP muss der Wert zunächst als String extrahiert und ggf. mit einer Bibliothek wie bcmath oder GMP weiterverarbeitet werden, da PHP keine native Decimal128-Arithmetik kennt.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	string		Die Dezimalzahl als Zeichenkette, z. B. `"9999.99"`, `"1.23456789012345678901234567890E+10"` oder `"NaN"`. Ungültige Werte lösen eine `MongoDB\Driver\Exception\InvalidArgumentException` aus.

Rückgabewert

Typ

Beispiele

Decimal128-Objekt erstellen und in MongoDB speichern

<?php
use MongoDB\BSON\Decimal128;
use MongoDB\Client;

$client = new Client('mongodb://localhost:27017');
$collection = $client->shop->products;

$preis = new Decimal128('19.99');

$collection->insertOne([
    'name'  => 'Schreibtischlampe',
    'preis' => $preis,
]);

echo "Gespeicherter Preis: " . $preis . PHP_EOL;
// Ausgabe: Gespeicherter Preis: 19.99

Gespeicherter Preis: 19.99

Decimal128-Wert aus MongoDB lesen und verarbeiten

<?php
use MongoDB\Client;

$client = new Client('mongodb://localhost:27017');
$collection = $client->shop->products;

$produkt = $collection->findOne(['name' => 'Schreibtischlampe']);

if ($produkt && isset($produkt['preis'])) {
    $decimal = $produkt['preis']; // Instanz von MongoDB\BSON\Decimal128
    $preisString = (string) $decimal;

    // Hochpräzise Berechnung mit bcmath
    $mwst      = '0.19';
    $bruttoStr = bcmul($preisString, bcadd('1', $mwst, 4), 4);
    $brutto    = new MongoDB\BSON\Decimal128($bruttoStr);

    echo "Netto:  " . $preisString . PHP_EOL;
    echo "Brutto: " . $brutto     . PHP_EOL;
}

Netto: 19.99 Brutto: 23.7881

JSON-Serialisierung eines Decimal128-Objekts

<?php
use MongoDB\BSON\Decimal128;

$wert = new Decimal128('123456789.123456789012345678');

// JsonSerializable-Implementierung
$json = json_encode(['betrag' => $wert]);
echo $json . PHP_EOL;
// Ausgabe: {"betrag":{"$numberDecimal":"123456789.123456789012345678"}}

{"betrag":{"$numberDecimal":"123456789.123456789012345678"}}

// Wichtig · Fallstricke

Präzision vs. Arithmetik: Decimal128 ist ein reiner Datencontainer – PHP bietet keine eingebaute Arithmetik für diesen Typ. Für Berechnungen empfiehlt sich die Extraktion per (string) $decimal und die Nutzung von bcmath- oder GMP-Funktionen.

Konstruktor-Validierung: Wird ein ungültiger String übergeben (z. B. "abc"), wirft der Konstruktor eine MongoDB\Driver\Exception\InvalidArgumentException. Sonderwerte wie "Infinity", "-Infinity" und "NaN" sind erlaubt.

Klasse ist final: Decimal128 kann nicht erweitert werden.

PHP-Extension: Diese Klasse ist Teil der PECL-Extension mongodb (nicht mongo) und steht ab Version 1.2.0 der Extension zur Verfügung.

Siehe auch

MongoDB\BSON\Decimal128Interface MongoDB\BSON\Int64 MongoDB\BSON\Type bcmul bcadd