timezone_location_get()

Funzione PHP timezone_location_get()

La funzione timezone_location_get() restituisce la posizione geografica associata a un fuso orario — il paese, la latitudine e la longitudine. È utile quando si dispone di un fuso orario (ad esempio quello associato all'account di un utente) e si vuole sapere dove sulla Terra si trova, piuttosto che solo lo scostamento dell'orologio.

Questa pagina illustra cosa restituisce la funzione, la sua sintassi e i parametri, esempi eseguibili, errori comuni e come si relaziona agli altri helper PHP per i fusi orari.

Sintassi

<?php

timezone_location_get(DateTimeZone $object): array|false

timezone_location_get() è l'alias procedurale del metodo DateTimeZone::getLocation(), quindi $tz->getLocation() e timezone_location_get($tz) sono intercambiabili.

Parametro

Nota che — a differenza di molte altre funzioni per i fusi orari — questa accetta un oggetto DateTimeZone, non una stringa. Per costruire l'oggetto da una stringa, usare new DateTimeZone("Europe/London") oppure timezone_open().

Valore di Ritorno

In caso di successo la funzione restituisce un array associativo con le seguenti chiavi:

Restituisce false se le informazioni sulla posizione non sono disponibili per il fuso orario fornito.

Esempi

Lettura della posizione di un fuso orario

Qui costruiamo un DateTimeZone per "Europe/London" e stampiamo i dati di posizione:

Output:

Array
(
    [country_code] => GB
    [latitude] => 51.50833
    [longitude] => -0.12528
    [comments] =>
)

La funzione restituisce un array associativo che descrive dove il fuso orario è ancorato. Nota che comments è vuoto per molte zone — non fare affidamento sul fatto che sia popolato.

Utilizzo dell'equivalente orientato agli oggetti

timezone_location_get($tz) è solo un alias di DateTimeZone::getLocation(). Il codice seguente stampa lo stesso array:

<?php

$timezone = new DateTimeZone("America/Los_Angeles");
print_r($timezone->getLocation());

Output:

Array
(
    [country_code] => US
    [latitude] => 34.05222
    [longitude] => -118.24278
    [comments] => Pacific
)

Calcolo della distanza tra due fusi orari

Poiché la funzione fornisce coordinate reali, è possibile eseguire calcoli geografici con esse — ad esempio, la distanza ortodromica (in chilometri) tra due zone:

<?php

$a = timezone_location_get(new DateTimeZone("Europe/London"));
$b = timezone_location_get(new DateTimeZone("America/New_York"));

$earthRadius = 6371; // km
$dLat = deg2rad($b["latitude"] - $a["latitude"]);
$dLon = deg2rad($b["longitude"] - $a["longitude"]);

$h = sin($dLat / 2) ** 2
   + cos(deg2rad($a["latitude"])) * cos(deg2rad($b["latitude"]))
   * sin($dLon / 2) ** 2;

$distance = 2 * $earthRadius * asin(sqrt($h));
echo round($distance) . " km";

Output:

5570 km

Errori Comuni

• Richiede un oggetto, non una stringa. Passare "Europe/London" direttamente genera un TypeError. Occorre racchiudere la stringa in new DateTimeZone(...) prima.
• comments è spesso vuoto. Trattarlo come metadato opzionale, non come un'etichetta da mostrare agli utenti.
• Le zone solo-offset non hanno posizione. Un DateTimeZone creato da un offset come "+02:00" non è collegato a un luogo, quindi la chiamata restituisce false.
• Gli identificatori non validi falliscono subito. In PHP 8.0+, la costruzione di new DateTimeZone("Not/AZone") lancia una DateInvalidTimeZoneException (un ValueError nelle versioni precedenti), quindi l'errore emerge al momento della costruzione, non in timezone_location_get().

Funzioni Correlate

• timezone_open() — crea un DateTimeZone da una stringa.
• timezone_name_get() — ottiene il nome di un fuso orario.
• timezone_offset_get() — ottiene lo scostamento UTC di un fuso orario.
• timezone_identifiers_list() — elenca tutti gli identificatori di fuso orario supportati.
• PHP Timezones — panoramica sul lavoro con i fusi orari in PHP.

Conclusione

timezone_location_get() trasforma un oggetto DateTimeZone in dati geografici concreti — codice paese, latitudine e longitudine — che è possibile utilizzare per la mappatura, il calcolo delle distanze o semplicemente per mostrare agli utenti dove si trova un fuso orario. Ricordare di passare un oggetto DateTimeZone (non una stringa) e di gestire il ritorno false per le zone solo-offset.

Esercitazione