timezone_identifiers_list()

Introduzione

La funzione timezone_identifiers_list() restituisce un array contenente ogni identificatore di fuso orario conosciuto da PHP. Gli identificatori di fuso orario sono stringhe nel formato Area/Location (ad esempio America/New_York, Europe/London, Asia/Tokyo) e provengono dal database dei fusi orari IANA incluso in PHP.

Questa pagina illustra la firma della funzione, come interpretarne il valore restituito, come filtrare l'elenco per continente o paese e i casi d'uso più comuni: costruire un menu a tendina per i fusi orari e validare i nomi di fuso orario forniti dall'utente.

Sintassi

timezone_identifiers_list(
    int $timezoneGroup = DateTimeZone::ALL,
    ?string $countryCode = null
): array

Entrambi i parametri sono opzionali e sono stati aggiunti in PHP 5.3, con il comportamento del filtro per paese perfezionato nelle versioni successive:

• $timezoneGroup — una costante DateTimeZone che limita il risultato a una regione, ad esempio DateTimeZone::EUROPE, DateTimeZone::AMERICA o DateTimeZone::ASIA. Il valore predefinito DateTimeZone::ALL restituisce ogni identificatore standard.
• $countryCode — un codice paese di due lettere secondo ISO 3166-1 (ad esempio 'US', 'GB', 'IN'). Ha effetto solo quando $timezoneGroup è impostato su DateTimeZone::PER_COUNTRY.

La funzione restituisce un array di stringhe indicizzato numericamente. Gli identificatori vengono restituiti in ordine alfabetico.

timezone_identifiers_list() è l'alias procedurale di DateTimeZone::listIdentifiers() — entrambi producono lo stesso risultato.

Elencare tutti gli identificatori

<?php

$identifiers = timezone_identifiers_list();

echo count($identifiers) . " timezones\n";
echo $identifiers[0] . "\n";
echo $identifiers[1] . "\n";

Output (il numero esatto dipende dalla versione di PHP/IANA in uso):

419 timezones
Africa/Abidjan
Africa/Accra

È possibile iterare sull'array per stampare ogni fuso orario disponibile:

<?php

foreach (timezone_identifiers_list() as $tz) {
    echo $tz . "\n";
}

Filtrare per regione o paese

Passa una costante di gruppo DateTimeZone per restringere l'elenco a un solo continente:

<?php

$european = timezone_identifiers_list(DateTimeZone::EUROPE);

echo $european[0] . "\n"; // Europe/Amsterdam

Per ottenere i fusi orari di un singolo paese, usa DateTimeZone::PER_COUNTRY insieme a un codice paese:

<?php

$usZones = timezone_identifiers_list(DateTimeZone::PER_COUNTRY, 'US');

echo $usZones[0] . "\n"; // America/Adak
echo in_array('America/New_York', $usZones, true) ? "found\n" : "missing\n"; // found

Questo risulta utile quando si vuole un selettore consapevole del paese — ad esempio, mostrare solo i fusi orari degli USA dopo che l'utente ha selezionato "United States".

Validare l'input dell'utente

Poiché la funzione restituisce un elenco autorevole, è il modo più sicuro per verificare se una stringa di fuso orario è valida prima di passarla a DateTimeZone o date_default_timezone_set():

<?php

function isValidTimezone(string $tz): bool
{
    return in_array($tz, timezone_identifiers_list(), true);
}

var_dump(isValidTimezone('Europe/London'));     // bool(true)
var_dump(isValidTimezone('Mars/Olympus_Mons')); // bool(false)

Applicare un identificatore

Una volta ottenuto un identificatore valido, impostalo come predefinito per l'intero script con date_default_timezone_set():

<?php

date_default_timezone_set('America/New_York');

Oppure crea un oggetto DateTimeZone per associare un fuso orario a una data specifica senza modificare il valore predefinito globale:

<?php

$timezone = new DateTimeZone('Asia/Tokyo');
$date = new DateTime('now', $timezone);

echo $date->format('Y-m-d H:i:s P');

PHP accetta anche un offset UTC fisso al posto di una zona con nome. In questo modo si saltano completamente le regole sull'ora legale:

<?php

$timezone = new DateTimeZone('-08:00');

Note e avvertenze

• L'elenco è costruito dal database IANA incluso nella propria versione di PHP, quindi gli identificatori esatti e il loro numero possono cambiare tra versioni diverse di PHP. Usa timezone_version_get() per verificare quale versione del database è attiva.
• Alcuni identificatori legacy sono deprecati e potrebbero essere rimossi nelle versioni future. Preferire i nomi canonici Area/Location rispetto alle abbreviazioni.
• Per le abbreviazioni di fuso orario (come CET o PST) invece degli identificatori completi, consulta timezone_abbreviations_list().
• Per una panoramica più ampia sull'utilizzo dei fusi orari in PHP, leggi PHP Timezones.

Esercitati

Esercitati