Comprendere la funzione PHP Date Timezone Version Get

La funzione timezone_version_get() restituisce la versione del database dei fusi orari incluso nell'estensione intl. Il database dei fusi orari (comunemente chiamato tz database o IANA tz data) è la fonte canonica delle regole mondiali sui fusi orari — offset UTC, transizioni dell'ora legale e modifiche storiche. I governi cambiano queste regole regolarmente, quindi il database viene aggiornato più volte all'anno e contrassegnato con una versione come 2024.1.

Conoscere la versione è importante perché regole non aggiornate producono orari errati. Se un paese modifica la data di inizio dell'ora legale e il server utilizza ancora un database precedente, ogni calcolo di data attorno a quella transizione sarà sfasato di un'ora. timezone_version_get() consente di leggere quale versione PHP sta effettivamente utilizzando, in modo da poterla verificare, registrare o avvisare quando è obsoleta.

Questa pagina illustra la sintassi, come chiamarla in modo sicuro, come interpretare il risultato e come si relaziona alle altre funzioni PHP per i fusi orari.

Sintassi

La funzione timezone_version_get() ha una sintassi molto semplice. Ecco la sintassi:

Sintassi della funzione PHP timezone_version_get()

string timezone_version_get ( void )

Disponibile da PHP 5.2.0.

Questa funzione non accetta argomenti e restituisce una string contenente solo il numero di versione, ad esempio 2023.3 o 2024.1. Il formato è YYYY.N — l'anno a quattro cifre del rilascio IANA seguito dal numero progressivo del rilascio in quell'anno (a, b, c… in IANA diventano .1, .2, .3 qui).

Nota: timezone_version_get() fa parte dell'estensione intl, non dell'estensione core data/ora. Riporta la copia del database dei fusi orari inclusa in intl/ICU, che può differire dalla versione utilizzata dalle classi DateTime/DateTimeZone di PHP. Per verificare se l'estensione intl è presente, usare extension_loaded('intl') prima di chiamarla.

Utilizzo

Una chiamata tipica si svolge così:

1. Proteggere con extension_loaded('intl') in modo che lo script non causi un errore fatale sui server privi dell'estensione.
2. Chiamare timezone_version_get() per recuperare la stringa di versione.
3. Memorizzare, registrare o visualizzare il valore — oppure confrontarlo con un minimo atteso.

Esempio

Ecco un esempio di codice che mostra come utilizzare la funzione timezone_version_get() nelle applicazioni PHP:

Esempio della funzione timezone_version_get() in PHP

Nota: questa funzione richiede l'estensione intl. Se l'estensione non è abilitata, la funzione non sarà disponibile. L'esempio sopra include un controllo per prevenire un errore fatale.

Avviso quando il database è obsoleto

Poiché la versione è semplicemente una stringa YYYY.N, è possibile confrontarla con un minimo ritenuto affidabile. Questo è utile per un endpoint di health-check o una verifica durante il deployment:

<?php
$minimum = '2024.1';
$current = timezone_version_get();

if (version_compare($current, $minimum, '<')) {
    echo "Warning: timezone database $current is older than $minimum. Update the intl/ICU library.";
} else {
    echo "Timezone database $current is up to date.";
}
?>

version_compare() tratta la versione con punto come una versione software, quindi 2024.1 viene correttamente confrontata come più recente di 2023.3.

Funzioni correlate

timezone_version_get() è l'unica funzione che riporta la versione del database. Il resto del kit PHP per i fusi orari lavora con i dati stessi:

• date_default_timezone_set() e date_default_timezone_get() — impostano e leggono il fuso orario predefinito usato da ogni funzione di data.
• timezone_identifiers_list() — elenca tutti gli identificatori di fuso orario supportati (es. Europe/London).
• timezone_name_get() — ottiene il nome di un oggetto DateTimeZone.
• timezone_abbreviations_list() — mappa le abbreviazioni come CET ai loro offset.

Conclusione

timezone_version_get() è una funzione piccola ma pratica: indica esattamente quale database IANA dei fusi orari sta usando l'estensione intl. Proteggere sempre la chiamata con extension_loaded('intl') e considerare il confronto della versione restituita con un minimo noto, in modo che le regole obsolete emergano durante il deployment anziché come timestamp errati in produzione.

Pratica