timezone_transitions_get()

PHP timezone_transitions_get(): Visão Geral

A função timezone_transitions_get() retorna a lista de transições de fuso horário para um determinado DateTimeZone — cada ponto no tempo em que o deslocamento UTC daquela zona foi alterado. Essas transições são, em sua maioria, mudanças de horário de verão (avançar/recuar o relógio), mas também incluem alterações históricas no horário padrão de uma região.

A função é procedural; o equivalente orientado a objetos é o método DateTimeZone::getTransitions(). Ambos se comportam de forma idêntica.

Quando você usaria isso? Casos típicos:

• Mostrar aos usuários os momentos exatos em que o horário de verão começa e termina em sua região.
• Auditar ou validar como o deslocamento e a abreviação de uma zona mudaram ao longo do tempo.
• Criar lógica de agendamento que deve pular ou ajustar em torno de uma hora "inexistente" ou "repetida".

Sintaxe

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

Cada entrada retornada descreve um único instante — o momento em que uma transição entra em vigor — não um intervalo. Para encontrar o período em que uma regra está em vigência, observe a diferença entre o ts de uma transição e o da próxima.

Parâmetros

A função recebe um parâmetro obrigatório e dois opcionais:

• $object (obrigatório): Um objeto DateTimeZone que identifica a zona a ser inspecionada.
• $timestampBegin (opcional): Um timestamp Unix. Somente as transições a partir desse momento são retornadas. Quando omitido, o PHP começa a partir da transição mais antiga conhecida para a zona.
• $timestampEnd (opcional): Um timestamp Unix que marca o limite superior. Quando omitido, todas as transições até o futuro distante são retornadas.

A função procedural retorna false se os limites forem inconsistentes (início após o fim). O método OO DateTimeZone::getTransitions() retorna false no mesmo caso.

Valor de Retorno

timezone_transitions_get() retorna um array com um elemento de array associativo por transição. Cada elemento possui as seguintes chaves:

• ts: O timestamp Unix no qual a transição entra em vigor.
• time: O mesmo instante como uma string ISO 8601 em UTC, por exemplo 2023-03-12T07:00:00+00:00. (Nota: este é o formato ISO 8601, não o formato Y-m-d H:i:s.)
• offset: O novo deslocamento em relação ao UTC, em segundos (por exemplo, -18000 para UTC−5).
• isdst: Um boolean — true se o horário de verão estiver em vigor a partir dessa transição em diante.
• abbr: A abreviação do fuso horário em vigor após a transição, como EST ou EDT.

Exemplos

Listando mudanças de horário de verão para um intervalo de datas

Sem limites, a função retorna todas as transições desde o início da zona — frequentemente centenas de entradas históricas. Na prática, você quase sempre passa um timestamp de início e fim para restringir o resultado ao período desejado. O exemplo abaixo lista as transições de Nova Iorque para 2023:

Exemplo com $timestampBegin e $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;
}

Saída:

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

A primeira linha é a transição "de borda" sintetizada em $start, indicando o deslocamento já em vigor naquela data. As duas seguintes são as mudanças reais: o EDT começa em 12 de março (os relógios avançam de 2h para 3h no horário local) e o EST retorna em 5 de novembro.

Observe que time está em UTC. 2023-03-12T07:00:00+00:00 é 07:00 UTC, que corresponde a 02:00 EST local — o instante em que os relógios avançam.

Equivalente orientado a objetos

O mesmo resultado usando o método DateTimeZone diretamente:

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

Funções Relacionadas

• date_default_timezone_set() — define o fuso horário padrão para o script.
• timezone_offset_get() — obtém o deslocamento UTC de uma zona em um determinado momento.
• timezone_location_get() — obtém a localização geográfica de uma zona.
• Visão geral de fusos horários PHP — como o PHP modela os fusos horários.

Conclusão

timezone_transitions_get() (e seu equivalente OO DateTimeZone::getTransitions()) expõe os instantes exatos em que o deslocamento UTC de um fuso horário muda — tanto as mudanças de horário de verão quanto as alterações históricas no horário padrão. Cada entrada fornece o timestamp (ts), uma string UTC no formato ISO 8601 (time), o novo deslocamento em segundos, um sinalizador de horário de verão e a abreviação em vigor após a transição.

Dois pontos práticos importantes: sempre passe $timestampBegin/$timestampEnd para evitar obter a lista histórica completa, e lembre-se de que time e offset descrevem o momento após cada transição, expresso em UTC.

Prática