timezone_transitions_get()

PHP timezone_transitions_get(): An Overview

The timezone_transitions_get() function returns the list of timezone transitions for a given DateTimeZone — every point in time at which that zone's UTC offset changed. These transitions are mostly daylight-saving-time switches (spring-forward / fall-back), but they also include historical changes to a region's standard time.

The function is procedural; the object-oriented equivalent is the DateTimeZone::getTransitions() method. Both behave identically.

When would you use it? Typical cases:

• Showing users the exact moments DST starts and ends in their region.
• Auditing or validating how a zone's offset and abbreviation have changed over time.
• Building scheduling logic that must skip or adjust around a "missing" or "repeated" hour.

Syntax

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

Each returned entry describes a single instant — the moment a transition takes effect — not a range. To find the period a rule is in force, look at the gap between one transition's ts and the next.

Parameters

The function takes one required parameter and two optional parameters:

• $object (required): A DateTimeZone object identifying the zone to inspect.
• $timestampBegin (optional): A Unix timestamp. Only transitions at or after this moment are returned. When omitted, PHP starts from the earliest known transition for the zone.
• $timestampEnd (optional): A Unix timestamp marking the upper bound. When omitted, all transitions through the far future are returned.

The procedural function returns false if the bounds are inconsistent (begin after end). The OO method DateTimeZone::getTransitions() returns false in the same case.

Return Value

timezone_transitions_get() returns an array with one associative-array element per transition. Each element has these keys:

• ts: The Unix timestamp at which the transition takes effect.
• time: The same instant as an ISO 8601 string in UTC, e.g. 2023-03-12T07:00:00+00:00. (Note: this is ISO 8601, not the Y-m-d H:i:s format.)
• offset: The new offset from UTC, in seconds (for example -18000 for UTC−5).
• isdst: A boolean — true if daylight saving time is in effect from this transition onward.
• abbr: The timezone abbreviation in effect after the transition, such as EST or EDT.

Examples

Listing DST changes for a date range

Without bounds, the function returns every transition since the zone began — often hundreds of historical entries. In practice you almost always pass a start and end timestamp to narrow the result to the period you care about. The example below lists New York's transitions for 2023:

Example with $timestampBegin and $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;
}

Output:

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

The first row is the "edge" transition synthesised at $start, telling you the offset already in effect on that date. The next two are the real switches: EDT begins on March 12 (clocks jump from 2:00 to 3:00 AM local) and EST returns on November 5.

Note that time is in UTC. 2023-03-12T07:00:00+00:00 is 07:00 UTC, which is 02:00 local EST — the instant the clocks spring forward.

Object-oriented equivalent

The same result using the DateTimeZone method directly:

Using 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;
}

Related functions

• date_default_timezone_set() — set the script-wide default timezone.
• timezone_offset_get() — get a zone's UTC offset at one moment.
• timezone_location_get() — get a zone's geographic location.
• PHP Timezones overview — how PHP models timezones.

Conclusion

timezone_transitions_get() (and its OO twin DateTimeZone::getTransitions()) exposes the exact instants a timezone's UTC offset changes — DST switches and historical standard-time changes alike. Each entry gives you the timestamp (ts), an ISO 8601 UTC string (time), the new offset in seconds, a DST flag, and the abbreviation in effect afterward.

Two practical takeaways: always pass $timestampBegin/$timestampEnd to avoid getting the full historical list, and remember that time and offset describe the moment after each transition, expressed in UTC.

Practice