timezone_location_get()

Fonction PHP timezone_location_get()

La fonction timezone_location_get() retourne la localisation géographique associée à un fuseau horaire — son pays, sa latitude et sa longitude. C'est très utile lorsque vous disposez d'un fuseau horaire (par exemple celui attaché au compte d'un utilisateur) et que vous souhaitez savoir où sur Terre il se situe, plutôt que de connaître simplement le décalage de son horloge.

Cette page explique ce que retourne la fonction, sa syntaxe et son paramètre, des exemples exécutables, les pièges courants, et comment elle se rapporte aux autres fonctions de gestion des fuseaux horaires de PHP.

Syntaxe

<?php

timezone_location_get(DateTimeZone $object): array|false

timezone_location_get() est l'alias procédural de la méthode DateTimeZone::getLocation(), donc $tz->getLocation() et timezone_location_get($tz) sont interchangeables.

Paramètre

Notez que — contrairement à de nombreuses autres fonctions de fuseaux horaires — celle-ci prend un objet DateTimeZone, et non une chaîne de fuseau horaire. Pour construire l'objet à partir d'une chaîne, utilisez new DateTimeZone("Europe/London") ou timezone_open().

Valeur de retour

En cas de succès, la fonction retourne un tableau associatif avec les clés suivantes :

La fonction retourne false si les informations de localisation ne sont pas disponibles pour le fuseau horaire donné.

Exemples

Lecture de la localisation d'un fuseau horaire

Ici, nous construisons un DateTimeZone pour "Europe/London" et affichons ses données de localisation :

Résultat :

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

La fonction retourne un tableau associatif décrivant où le fuseau horaire est ancré. Notez que comments est vide pour de nombreux fuseaux — ne comptez pas sur cette valeur pour l'afficher à vos utilisateurs.

Utilisation de l'équivalent orienté objet

timezone_location_get($tz) est simplement un alias de DateTimeZone::getLocation(). Le code suivant affiche le même tableau :

<?php

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

Résultat :

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

Calcul de la distance entre deux fuseaux horaires

Puisque la fonction vous donne de vraies coordonnées, vous pouvez effectuer des calculs géographiques — par exemple, la distance orthodromique (en kilomètres) entre deux fuseaux :

<?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";

Résultat :

5570 km

Pièges courants

• La fonction attend un objet, pas une chaîne. Passer "Europe/London" directement génère une TypeError. Enveloppez la chaîne dans new DateTimeZone(...) au préalable.
• comments est fréquemment vide. Traitez-le comme des métadonnées optionnelles, pas comme une étiquette à afficher aux utilisateurs.
• Les fuseaux définis uniquement par un décalage n'ont pas de localisation. Un DateTimeZone créé à partir d'un décalage tel que "+02:00" n'est pas lié à un lieu, donc l'appel retourne false.
• Les identifiants invalides échouent tôt. En PHP 8.0+, construire new DateTimeZone("Not/AZone") lève une DateInvalidTimeZoneException (une ValueError avant cela), donc l'erreur apparaît à la construction, pas dans timezone_location_get().

Fonctions associées

• timezone_open() — créer un DateTimeZone à partir d'une chaîne.
• timezone_name_get() — obtenir le nom d'un fuseau horaire.
• timezone_offset_get() — obtenir le décalage UTC d'un fuseau horaire.
• timezone_identifiers_list() — lister tous les identifiants de fuseaux horaires pris en charge.
• PHP Timezones — aperçu de la gestion des fuseaux horaires en PHP.

Conclusion

timezone_location_get() transforme un objet DateTimeZone en données géographiques concrètes — code pays, latitude et longitude — que vous pouvez utiliser pour la cartographie, les calculs de distance, ou simplement pour montrer aux utilisateurs où se situe un fuseau horaire. N'oubliez pas de passer un objet DateTimeZone (pas une chaîne) et de gérer le retour false pour les fuseaux définis uniquement par un décalage.

Pratique