date_timezone_set()

Einführung

date_timezone_set() ändert die Zeitzone eines vorhandenen DateTime-Objekts. Entscheidend dabei ist, dass der zugrunde liegende Zeitpunkt nicht geändert wird — nur die Wanduhranzeige dieses Zeitpunkts ändert sich. Derselbe Moment wird lediglich in einer anderen Zeitzone dargestellt, sodass die angezeigte Uhrzeit verschoben wird, während der absolute Punkt auf der Zeitachse identisch bleibt.

Das macht diese Funktion zum richtigen Werkzeug, wenn ein Datum/Uhrzeit in einer Zone vorliegt und in einer anderen angezeigt werden soll: etwa zum Umrechnen eines gespeicherten UTC-Zeitstempels in die Ortszeit eines Benutzers oder zum Vergleichen von Ereignissen aus verschiedenen Regionen.

date_timezone_set() ist der prozedurale Alias der Methode DateTime::setTimezone() — beide tun genau dasselbe.

Syntax

date_timezone_set(DateTime $object, DateTimeZone $timezone): DateTime|false

• $object — das DateTime-Objekt, dessen Zeitzone geändert werden soll.
• $timezone — ein DateTimeZone-Objekt mit der Zielzone (z. B. new DateTimeZone('Asia/Tokyo')).

Die Funktion verändert $object direkt und gibt bei Erfolg dieselbe Instanz zurück (praktisch für Verkettungen) oder false bei einem Fehler. Da das ursprüngliche Objekt geändert wird, gibt es keine separate „Kopie" — das Eingabeobjekt selbst wird verändert.

Grundlegendes Beispiel

2023-03-03 21:00:00

Das Objekt startet um 12:00 Uhr in London (Europe/London, also UTC+0 im März). Tokio liegt 9 Stunden voraus, daher wird derselbe Zeitpunkt als 21:00 Uhr angezeigt. Am eigentlichen Moment hat sich nichts geändert — nur die Zone, in der er dargestellt wird.

Der Zeitpunkt bleibt gleich — nur die Anzeige ändert sich

Das ist das Wichtigste, was man über date_timezone_set() verstehen muss. Vergleiche den Wert vor und nach der Konvertierung:

<?php
$date = new DateTime('2023-03-03 12:00:00', new DateTimeZone('Europe/London'));
echo $date->format('Y-m-d H:i:s P'), "\n";   // before

date_timezone_set($date, new DateTimeZone('Asia/Tokyo'));
echo $date->format('Y-m-d H:i:s P'), "\n";   // after

2023-03-03 12:00:00 +00:00
2023-03-03 21:00:00 +09:00

Die Wanduhrzeit und der UTC-Offset ändern sich beide, aber 12:00 +00:00 und 21:00 +09:00 sind derselbe Zeitpunkt. Wenn du nur den absoluten Zeitpunkt benötigst (z. B. einen UNIX-Zeitstempel), bleibt dieser unverändert.

Wenn du stattdessen die Wanduhrzeit ersetzen möchtest, ohne sie zu konvertieren, verwende diese Funktion nicht — setze die Uhrzeit direkt mit date_time_set().

Sommerzeit wird automatisch berücksichtigt

Da die Konvertierung über eine echte DateTimeZone erfolgt, werden die Sommerzeit-Regeln (DST) automatisch angewendet. New York ist im Winter UTC-5, im Sommer UTC-4, und date_timezone_set() wählt den korrekten Offset für das jeweilige Datum:

<?php
$utc = new DateTime('2023-06-21 12:00:00', new DateTimeZone('UTC'));
date_timezone_set($utc, new DateTimeZone('America/New_York'));
echo $utc->format('Y-m-d H:i:s');

2023-06-21 08:00:00

Im Juni gilt in New York Eastern Daylight Time (UTC-4), daher wird aus 12:00 UTC 08:00 Uhr. Führe denselben Code mit einem Januar-Datum aus, erhältst du 07:00 Uhr (UTC-5) — ohne jede Codeänderung. Deshalb solltest du immer IANA-Zonenkennungen wie America/New_York anstelle von festen Offsets wie -05:00 verwenden.

Prozeduraler vs. objektorientierter Stil

date_timezone_set($obj, $tz) und $obj->setTimezone($tz) sind austauschbar. Die Methodenform liest sich meist besser und lässt sich natürlich verketten:

<?php
$london = (new DateTime('2023-03-03 12:00:00', new DateTimeZone('Europe/London')))
    ->setTimezone(new DateTimeZone('Asia/Tokyo'));
echo $london->format('Y-m-d H:i:s');

2023-03-03 21:00:00

Häufige Anwendungsfälle

• Gespeicherte UTC-Zeiten in der Zeitzone des Benutzers anzeigen. Jeden Zeitstempel in UTC speichern und bei der Ausgabe mit date_timezone_set() in die bevorzugte Zeitzone des jeweiligen Benutzers umrechnen.
• Zeiten aus mehreren Regionen normalisieren, bevor sie verglichen oder sortiert werden.
• Regionale Berichte erstellen, die dasselbe Ereignis in mehreren Zeitzonen nebeneinander zeigen.

Worauf du achten solltest

• Die Funktion verändert das ursprüngliche Objekt. Wenn du den Ausgangswert behalten möchtest, klone ihn zuerst: $copy = clone $date; und konvertiere dann $copy.
• Sie parst oder setzt kein neues Datum — sie projiziert nur den vorhandenen Zeitpunkt neu. Verwende date_create(), um ein DateTime-Objekt zu erstellen, und date_time_set(), um die Uhrzeit zu überschreiben.
• Um die derzeit an ein Objekt gebundene Zeitzone auszulesen, verwende date_timezone_get().
• Verwechsle sie nicht mit date_default_timezone_set(), die die skriptweit gültige Standardzeitzone für alle Datums-/Uhrzeitfunktionen festlegt — eine völlig andere Aufgabe.

Diagramm

graph LR
A[DateTime Object] --> B((date_timezone_set))
C[Target DateTimeZone] --> B
B --> D[Same instant, new wall-clock display]

Übung