date_timestamp_set()

Die PHP-Funktion date_timestamp_set()

date_timestamp_set() setzt Datum und Uhrzeit eines DateTime-Objekts anhand eines Unix-Timestamps — der Anzahl der Sekunden seit dem 1. Januar 1970, 00:00:00 UTC (der „Unix-Epoche"). Sie überschreibt das zuvor im Objekt gespeicherte Datum und fixiert es auf den genauen Zeitpunkt, den der Timestamp beschreibt.

Diese Seite behandelt die Syntax der Funktion, ein praktisches Beispiel, das Zusammenspiel mit Zeitzonen (der Teil, den die meisten falsch verstehen), das objektorientierte Äquivalent DateTime::setTimestamp(), häufige Anwendungsfälle und die Beziehung zu anderen PHP-Datumsfunktionen.

Syntax

date_timestamp_set(DateTime $object, int $timestamp): DateTime

• $object — eine DateTime-Instanz, die geändert werden soll.
• $timestamp — ein Unix-Timestamp (Sekunden seit der Epoche). Für Datumsangaben vor 1970 wird eine negative Zahl übergeben.
• Rückgabewert — dasselbe DateTime-Objekt (damit Aufrufe verkettet werden können), nun aktualisiert.

Da die Funktion das übergebene Objekt verändert und zurückgibt, ist date_timestamp_set() das prozedurale Gegenstück zur Methode DateTime::setTimestamp() — beide bewirken dasselbe.

Ein einfaches Beispiel

Dieses Beispiel setzt ein DateTime-Objekt auf den 1. Januar 2022, 00:00:00 UTC, dessen Unix-Timestamp 1640995200 ist:

Wir erstellen ein DateTime-Objekt, übergeben es zusammen mit dem Timestamp an date_timestamp_set() und formatieren das Ergebnis. Das ursprüngliche Datum, das der Konstruktor erzeugt hat (der aktuelle Zeitpunkt), wird verworfen.

Ein Unix-Timestamp zeigt immer auf einen Moment in UTC — er enthält keine eigene Zeitzone. Wenn Sie den Timestamp für ein bestimmtes Kalenderdatum benötigen, verwenden Sie mktime(), strtotime() oder (new DateTime('2022-01-01'))->getTimestamp().

Timestamps sind absolut — die Zeitzone beeinflusst nur die Anzeige

Ein weit verbreitetes Missverständnis ist, dass date_timestamp_set() ein Datum zwischen Zeitzonen „konvertiert". Das ist nicht der Fall: Die Funktion ändert nicht, auf welchen Zeitpunkt das Objekt zeigt, sondern setzt diesen Zeitpunkt nur. Was sich zwischen Zeitzonen unterscheidet, ist die Art und Weise, wie format() ihn darstellt.

Derselbe Timestamp in zwei verschiedenen Zeitzonen angezeigt:

<?php
$timestamp = 1640995200; // 2022-01-01 00:00:00 UTC

$nyc = new DateTime('now', new DateTimeZone('America/New_York'));
date_timestamp_set($nyc, $timestamp);

echo $nyc->format('Y-m-d H:i:s P'); // 2021-12-31 19:00:00 -05:00

Der Zeitpunkt ist identisch, aber New York liegt im Januar fünf Stunden hinter UTC, sodass die Uhrzeitanzeige dem Abend des 31. Dezember entspricht. Ein Aufruf von $nyc->getTimestamp() gibt nach wie vor 1640995200 zurück. Um die angezeigte Zeitzone tatsächlich zu ändern, setzen Sie diese explizit mit date_timezone_set().

Objektorientiertes Äquivalent

Wer Method Chaining bevorzugt, kann DateTime::setTimestamp() verwenden, das dieselbe Wirkung hat:

<?php
date_default_timezone_set('UTC');

$date = (new DateTime())->setTimestamp(1640995200);

echo $date->format('Y-m-d H:i:s'); // 2022-01-01 00:00:00

Beide Varianten verändern das Objekt direkt und geben es zurück — wählen Sie also diejenige, die in Ihrem Code besser lesbar ist.

Häufige Anwendungsfälle

• Gespeicherte Zeit wiederherstellen. Datenbanken und APIs speichern Zeiten häufig als Integer-Unix-Timestamps. Mit date_timestamp_set() lässt sich aus diesem Integer ein DateTime-Objekt rekonstruieren, das anschließend formatiert oder per date_add() und date_diff() arithmetisch verarbeitet werden kann.
• Benutzereingaben normalisieren. Konvertieren Sie vom Benutzer eingegebene Datumsangaben mit strtotime() in einen Timestamp und initialisieren Sie damit ein DateTime-Objekt mit einem einzigen kanonischen Wert.
• Vorhandenes Objekt zurücksetzen. Wenn Sie bereits ein konfiguriertes DateTime-Objekt (mit gewählter Zeitzone oder Formatierungslogik) haben und es einfach auf einen neuen Zeitpunkt setzen möchten, ohne es neu zu erstellen.

Verwandte Funktionen

• date_timestamp_get() — das Gegenstück: liest den Unix-Timestamp eines DateTime-Objekts aus.
• date_date_set() und date_time_set() — setzen Datum oder Uhrzeit anhand einzelner Komponenten statt eines Timestamps.
• date_default_timezone_set() — steuert die verwendete Zeitzone, wenn keine DateTimeZone angegeben wird.

Fazit

date_timestamp_set() setzt ein DateTime-Objekt auf den genauen Zeitpunkt, der durch einen Unix-Timestamp beschrieben wird, überschreibt den vorherigen Wert und gibt dasselbe Objekt zurück. Denken Sie daran, dass der Timestamp immer UTC-basiert ist und die Zeitzone nur die Darstellung des Ergebnisses beeinflusst — nicht den zugrunde liegenden Zeitpunkt. Für die umgekehrte Operation verwenden Sie date_timestamp_get().

Übungen