MongoDB\BSON\UTCDateTime — Klasse · PHP-Referenz

Signatur

class MongoDB\BSON\UTCDateTime implements MongoDB\BSON\UTCDateTimeInterface, MongoDB\BSON\Type, JsonSerializable, Serializable

Beschreibung

MongoDB\BSON\UTCDateTime ist die PHP-Repräsentation des BSON-Typs UTC datetime, der Datum und Uhrzeit als vorzeichenbehaftete 64-Bit-Integer in Millisekunden seit der Unix-Epoche speichert. Damit können Zeitwerte weit vor 1970 und weit nach 2038 dargestellt werden – ein wesentlicher Vorteil gegenüber dem klassischen Unix-Timestamp.

Die Klasse wird überall dort eingesetzt, wo Zeitstempel in MongoDB-Dokumenten gespeichert oder ausgelesen werden. Beim Schreiben erzeugt man eine Instanz aus einem \DateTime-Objekt, einem Integer (Millisekunden) oder einem numerischen String. Beim Lesen liefert der MongoDB-Treiber automatisch UTCDateTime-Objekte für BSON-Datumsfelder zurück.

Mit der Methode toDateTime() lässt sich eine UTCDateTime-Instanz jederzeit in ein natives PHP-\DateTime-Objekt (mit UTC-Zeitzone) umwandeln, was die weitere Verarbeitung mit Standard-PHP-Funktionen ermöglicht.

Unterstützt Zeitwerte über den Jahr-2038-Bug hinaus.
Zeitzone ist immer UTC – Konvertierungen in lokale Zeitzonen müssen manuell erfolgen.
Kann mit null aufgerufen werden, um den aktuellen Zeitpunkt zu erfassen.

Parameter

Name	Typ	Default	Beschreibung
$milliseconds	int\|string\|\DateTime\|null	null	Der Zeitwert als Millisekunden seit der Unix-Epoche (Integer oder numerischer String), als `\DateTime`-Objekt oder `null` für den aktuellen Zeitpunkt. Bei `\DateTime`-Objekten wird der Wert automatisch in Millisekunden umgerechnet.

Rückgabewert

Typ

Beispiele

Aktuellen Zeitstempel in MongoDB speichern

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

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

// Aktuellen Zeitpunkt als BSON-Datum speichern
$result = $collection->insertOne([
    'event'      => 'Benutzer-Login',
    'created_at' => new UTCDateTime(), // null = jetzt
]);

echo 'Dokument eingefügt mit ID: ' . $result->getInsertedId() . PHP_EOL;

Dokument eingefügt mit ID: 6642f1a3e4b0c1d2e3f4a5b6

DateTime-Objekt in UTCDateTime konvertieren und zurücklesen

<?php
use MongoDB\BSON\UTCDateTime;

// PHP-DateTime in UTCDateTime umwandeln
$phpDate = new \DateTime('2024-06-15 12:30:00', new \DateTimeZone('Europe/Berlin'));
$bsonDate = new UTCDateTime($phpDate);

echo 'BSON-Millisekunden: ' . $bsonDate . PHP_EOL;

// Zurück zu PHP-DateTime konvertieren (immer UTC)
$utcDate = $bsonDate->toDateTime();
echo 'UTC-Datum: ' . $utcDate->format('Y-m-d H:i:s T') . PHP_EOL;

// In Berliner Ortszeit umrechnen
$utcDate->setTimezone(new \DateTimeZone('Europe/Berlin'));
echo 'Berliner Zeit: ' . $utcDate->format('Y-m-d H:i:s T') . PHP_EOL;

BSON-Millisekunden: 1718447400000 UTC-Datum: 2024-06-15 10:30:00 UTC Berliner Zeit: 2024-06-15 12:30:00 CEST

Datenbankabfrage mit Zeitbereich (Range-Query)

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

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

$start = new UTCDateTime(new \DateTime('2024-01-01 00:00:00', new \DateTimeZone('UTC')));
$end   = new UTCDateTime(new \DateTime('2024-12-31 23:59:59', new \DateTimeZone('UTC')));

$cursor = $collection->find([
    'created_at' => [
        '$gte' => $start,
        '$lte' => $end,
    ],
]);

foreach ($cursor as $document) {
    $date = $document['created_at']->toDateTime();
    echo $document['event'] . ' am ' . $date->format('d.m.Y H:i') . ' UTC' . PHP_EOL;
}

// Wichtig · Fallstricke

Zeitzone immer UTC: toDateTime() gibt immer ein \DateTime-Objekt mit der Zeitzone UTC zurück. Lokale Zeitzonenkonvertierungen müssen über setTimezone() explizit erfolgen – anderenfalls können Anzeigefehler entstehen.

Millisekunden, nicht Sekunden: Ein häufiger Fehler ist die Übergabe eines Unix-Timestamps in Sekunden statt Millisekunden. Für Sekunden-Timestamps muss mit 1000 multipliziert werden: new UTCDateTime(time() * 1000). Die Übergabe eines \DateTime-Objekts ist daher der sicherere und lesbarere Weg.

Serialisierung: Die Klasse implementiert JsonSerializable und gibt beim JSON-Encoding ein Objekt der Form {"$date":{"$numberLong":"..."}} (Extended JSON) zurück, was beim Austausch mit anderen Systemen zu beachten ist.

Siehe auch

MongoDB\BSON\UTCDateTimeInterface MongoDB\BSON\Type DateTime MongoDB\BSON\ObjectId MongoDB\BSON\Timestamp