timezone_transitions_get()

PHP timezone_transitions_get(): Eine Übersicht

Die Funktion timezone_transitions_get() gibt die Liste der Zeitzonen-Übergänge für ein gegebenes DateTimeZone-Objekt zurück – jeden Zeitpunkt, an dem sich der UTC-Offset dieser Zone geändert hat. Diese Übergänge sind meistens Sommerzeit-Umstellungen (Vor- und Zurückstellen der Uhr), umfassen aber auch historische Änderungen an der Standardzeit einer Region.

Die Funktion ist prozedural; das objektorientierte Äquivalent ist die Methode DateTimeZone::getTransitions(). Beide verhalten sich identisch.

Wann würde man sie verwenden? Typische Anwendungsfälle:

• Benutzern die genauen Zeitpunkte anzeigen, an denen die Sommerzeit in ihrer Region beginnt und endet.
• Prüfen oder validieren, wie sich Offset und Abkürzung einer Zone im Laufe der Zeit geändert haben.
• Aufbau von Planungslogik, die eine „fehlende" oder „doppelte" Stunde überspringen oder anpassen muss.

Syntax

timezone_transitions_get(
    DateTimeZone $object,
    int $timestampBegin = PHP_INT_MIN,
    int $timestampEnd = PHP_INT_MAX
): array|false

Jeder zurückgegebene Eintrag beschreibt einen einzelnen Moment – den Zeitpunkt, an dem ein Übergang wirksam wird – keinen Zeitraum. Um den Zeitraum zu ermitteln, in dem eine Regel gilt, betrachtet man die Lücke zwischen dem ts-Wert eines Übergangs und dem nächsten.

Parameter

Die Funktion nimmt einen erforderlichen Parameter und zwei optionale Parameter:

• $object (erforderlich): Ein DateTimeZone-Objekt, das die zu untersuchende Zone angibt.
• $timestampBegin (optional): Ein Unix-Timestamp. Nur Übergänge ab diesem Zeitpunkt werden zurückgegeben. Wird er weggelassen, beginnt PHP beim frühestmöglichen bekannten Übergang für die Zone.
• $timestampEnd (optional): Ein Unix-Timestamp als obere Grenze. Wird er weggelassen, werden alle Übergänge bis in die ferne Zukunft zurückgegeben.

Die prozedurale Funktion gibt false zurück, wenn die Grenzen inkonsistent sind (Beginn nach Ende). Die OO-Methode DateTimeZone::getTransitions() gibt im selben Fall false zurück.

Rückgabewert

timezone_transitions_get() gibt ein Array mit einem assoziativen Array-Element pro Übergang zurück. Jedes Element hat folgende Schlüssel:

• ts: Der Unix-Timestamp, ab dem der Übergang wirksam wird.
• time: Derselbe Zeitpunkt als ISO 8601-String in UTC, z. B. 2023-03-12T07:00:00+00:00. (Hinweis: Dies ist ISO 8601, nicht das Format Y-m-d H:i:s.)
• offset: Der neue Offset gegenüber UTC in Sekunden (z. B. -18000 für UTC−5).
• isdst: Ein boolean — true, wenn die Sommerzeit ab diesem Übergang gilt.
• abbr: Die nach dem Übergang geltende Zeitzonenabkürzung, z. B. EST oder EDT.

Beispiele

Sommerzeit-Änderungen für einen Datumsbereich auflisten

Ohne Grenzen gibt die Funktion alle Übergänge seit Beginn der Zone zurück – oft Hunderte historischer Einträge. In der Praxis übergibt man fast immer einen Start- und End-Timestamp, um das Ergebnis auf den gewünschten Zeitraum einzugrenzen. Das folgende Beispiel listet die Übergänge für New York im Jahr 2023 auf:

Beispiel mit $timestampBegin und $timestampEnd

<?php

$timezone = new DateTimeZone('America/New_York');
$start = strtotime('2023-01-01');
$end   = strtotime('2023-12-31');

$transitions = timezone_transitions_get($timezone, $start, $end);

foreach ($transitions as $transition) {
    echo $transition['time']
        . '  offset=' . $transition['offset']
        . '  ' . $transition['abbr']
        . ($transition['isdst'] ? ' (DST)' : '')
        . PHP_EOL;
}

Ausgabe:

2023-01-01T00:00:00+00:00  offset=-18000  EST
2023-03-12T07:00:00+00:00  offset=-14400  EDT (DST)
2023-11-05T06:00:00+00:00  offset=-18000  EST

Die erste Zeile ist der bei $start synthetisierte „Rand"-Übergang, der den bereits an diesem Datum geltenden Offset anzeigt. Die nächsten beiden sind die echten Umstellungen: EDT beginnt am 12. März (die Uhr springt von 2:00 auf 3:00 Uhr Ortszeit) und EST kehrt am 5. November zurück.

Beachte, dass time in UTC angegeben ist. 2023-03-12T07:00:00+00:00 ist 07:00 UTC, was 02:00 Uhr Ortszeit (EST) entspricht – der Moment, in dem die Uhren vorgestellt werden.

Objektorientiertes Äquivalent

Das gleiche Ergebnis mithilfe der DateTimeZone-Methode direkt:

Verwendung von DateTimeZone::getTransitions()

<?php

$timezone = new DateTimeZone('America/New_York');
$start = strtotime('2023-01-01');
$end   = strtotime('2023-12-31');

foreach ($timezone->getTransitions($start, $end) as $transition) {
    echo $transition['time'] . '  ' . $transition['abbr'] . PHP_EOL;
}

Verwandte Funktionen

• date_default_timezone_set() — setzt die skriptweit gültige Standardzeitzone.
• timezone_offset_get() — gibt den UTC-Offset einer Zone zu einem bestimmten Zeitpunkt zurück.
• timezone_location_get() — gibt den geografischen Standort einer Zone zurück.
• PHP-Zeitzonen-Übersicht — wie PHP Zeitzonen modelliert.

Fazit

timezone_transitions_get() (und sein OO-Pendant DateTimeZone::getTransitions()) gibt die genauen Zeitpunkte zurück, an denen sich der UTC-Offset einer Zeitzone ändert – sowohl Sommerzeit-Umstellungen als auch historische Änderungen der Standardzeit. Jeder Eintrag liefert den Timestamp (ts), einen ISO 8601 UTC-String (time), den neuen Offset in Sekunden, ein Sommerzeit-Flag und die danach gültige Abkürzung.

Zwei praktische Hinweise: Übergib immer $timestampBegin/$timestampEnd, um die vollständige historische Liste zu vermeiden, und bedenke, dass time und offset den Moment nach jedem Übergang beschreiben, ausgedrückt in UTC.

Übungen