timezone_location_get()

Função PHP timezone_location_get()

A função timezone_location_get() retorna a localização geográfica associada a um fuso horário — seu país, latitude e longitude. Isso é útil quando você tem um fuso horário (por exemplo, o vinculado à conta de um usuário) e precisa saber onde no mundo ele aponta, em vez de apenas qual é o deslocamento do relógio.

Esta página aborda o que a função retorna, sua sintaxe e parâmetro, exemplos executáveis, armadilhas comuns e como ela se relaciona com outros auxiliares de fuso horário do PHP.

Sintaxe

<?php

timezone_location_get(DateTimeZone $object): array|false

timezone_location_get() é o alias procedural do método DateTimeZone::getLocation(), portanto $tz->getLocation() e timezone_location_get($tz) são intercambiáveis.

Parâmetro

Observe que — ao contrário de muitas outras funções de fuso horário — esta recebe um objeto DateTimeZone, não uma string de fuso horário. Para construir o objeto a partir de uma string, use new DateTimeZone("Europe/London") ou timezone_open().

Valor de Retorno

Em caso de sucesso, a função retorna um array associativo com estas chaves:

Retorna false se as informações de localização não estiverem disponíveis para o fuso horário fornecido.

Exemplos

Lendo a localização de um fuso horário

Aqui construímos um DateTimeZone para "Europe/London" e exibimos seus dados de localização:

Saída:

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

A função retorna um array associativo descrevendo onde o fuso horário está ancorado. Observe que comments é vazio para muitas zonas — não dependa de ele estar preenchido.

Usando o equivalente orientado a objetos

timezone_location_get($tz) é apenas um alias para DateTimeZone::getLocation(). O seguinte imprime o mesmo array:

<?php

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

Saída:

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

Calculando a distância entre dois fusos horários

Como a função fornece coordenadas reais, você pode fazer cálculos geográficos com elas — por exemplo, a distância de grande círculo (em quilômetros) entre duas 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";

Saída:

5570 km

Armadilhas Comuns

• Precisa de um objeto, não de uma string. Passar "Europe/London" diretamente gera um TypeError. Envolva a string em new DateTimeZone(...) primeiro.
• comments frequentemente está vazio. Trate-o como metadado opcional, não como um rótulo que você pode exibir aos usuários.
• Zonas somente com deslocamento não têm localização. Um DateTimeZone criado a partir de um deslocamento como "+02:00" não está vinculado a um lugar, então a chamada retorna false.
• Identificadores inválidos falham cedo. No PHP 8.0+, construir new DateTimeZone("Not/AZone") lança uma DateInvalidTimeZoneException (um ValueError antes disso), então o erro aparece no momento da construção, não em timezone_location_get().

Funções Relacionadas

• timezone_open() — criar um DateTimeZone a partir de uma string.
• timezone_name_get() — obter o nome de um fuso horário.
• timezone_offset_get() — obter o deslocamento UTC de um fuso horário.
• timezone_identifiers_list() — listar todos os identificadores de fuso horário suportados.
• PHP Timezones — visão geral sobre como trabalhar com fusos horários no PHP.

Conclusão

timezone_location_get() converte um objeto DateTimeZone em dados geográficos concretos — código de país, latitude e longitude — que você pode usar para mapeamento, cálculos de distância ou simplesmente para mostrar aos usuários onde um fuso horário fica. Lembre-se de passar um objeto DateTimeZone (não uma string) e de tratar o retorno false para zonas somente com deslocamento.

Prática