timezone_transitions_get()

PHP timezone_transitions_get(): обзор

Функция timezone_transitions_get() возвращает список переходов часового пояса для заданного объекта DateTimeZone — каждый момент времени, в который смещение этого пояса относительно UTC менялось. Большинство переходов связаны с переходом на летнее/зимнее время, но сюда также входят исторические изменения стандартного времени региона.

Функция является процедурной; объектно-ориентированный эквивалент — метод DateTimeZone::getTransitions(). Оба ведут себя одинаково.

Когда это может пригодиться? Типичные сценарии использования:

• Показ пользователям точных моментов начала и окончания летнего времени в их регионе.
• Аудит или проверка того, как менялись смещение и аббревиатура пояса со временем.
• Построение логики планирования, которая должна учитывать «пропущенный» или «повторяющийся» час.

Синтаксис

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

Каждый возвращаемый элемент описывает один момент — когда переход вступает в силу, — а не диапазон. Чтобы определить период действия правила, смотрите на разницу между значением ts одного перехода и следующего.

Параметры

Функция принимает один обязательный параметр и два необязательных:

• $object (обязательный): объект DateTimeZone, идентифицирующий исследуемый пояс.
• $timestampBegin (необязательный): Unix-временная метка. Возвращаются только переходы, произошедшие в этот момент или после него. Если не указан, PHP начинает с самого раннего известного перехода для данного пояса.
• $timestampEnd (необязательный): Unix-временная метка, задающая верхнюю границу. Если не указан, возвращаются все переходы вплоть до отдалённого будущего.

Процедурная функция возвращает false, если границы указаны некорректно (начало после конца). Метод DateTimeZone::getTransitions() возвращает false в том же случае.

Возвращаемое значение

timezone_transitions_get() возвращает массив, в котором каждый элемент является ассоциативным массивом, описывающим один переход. Каждый элемент содержит следующие ключи:

• ts: Unix-временная метка момента, когда переход вступает в силу.
• time: тот же момент в виде строки ISO 8601 в UTC, например 2023-03-12T07:00:00+00:00. (Обратите внимание: это формат ISO 8601, а не Y-m-d H:i:s.)
• offset: новое смещение от UTC в секундах (например, -18000 для UTC−5).
• isdst: boolean-значение — true, если после этого перехода действует летнее время.
• abbr: аббревиатура часового пояса, действующая после перехода, например EST или EDT.

Примеры

Список изменений летнего времени для диапазона дат

Без указания границ функция возвращает все переходы с момента создания пояса — нередко сотни исторических записей. На практике почти всегда передаются начальная и конечная временные метки для сужения результата до нужного периода. Пример ниже выводит переходы Нью-Йорка за 2023 год:

Пример с $timestampBegin и $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;
}

Вывод:

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

Первая строка — «граничный» переход, синтезированный на основе $start, который указывает смещение, уже действовавшее на эту дату. Следующие две — реальные переключения: EDT начинается 12 марта (часы переводятся с 2:00 на 3:00 по местному времени), а EST возвращается 5 ноября.

Обратите внимание, что time указывается в UTC. 2023-03-12T07:00:00+00:00 — это 07:00 UTC, что соответствует 02:00 по местному времени EST — моменту, когда часы переводятся вперёд.

Объектно-ориентированный эквивалент

Тот же результат с использованием метода DateTimeZone напрямую:

Использование 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;
}

Связанные функции

• date_default_timezone_set() — устанавливает часовой пояс по умолчанию для скрипта.
• timezone_offset_get() — возвращает смещение UTC для пояса в конкретный момент.
• timezone_location_get() — возвращает географическое местоположение пояса.
• Обзор часовых поясов PHP — как PHP моделирует часовые пояса.

Заключение

timezone_transitions_get() (и её объектно-ориентированный аналог DateTimeZone::getTransitions()) предоставляет точные моменты изменения смещения UTC часового пояса — как переходы на летнее время, так и исторические изменения стандартного времени. Каждая запись содержит временную метку (ts), строку UTC в формате ISO 8601 (time), новое смещение в секундах, флаг летнего времени и аббревиатуру, действующую после перехода.

Два практических вывода: всегда передавайте $timestampBegin/$timestampEnd, чтобы не получать полный исторический список, и помните, что time и offset описывают момент после каждого перехода, выраженный в UTC.

Практика