timezone_transitions_get()

PHP timezone_transitions_get(): Panoramica

La funzione timezone_transitions_get() restituisce l'elenco delle transizioni di fuso orario per un dato DateTimeZone — ogni momento in cui l'offset UTC di quella zona è cambiato. Queste transizioni sono per lo più cambi dell'ora legale (avanzamento primaverile / arretramento autunnale), ma includono anche modifiche storiche all'ora standard di una regione.

La funzione è procedurale; l'equivalente orientato agli oggetti è il metodo DateTimeZone::getTransitions(). Entrambi si comportano in modo identico.

Quando utilizzarla? Casi tipici:

• Mostrare agli utenti i momenti esatti in cui l'ora legale inizia e finisce nella loro regione.
• Verificare o convalidare come l'offset e l'abbreviazione di una zona sono cambiati nel tempo.
• Costruire logica di schedulazione che deve saltare o adattarsi attorno a un'ora "mancante" o "ripetuta".

Sintassi

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

Ogni voce restituita descrive un singolo istante — il momento in cui una transizione entra in vigore — non un intervallo. Per trovare il periodo in cui una regola è in vigore, osserva il divario tra il valore ts di una transizione e quello della successiva.

Parametri

La funzione accetta un parametro obbligatorio e due parametri opzionali:

• $object (obbligatorio): Un oggetto DateTimeZone che identifica la zona da esaminare.
• $timestampBegin (opzionale): Un timestamp Unix. Vengono restituite solo le transizioni a partire da questo momento. Se omesso, PHP parte dalla transizione più antica conosciuta per la zona.
• $timestampEnd (opzionale): Un timestamp Unix che segna il limite superiore. Se omesso, vengono restituite tutte le transizioni fino al futuro remoto.

La funzione procedurale restituisce false se i limiti sono incoerenti (inizio dopo la fine). Il metodo OO DateTimeZone::getTransitions() restituisce false nello stesso caso.

Valore di ritorno

timezone_transitions_get() restituisce un array con un elemento array associativo per ogni transizione. Ogni elemento ha le seguenti chiavi:

• ts: Il timestamp Unix in cui la transizione entra in vigore.
• time: Lo stesso istante come stringa ISO 8601 in UTC, ad es. 2023-03-12T07:00:00+00:00. (Nota: questo è ISO 8601, non il formato Y-m-d H:i:s.)
• offset: Il nuovo offset dall'UTC, in secondi (ad esempio -18000 per UTC−5).
• isdst: Un boolean — true se l'ora legale è in vigore da questa transizione in poi.
• abbr: L'abbreviazione del fuso orario in vigore dopo la transizione, come EST o EDT.

Esempi

Elenco dei cambi dell'ora legale per un intervallo di date

Senza limiti, la funzione restituisce ogni transizione dall'inizio della zona — spesso centinaia di voci storiche. In pratica si passano quasi sempre un timestamp di inizio e di fine per limitare il risultato al periodo di interesse. L'esempio seguente elenca le transizioni di New York per il 2023:

Esempio con $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;
}

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

La prima riga è la transizione "di bordo" sintetizzata a $start, che indica l'offset già in vigore in quella data. Le successive due sono i veri cambi: EDT inizia il 12 marzo (gli orologi passano dalle 2:00 alle 3:00 AM locali) e EST ritorna il 5 novembre.

Si noti che time è in UTC. 2023-03-12T07:00:00+00:00 corrisponde alle 07:00 UTC, ovvero alle 02:00 locali EST — il momento in cui gli orologi avanzano.

Equivalente orientato agli oggetti

Lo stesso risultato usando direttamente il metodo DateTimeZone:

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

Funzioni correlate

• date_default_timezone_set() — imposta il fuso orario predefinito per lo script.
• timezone_offset_get() — ottiene l'offset UTC di una zona in un dato momento.
• timezone_location_get() — ottiene la posizione geografica di una zona.
• Panoramica sui fusi orari PHP — come PHP gestisce i fusi orari.

Conclusione

timezone_transitions_get() (e il suo equivalente OO DateTimeZone::getTransitions()) espone gli istanti esatti in cui l'offset UTC di un fuso orario cambia — sia i cambi dell'ora legale sia le modifiche storiche dell'ora standard. Ogni voce fornisce il timestamp (ts), una stringa UTC ISO 8601 (time), il nuovo offset in secondi, un flag per l'ora legale e l'abbreviazione in vigore successivamente.

Due considerazioni pratiche: passa sempre $timestampBegin/$timestampEnd per evitare di ottenere l'intero elenco storico, e ricorda che time e offset descrivono il momento dopo ogni transizione, espressi in UTC.

Pratica