timezone_transitions_get()

PHP timezone_transitions_get() : Aperçu

La fonction timezone_transitions_get() retourne la liste des transitions de fuseau horaire pour un objet DateTimeZone donné — chaque instant auquel le décalage UTC de cette zone a changé. Ces transitions correspondent principalement aux basculements heure d'été/heure d'hiver (passage à l'heure d'été / retour à l'heure d'hiver), mais elles incluent également les changements historiques d'heure standard d'une région.

La fonction est procédurale ; l'équivalent orienté objet est la méthode DateTimeZone::getTransitions(). Les deux se comportent de manière identique.

Dans quels cas l'utiliser ? Cas d'usage typiques :

• Afficher aux utilisateurs les moments exacts où l'heure d'été commence et se termine dans leur région.
• Auditer ou valider comment le décalage et l'abréviation d'une zone ont évolué au fil du temps.
• Construire une logique de planification qui doit ignorer ou ajuster une heure « manquante » ou « répétée ».

Syntaxe

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

Chaque entrée retournée décrit un instant unique — le moment où une transition prend effet — et non une plage. Pour trouver la période durant laquelle une règle est en vigueur, examinez l'écart entre le ts d'une transition et celui de la suivante.

Paramètres

La fonction accepte un paramètre obligatoire et deux paramètres optionnels :

• $object (obligatoire) : Un objet DateTimeZone identifiant la zone à inspecter.
• $timestampBegin (optionnel) : Un horodatage Unix. Seules les transitions à partir de cet instant sont retournées. S'il est omis, PHP commence depuis la transition la plus ancienne connue pour la zone.
• $timestampEnd (optionnel) : Un horodatage Unix définissant la borne supérieure. S'il est omis, toutes les transitions jusqu'au futur lointain sont retournées.

La fonction procédurale retourne false si les bornes sont incohérentes (début après la fin). La méthode OO DateTimeZone::getTransitions() retourne false dans le même cas.

Valeur de retour

timezone_transitions_get() retourne un tableau contenant un élément de tableau associatif par transition. Chaque élément possède les clés suivantes :

• ts : L'horodatage Unix auquel la transition prend effet.
• time : Le même instant sous forme de chaîne ISO 8601 en UTC, par ex. 2023-03-12T07:00:00+00:00. (Remarque : il s'agit du format ISO 8601, et non du format Y-m-d H:i:s.)
• offset : Le nouveau décalage par rapport à UTC, en secondes (par exemple -18000 pour UTC−5).
• isdst : Un boolean — true si l'heure d'été est en vigueur à partir de cette transition.
• abbr : L'abréviation du fuseau horaire en vigueur après la transition, comme EST ou EDT.

Exemples

Lister les changements d'heure d'été pour une plage de dates

Sans bornes, la fonction retourne toutes les transitions depuis le début de la zone — souvent des centaines d'entrées historiques. En pratique, vous passerez presque toujours un horodatage de début et de fin pour restreindre le résultat à la période qui vous intéresse. L'exemple ci-dessous liste les transitions de New York pour 2023 :

Exemple avec $timestampBegin et $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;
}

Résultat :

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 première ligne est la transition « de bord » synthétisée à $start, indiquant le décalage déjà en vigueur à cette date. Les deux suivantes sont les vrais basculements : l'EDT commence le 12 mars (les horloges passent de 2h00 à 3h00 localement) et l'EST reprend le 5 novembre.

Notez que time est en UTC. 2023-03-12T07:00:00+00:00 correspond à 07h00 UTC, soit 02h00 heure locale EST — l'instant où les horloges avancent.

Équivalent orienté objet

Le même résultat en utilisant directement la méthode DateTimeZone :

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

Fonctions associées

• date_default_timezone_set() — définir le fuseau horaire par défaut du script.
• timezone_offset_get() — obtenir le décalage UTC d'une zone à un instant donné.
• timezone_location_get() — obtenir la localisation géographique d'une zone.
• Aperçu des fuseaux horaires PHP — comment PHP modélise les fuseaux horaires.

Conclusion

timezone_transitions_get() (et son équivalent OO DateTimeZone::getTransitions()) expose les instants exacts auxquels le décalage UTC d'un fuseau horaire change — basculements heure d'été et changements d'heure standard historiques compris. Chaque entrée fournit l'horodatage (ts), une chaîne UTC ISO 8601 (time), le nouveau décalage en secondes, un indicateur d'heure d'été et l'abréviation en vigueur ensuite.

Deux points pratiques à retenir : passez toujours $timestampBegin/$timestampEnd pour éviter d'obtenir la liste historique complète, et souvenez-vous que time et offset décrivent le moment après chaque transition, exprimé en UTC.

Pratique