MongoDB\BSON\Int64 — Klasse · PHP-Referenz

Signatur

final class MongoDB\BSON\Int64 implements MongoDB\BSON\Type, JsonSerializable, Stringable

Beschreibung

MongoDB\BSON\Int64 kapselt einen 64-Bit-Ganzzahlwert, der explizit als BSON-Typ int64 gespeichert und übertragen werden soll. Auf 32-Bit-PHP-Plattformen, auf denen native PHP-Integer nur 32 Bit breit sind, ist diese Klasse unverzichtbar, um große Ganzzahlen korrekt nach MongoDB zu schreiben und zu lesen, ohne Präzisionsverlust.

In PHP 8.x auf 64-Bit-Plattformen werden PHP-Integer automatisch als BSON int32 oder int64 serialisiert, je nach Größe des Werts. Mit Int64 kann man jedoch explizit erzwingen, dass ein Wert immer als int64 gespeichert wird – unabhängig von seiner tatsächlichen Größe. Das ist besonders bei Schema-Konsistenz wichtig, wenn MongoDB-Felder stets denselben BSON-Typ aufweisen sollen.

Beim Lesen von MongoDB-Dokumenten liefert der Treiber Felder, die als BSON int64 gespeichert sind, auf 32-Bit-PHP-Systemen als MongoDB\BSON\Int64-Objekt zurück, da der native PHP-Integer-Typ nicht ausreicht. Auf 64-Bit-Systemen werden solche Felder direkt als PHP-Integer deserialisiert.

Die Klasse implementiert Stringable, sodass eine Instanz per String-Casting in ihre Ganzzahl-Repräsentation umgewandelt werden kann, und JsonSerializable, um in JSON-Kontexten korrekt serialisiert zu werden.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	int\|string		Der Ganzzahlwert, der als BSON `int64` repräsentiert werden soll. Auf 32-Bit-Systemen sollte ein `string` übergeben werden, um Präzisionsverluste zu vermeiden.

Rückgabewert

Typ

Beispiele

Explizites Speichern eines int64-Werts in MongoDB

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

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

// Explizit als BSON int64 speichern – auch wenn der Wert in int32 passen würde
$collection->insertOne([
    'name'  => 'page_views',
    'count' => new Int64(9876543210),
]);

echo 'Dokument gespeichert mit BSON int64.' . PHP_EOL;

Dokument gespeichert mit BSON int64.

Großen Wert als String übergeben (32-Bit-Sicherheit)

<?php
use MongoDB\BSON\Int64;

// Auf 32-Bit-PHP als String übergeben, um Präzisionsverlust zu vermeiden
$bigValue = new Int64('9223372036854775807'); // PHP_INT_MAX auf 64-Bit

echo $bigValue . PHP_EOL;          // Stringable-Interface
echo get_class($bigValue) . PHP_EOL;

$json = json_encode(['value' => $bigValue]);
echo $json . PHP_EOL;              // JsonSerializable

9223372036854775807 MongoDB\BSON\Int64 {"value":9223372036854775807}

Lesen und Vergleichen eines int64-Felds aus MongoDB

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

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

$doc = $collection->findOne(['name' => 'page_views']);

if ($doc !== null) {
    $count = $doc['count'];
    // Auf 32-Bit-PHP ist $count eine Int64-Instanz
    if ($count instanceof Int64) {
        echo 'Int64-Wert: ' . $count . PHP_EOL;
    } else {
        // Auf 64-Bit-PHP direkt als nativer Integer
        echo 'Integer-Wert: ' . $count . PHP_EOL;
    }
}

Int64-Wert: 9876543210

// Wichtig · Fallstricke

32-Bit-Plattformen: Auf 32-Bit-PHP-Systemen können Ganzzahlen größer als 2.147.483.647 nicht als nativer PHP-Integer dargestellt werden. Um Präzisionsverluste beim Erstellen einer Int64-Instanz zu vermeiden, sollte der Wert stets als string übergeben werden.

Deserialisierung: Auf 64-Bit-PHP-Systemen werden BSON-int64-Felder vom Treiber als native PHP-Integer deserialisiert, nicht als Int64-Objekte. Portabler Code sollte dies mit instanceof prüfen.

Vergleiche: Da es sich um ein Objekt handelt, sind direkte numerische Vergleiche mit == oder === nicht sinnvoll. Zum Vergleich sollte der Wert via (string)-Cast oder einer geeigneten Bibliothek wie brick/math verglichen werden.

Siehe auch

MongoDB\BSON\Int32 MongoDB\BSON\Type MongoDB\BSON\Document MongoDB\BSON\Decimal128