timezone_location_get()

Función PHP timezone_location_get()

La función timezone_location_get() devuelve la ubicación geográfica asociada a una zona horaria: su país, latitud y longitud. Es útil cuando tienes una zona horaria (por ejemplo, la vinculada a la cuenta de un usuario) y necesitas saber dónde en el planeta apunta, en lugar de solo cuál es su desplazamiento horario.

Esta página cubre qué devuelve la función, su sintaxis y parámetros, ejemplos ejecutables, errores comunes y cómo se relaciona con los demás helpers de zona horaria de PHP.

Sintaxis

<?php

timezone_location_get(DateTimeZone $object): array|false

timezone_location_get() es el alias procedimental del método DateTimeZone::getLocation(), por lo que $tz->getLocation() y timezone_location_get($tz) son intercambiables.

Parámetro

Ten en cuenta que, a diferencia de muchas otras funciones de zona horaria, esta acepta un objeto DateTimeZone, no una cadena de texto. Para construir el objeto a partir de una cadena, usa new DateTimeZone("Europe/London") o timezone_open().

Valor de retorno

Si tiene éxito, la función devuelve un array asociativo con estas claves:

Devuelve false si la información de ubicación no está disponible para la zona horaria indicada.

Ejemplos

Leer la ubicación de una zona horaria

Aquí construimos un DateTimeZone para "Europe/London" e imprimimos sus datos de ubicación:

Salida:

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

La función devuelve un array asociativo que describe dónde está anclada la zona horaria. Ten en cuenta que comments está vacío en muchas zonas; no confíes en que esté poblado.

Usar el equivalente orientado a objetos

timezone_location_get($tz) es simplemente un alias de DateTimeZone::getLocation(). Lo siguiente imprime el mismo array:

<?php

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

Salida:

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

Calcular la distancia entre dos zonas horarias

Como la función te proporciona coordenadas reales, puedes hacer cálculos geográficos con ellas, por ejemplo, la distancia de gran círculo (en kilómetros) entre dos zonas:

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

Salida:

5570 km

Errores comunes

• Necesita un objeto, no una cadena. Pasar "Europe/London" directamente genera un TypeError. Envuelve la cadena en new DateTimeZone(...) primero.
• comments suele estar vacío. Trátalo como metadatos opcionales, no como una etiqueta que puedas mostrar a los usuarios.
• Las zonas basadas solo en desplazamiento no tienen ubicación. Un DateTimeZone creado a partir de un desplazamiento como "+02:00" no está vinculado a un lugar, por lo que la llamada devuelve false.
• Los identificadores inválidos fallan desde el principio. En PHP 8.0+, construir new DateTimeZone("Not/AZone") lanza una DateInvalidTimeZoneException (un ValueError antes de esa versión), de modo que el error aparece en el momento de construcción, no en timezone_location_get().

Funciones relacionadas

• timezone_open() — crear un DateTimeZone a partir de una cadena.
• timezone_name_get() — obtener el nombre de una zona horaria.
• timezone_offset_get() — obtener el desplazamiento UTC de una zona horaria.
• timezone_identifiers_list() — listar todos los identificadores de zona horaria admitidos.
• PHP Timezones — visión general del trabajo con zonas horarias en PHP.

Conclusión

timezone_location_get() convierte un objeto DateTimeZone en datos geográficos concretos: código de país, latitud y longitud, que puedes usar para mapas, cálculos de distancias o simplemente para mostrar a los usuarios dónde se encuentra una zona horaria. Recuerda pasar un objeto DateTimeZone (no una cadena) y gestionar el retorno false para zonas basadas solo en desplazamiento.

Práctica