MongoDB\BSON\UTCDateTimeInterface — Interface · PHP-Referenz

Signatur

interface UTCDateTimeInterface

Beschreibung

MongoDB\BSON\UTCDateTimeInterface definiert den Vertrag für Klassen, die einen BSON-Typ UTC datetime abbilden. MongoDB speichert Zeitstempel intern als 64-Bit-Integer (Millisekunden seit Unix-Epoche), und dieses Interface stellt sicher, dass Implementierungen sowohl den rohen Millisekunden-Wert als auch ein normiertes PHP-DateTime-Objekt liefern können.

Das Interface wird von der eingebauten Klasse MongoDB\BSON\UTCDateTime implementiert und ist nützlich, wenn eigene Wert-Objekte typsicher als BSON-Datumswerte behandelt werden sollen – etwa in benutzerdefinierten Typmappings über MongoDB\BSON\Persistable.

Durch den Einsatz des Interfaces im eigenen Code (z. B. als Typ-Hint in Methodensignaturen) bleibt der Code offen für alternative Implementierungen und testbar, ohne an die konkrete Klasse gebunden zu sein.

toDateTime(): Konvertiert den BSON-Zeitstempel in ein PHP-\DateTime-Objekt (UTC-Zeitzone).
__toString(): Gibt den Wert als String (Millisekunden seit Epoche) zurück.

Beispiele

Typ-Hint mit UTCDateTimeInterface in einer Datenschicht

<?php
use MongoDB\BSON\UTCDateTimeInterface;
use MongoDB\BSON\UTCDateTime;

function formatMongoDate(UTCDateTimeInterface $date): string {
    $dt = $date->toDateTime();
    return $dt->format('d.m.Y H:i:s') . ' UTC';
}

$bsonDate = new UTCDateTime(new \DateTime('2024-06-15 12:00:00'));
echo formatMongoDate($bsonDate);

15.06.2024 12:00:00 UTC

Benutzerdefiniertes Typmapping mit UTCDateTimeInterface

<?php
use MongoDB\BSON\UTCDateTimeInterface;
use MongoDB\BSON\UTCDateTime;

class Article implements MongoDB\BSON\Persistable {
    public string $title;
    public UTCDateTimeInterface $createdAt;

    public function __construct(string $title, UTCDateTimeInterface $createdAt) {
        $this->title     = $title;
        $this->createdAt = $createdAt;
    }

    public function bsonSerialize(): array {
        return [
            'title'     => $this->title,
            'createdAt' => $this->createdAt,
        ];
    }

    public function bsonUnserialize(array $data): void {
        $this->title     = $data['title'];
        $this->createdAt = $data['createdAt']; // UTCDateTime aus MongoDB
    }
}

$article = new Article('Hallo Welt', new UTCDateTime(new \DateTime('now')));
echo $article->title . ' – erstellt: ' . $article->createdAt->toDateTime()->format('Y-m-d');

Hallo Welt – erstellt: 2024-06-15

// Wichtig · Fallstricke

Zeitzone: toDateTime() gibt stets ein \DateTime-Objekt in der Zeitzone UTC zurück. Für die Anzeige in anderen Zeitzonen muss das Objekt anschließend konvertiert werden, z. B. mit $dt->setTimezone(new \DateTimeZone('Europe/Berlin')).

Millisekunden: BSON-Datumsangaben haben Millisekundengenauigkeit, PHP-\DateTime hat dagegen Mikrosekundengenauigkeit. Bei der Konvertierung können geringe Präzisionsverluste auftreten, wenn mit Mikrosekunden gearbeitet wird.

Das Interface gehört zur MongoDB PHP Library (PECL-Extension mongodb) und steht nicht in einer Standard-PHP-Installation zur Verfügung.

Siehe auch

MongoDB\BSON\UTCDateTime MongoDB\BSON\Persistable MongoDB\BSON\Serializable MongoDB\BSON\Unserializable