timezone_location_get()

Функция PHP timezone_location_get()

Функция timezone_location_get() возвращает географическое местоположение, связанное с часовым поясом, — страну, широту и долготу. Это удобно, когда у вас есть часовой пояс (например, привязанный к аккаунту пользователя) и нужно узнать, где на Земле он находится, а не просто каково его смещение по времени.

На этой странице рассматриваются возвращаемые функцией данные, её синтаксис и параметры, запускаемые примеры, распространённые ловушки, а также связь с другими вспомогательными функциями для работы с часовыми поясами в PHP.

Синтаксис

<?php

timezone_location_get(DateTimeZone $object): array|false

timezone_location_get() является процедурным псевдонимом метода DateTimeZone::getLocation(), поэтому $tz->getLocation() и timezone_location_get($tz) взаимозаменяемы.

Параметр

Обратите внимание, что — в отличие от многих других функций работы с часовыми поясами — эта принимает объект DateTimeZone, а не строку. Чтобы создать объект из строки, используйте new DateTimeZone("Europe/London") или timezone_open().

Возвращаемое значение

При успехе функция возвращает ассоциативный массив со следующими ключами:

Возвращает false, если информация о местоположении недоступна для указанного часового пояса.

Примеры

Чтение местоположения часового пояса

Здесь мы создаём DateTimeZone для "Europe/London" и выводим данные о его местоположении:

Вывод:

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

Функция возвращает ассоциативный массив, описывающий, где закреплён часовой пояс. Обратите внимание, что comments пуст для многих зон — не рассчитывайте на его заполнение.

Использование объектно-ориентированного эквивалента

timezone_location_get($tz) — это просто псевдоним для DateTimeZone::getLocation(). Следующий код выводит тот же массив:

<?php

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

Вывод:

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

Вычисление расстояния между двумя часовыми поясами

Поскольку функция возвращает реальные координаты, с ними можно выполнять географические вычисления — например, расстояние по большому кругу (в километрах) между двумя зонами:

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

Вывод:

5570 km

Распространённые ловушки

• Требуется объект, а не строка. Передача "Europe/London" напрямую вызывает TypeError. Сначала оберните строку в new DateTimeZone(...).
• comments часто пустой. Воспринимайте его как необязательные метаданные, а не метку для отображения пользователям.
• Зоны только со смещением не имеют местоположения. DateTimeZone, созданный из смещения вроде "+02:00", не привязан к месту, поэтому вызов возвращает false.
• Неверные идентификаторы дают ошибку сразу. В PHP 8.0+ создание new DateTimeZone("Not/AZone") выбрасывает DateInvalidTimeZoneException (до этого — ValueError), поэтому ошибка возникает при конструировании объекта, а не в timezone_location_get().

Связанные функции

• timezone_open() — создание DateTimeZone из строки.
• timezone_name_get() — получение имени часового пояса.
• timezone_offset_get() — получение смещения UTC для часового пояса.
• timezone_identifiers_list() — список всех поддерживаемых идентификаторов часовых поясов.
• PHP Timezones — обзор работы с часовыми поясами в PHP.

Заключение

timezone_location_get() превращает объект DateTimeZone в конкретные географические данные — код страны, широту и долготу, — которые можно использовать для картографии, вычисления расстояний или просто для того, чтобы показать пользователям, где находится часовой пояс. Не забывайте передавать объект DateTimeZone (а не строку) и обрабатывать возвращаемое значение false для зон, основанных только на смещении.

Практика