timezone_transitions_get()

PHP timezone_transitions_get(): Una visión general

La función timezone_transitions_get() devuelve la lista de transiciones de zona horaria para un objeto DateTimeZone dado — cada momento en que el offset UTC de esa zona cambió. Estas transiciones son principalmente cambios de horario de verano (adelantar/retrasar relojes), pero también incluyen cambios históricos en la hora estándar de una región.

La función es de estilo procedimental; el equivalente orientado a objetos es el método DateTimeZone::getTransitions(). Ambos se comportan de manera idéntica.

¿Cuándo la usarías? Casos típicos:

• Mostrar a los usuarios los momentos exactos en que el horario de verano comienza y termina en su región.
• Auditar o validar cómo el offset y la abreviatura de una zona han cambiado con el tiempo.
• Construir lógica de programación que deba omitir o ajustar una hora "faltante" o "repetida".

Sintaxis

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

Cada entrada devuelta describe un único instante — el momento en que una transición entra en vigor — no un rango. Para encontrar el período en que una regla está vigente, observe la diferencia entre el ts de una transición y el de la siguiente.

Parámetros

La función acepta un parámetro obligatorio y dos opcionales:

• $object (obligatorio): Un objeto DateTimeZone que identifica la zona a inspeccionar.
• $timestampBegin (opcional): Un timestamp Unix. Solo se devuelven las transiciones en ese momento o después. Si se omite, PHP comienza desde la transición más antigua conocida para la zona.
• $timestampEnd (opcional): Un timestamp Unix que marca el límite superior. Si se omite, se devuelven todas las transiciones hasta el futuro lejano.

La función procedimental devuelve false si los límites son inconsistentes (inicio posterior al fin). El método OO DateTimeZone::getTransitions() devuelve false en el mismo caso.

Valor de retorno

timezone_transitions_get() devuelve un array con un elemento de array asociativo por transición. Cada elemento tiene estas claves:

• ts: El timestamp Unix en que la transición entra en vigor.
• time: El mismo instante como una cadena ISO 8601 en UTC, p. ej. 2023-03-12T07:00:00+00:00. (Nota: es ISO 8601, no el formato Y-m-d H:i:s.)
• offset: El nuevo offset desde UTC, en segundos (por ejemplo -18000 para UTC−5).
• isdst: Un boolean — true si el horario de verano está en efecto desde esta transición en adelante.
• abbr: La abreviatura de zona horaria vigente después de la transición, como EST o EDT.

Ejemplos

Listado de cambios de horario de verano para un rango de fechas

Sin límites, la función devuelve cada transición desde que comenzó la zona — a menudo cientos de entradas históricas. En la práctica, casi siempre se pasa un timestamp de inicio y fin para reducir el resultado al período que interesa. El ejemplo a continuación lista las transiciones de Nueva York para 2023:

Ejemplo con $timestampBegin y $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;
}

Salida:

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

La primera fila es la transición "borde" sintetizada en $start, que indica el offset ya vigente en esa fecha. Las dos siguientes son los cambios reales: EDT comienza el 12 de marzo (los relojes saltan de las 2:00 a las 3:00 AM local) y EST regresa el 5 de noviembre.

Tenga en cuenta que time está en UTC. 2023-03-12T07:00:00+00:00 es 07:00 UTC, que son las 02:00 EST local — el instante en que los relojes se adelantan.

Equivalente orientado a objetos

El mismo resultado usando el método DateTimeZone directamente:

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

Funciones relacionadas

• date_default_timezone_set() — establece la zona horaria predeterminada para el script.
• timezone_offset_get() — obtiene el offset UTC de una zona en un momento dado.
• timezone_location_get() — obtiene la ubicación geográfica de una zona.
• Visión general de zonas horarias en PHP — cómo PHP modela las zonas horarias.

Conclusión

timezone_transitions_get() (y su equivalente OO DateTimeZone::getTransitions()) expone los instantes exactos en que cambia el offset UTC de una zona horaria — tanto cambios de horario de verano como cambios históricos de hora estándar. Cada entrada proporciona el timestamp (ts), una cadena UTC en ISO 8601 (time), el nuevo offset en segundos, un indicador de DST y la abreviatura vigente posteriormente.

Dos conclusiones prácticas: siempre pase $timestampBegin/$timestampEnd para evitar obtener la lista histórica completa, y recuerde que time y offset describen el momento después de cada transición, expresado en UTC.

Práctica