MongoDB\BSON\TimestampInterface — Interface · PHP-Referenz

Signatur

interface TimestampInterface

Beschreibung

MongoDB\BSON\TimestampInterface definiert den Vertrag für Klassen, die den BSON-Datentyp Timestamp abbilden. Ein BSON-Timestamp besteht aus zwei vorzeichenlosen 32-Bit-Ganzzahlen: dem Zeitwert (Unix-Sekunden) und dem Inkrement, das bei mehreren Operationen innerhalb derselben Sekunde eine eindeutige Reihenfolge sicherstellt.

Der BSON-Timestamp-Typ ist ein internes MongoDB-Format, das primär im Replikationslog (Oplog) und bei Sharding-Mechanismen verwendet wird. Für allgemeine Datums- und Zeitangaben in Anwendungsdaten sollte stattdessen der BSON-Typ UTCDateTime (MongoDB\BSON\UTCDateTimeInterface) genutzt werden.

Durch die Implementierung dieses Interfaces kann eine eigene Klasse als BSON-Timestamp-Typ behandelt werden — etwa für Type-Maps beim Deserialisieren von MongoDB-Dokumenten. Das Interface stellt sicher, dass Inkrement und Zeitwert über standardisierte Methoden abrufbar sind.

Die konkrete Referenzimplementierung ist MongoDB\BSON\Timestamp. Klassen, die TimestampInterface implementieren, müssen außerdem __toString() bereitstellen.

Beispiele

Eigene Klasse, die TimestampInterface implementiert

<?php
use MongoDB\BSON\TimestampInterface;

class MyTimestamp implements TimestampInterface
{
    private int $increment;
    private int $timestamp;

    public function __construct(int $increment, int $timestamp)
    {
        $this->increment = $increment;
        $this->timestamp = $timestamp;
    }

    public function getIncrement(): int
    {
        return $this->increment;
    }

    public function getTimestamp(): int
    {
        return $this->timestamp;
    }

    public function __toString(): string
    {
        return sprintf('[%d:%d]', $this->timestamp, $this->increment);
    }
}

$ts = new MyTimestamp(1, 1700000000);
echo 'Zeitwert: ' . $ts->getTimestamp() . PHP_EOL;
echo 'Inkrement: ' . $ts->getIncrement() . PHP_EOL;
echo 'Als String: ' . $ts . PHP_EOL;

Zeitwert: 1700000000 Inkrement: 1 Als String: [1700000000:1]

BSON-Timestamp aus MongoDB lesen und TimestampInterface-Methoden nutzen

<?php
use MongoDB\BSON\Timestamp;
use MongoDB\BSON\TimestampInterface;

// Konkreter BSON-Timestamp (Referenzimplementierung)
$bsonTs = new Timestamp(42, 1700000000);

// Funktion, die gegen das Interface typisiert ist
function printTimestamp(TimestampInterface $ts): void
{
    echo sprintf(
        'Unix-Zeit: %d, Inkrement: %d, String: %s' . PHP_EOL,
        $ts->getTimestamp(),
        $ts->getIncrement(),
        (string) $ts
    );
}

printTimestamp($bsonTs);

Unix-Zeit: 1700000000, Inkrement: 42, String: 1700000000:42

// Wichtig · Fallstricke

Achtung: Der BSON-Typ Timestamp ist nicht für die Speicherung von Anwendungsdaten gedacht. MongoDB verwendet ihn intern für die Replikation (Oplog). Für Zeitstempel in eigenen Dokumenten sollte MongoDB\BSON\UTCDateTime verwendet werden.

Die Methoden getIncrement() und getTimestamp() sowie __toString() sind verpflichtend zu implementieren. Das genaue Format des String-Outputs ist nicht durch das Interface vorgeschrieben, die Referenzimplementierung gibt "<timestamp>:<increment>" aus.

Dieses Interface ist seit Version 1.3.0 des MongoDB PHP-Treibers (mongodb-Extension) verfügbar.

Siehe auch

MongoDB\BSON\Timestamp MongoDB\BSON\UTCDateTimeInterface MongoDB\BSON\UTCDateTime MongoDB\BSON\Serializable MongoDB\BSON\Unserializable