MongoDB\BSON\Timestamp — Klasse · PHP-Referenz

Signatur

final class MongoDB\BSON\Timestamp implements MongoDB\BSON\TimestampInterface, MongoDB\BSON\Type, Serializable, JsonSerializable, Stringable

Beschreibung

Der BSON-Typ Timestamp ist ein spezieller 64-Bit-Wert, der aus zwei vorzeichenlosen 32-Bit-Integern besteht: einem Unix-Epochen-Zeitstempel (Sekunden) und einem aufsteigenden Ordinalwert (Inkrement). Er wird intern von MongoDB für Replikations- und Sharding-Mechanismen verwendet, insbesondere im Oplog.

Wichtig: Dieser Typ ist nicht für allgemeine Datums- oder Uhrzeitangaben in Anwendungsdaten gedacht. Für Datum/Uhrzeit in eigenen Dokumenten sollte stattdessen MongoDB\BSON\UTCDateTime verwendet werden. Timestamp ist ausschließlich für interne MongoDB-Zwecke vorgesehen.

Die Klasse ist final und kann nicht erweitert werden. Sie implementiert TimestampInterface, sodass sie per Interface-Type-Hint typsicher verwendet werden kann. Über getTimestamp() und getIncrement() lassen sich die beiden Komponenten auslesen.

Beim Serialisieren wird der Wert in das MongoDB Extended JSON-Format überführt, was die Interoperabilität mit anderen Systemen erleichtert. Beim Einfügen eines Dokuments mit einem leeren Timestamp (beide Felder 0) füllt MongoDB das Feld serverseitig automatisch aus.

Parameter

Name	Typ	Default	Beschreibung
$increment Pflicht	int		Vorzeichenloser 32-Bit-Ordinalwert (Inkrement), der innerhalb einer Sekunde aufsteigende Reihenfolge sicherstellt. Muss im Bereich `0` bis `4294967295` liegen.
$timestamp Pflicht	int		Vorzeichenloser 32-Bit-Unix-Epochen-Zeitstempel in Sekunden. Muss im Bereich `0` bis `4294967295` liegen.

Beispiele

Timestamp erstellen und Komponenten auslesen

<?php
require_once 'vendor/autoload.php';

// Aktuellen Unix-Zeitstempel und ein Inkrement verwenden
$increment = 1;
$timestamp = time(); // z. B. 1700000000

$bsonTimestamp = new MongoDB\BSON\Timestamp($increment, $timestamp);

echo 'Timestamp:  ' . $bsonTimestamp->getTimestamp() . PHP_EOL;
echo 'Inkrement:  ' . $bsonTimestamp->getIncrement() . PHP_EOL;
echo 'Als String: ' . (string) $bsonTimestamp . PHP_EOL;

Timestamp: 1700000000 Inkrement: 1 Als String: 1700000000:1

Oplog-Eintrag eines MongoDB-Dokuments lesen

<?php
require_once 'vendor/autoload.php';

$client = new MongoDB\Client('mongodb://localhost:27017');

// Oplog des Replikationssets abfragen
$oplog = $client->local->selectCollection('oplog.rs');

$entry = $oplog->findOne([], ['sort' => ['$natural' => -1]]);

if ($entry && $entry['ts'] instanceof MongoDB\BSON\TimestampInterface) {
    $ts = $entry['ts'];
    echo 'Letzter Oplog-Eintrag:' . PHP_EOL;
    echo '  Zeitstempel: ' . $ts->getTimestamp() . PHP_EOL;
    echo '  Inkrement:   ' . $ts->getIncrement() . PHP_EOL;
    echo '  Operation:   ' . $entry['op'] . PHP_EOL;
}

Letzter Oplog-Eintrag: Zeitstempel: 1700000042 Inkrement: 3 Operation: i

JSON-Serialisierung eines Timestamps

<?php
require_once 'vendor/autoload.php';

$ts = new MongoDB\BSON\Timestamp(5, 1700000000);

// JsonSerializable-Implementierung
$json = json_encode($ts);
echo $json . PHP_EOL;

// BSON-Roundtrip
$bson = MongoDB\BSON\fromPHP(['ts' => $ts]);
$doc  = MongoDB\BSON\toPHP($bson);
echo 'Roundtrip-Timestamp: ' . $doc->ts->getTimestamp() . PHP_EOL;

{"$timestamp":{"t":1700000000,"i":5}} Roundtrip-Timestamp: 1700000000

// Wichtig · Fallstricke

Nicht für Anwendungsdaten verwenden: MongoDB\BSON\Timestamp ist ein interner MongoDB-Typ. Für eigene Datum/Uhrzeit-Felder in Dokumenten ist MongoDB\BSON\UTCDateTime die richtige Wahl.

Plattformabhängigkeit bei int: Auf 32-Bit-Systemen kann PHP keine vorzeichenlosen 32-Bit-Integer nativ darstellen. Werte über 2147483647 sollten daher mit Vorsicht behandelt werden, da es zu Vorzeichenproblemen kommen kann.

Automatisches Ausfüllen: Wird ein Dokument mit new Timestamp(0, 0) in ein Replikationsset eingefügt, befüllt MongoDB den Wert serverseitig automatisch mit dem aktuellen Oplog-Zeitstempel. Dieses Verhalten gilt ausschließlich für das oberste Feld eines Dokuments.

Die Klasse ist als final deklariert und kann nicht abgeleitet werden. Typprüfungen sollten gegen das Interface MongoDB\BSON\TimestampInterface erfolgen, um Zukunftssicherheit zu gewährleisten.

Siehe auch

MongoDB\BSON\UTCDateTime MongoDB\BSON\TimestampInterface MongoDB\BSON\ObjectId MongoDB\BSON\Type