timezone_identifiers_list()

Введение

Функция timezone_identifiers_list() возвращает массив всех идентификаторов часовых поясов, известных PHP. Идентификаторы часовых поясов — это строки в формате Area/Location (например, America/New_York, Europe/London, Asia/Tokyo), взятые из базы данных часовых поясов IANA, поставляемой вместе с PHP.

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

Синтаксис

timezone_identifiers_list(
    int $timezoneGroup = DateTimeZone::ALL,
    ?string $countryCode = null
): array

Оба параметра необязательны и были добавлены в PHP 5.3; поведение фильтрации по стране уточнялось в последующих версиях:

• $timezoneGroup — константа DateTimeZone, ограничивающая результат одним регионом, например DateTimeZone::EUROPE, DateTimeZone::AMERICA или DateTimeZone::ASIA. Значение по умолчанию DateTimeZone::ALL возвращает все стандартные идентификаторы.
• $countryCode — двухбуквенный код страны по ISO 3166-1 (например 'US', 'GB', 'IN'). Применяется только тогда, когда $timezoneGroup установлен в DateTimeZone::PER_COUNTRY.

Функция возвращает нумерованный массив строк. Идентификаторы отсортированы в алфавитном порядке.

timezone_identifiers_list() является процедурным псевдонимом DateTimeZone::listIdentifiers() — обе функции дают одинаковый результат.

Получение всех идентификаторов

<?php

$identifiers = timezone_identifiers_list();

echo count($identifiers) . " timezones\n";
echo $identifiers[0] . "\n";
echo $identifiers[1] . "\n";

Вывод (точное количество зависит от версии PHP/IANA):

419 timezones
Africa/Abidjan
Africa/Accra

Можно перебрать массив, чтобы вывести все доступные часовые пояса:

<?php

foreach (timezone_identifiers_list() as $tz) {
    echo $tz . "\n";
}

Фильтрация по региону или стране

Передайте групповую константу DateTimeZone, чтобы сузить список до одного континента:

<?php

$european = timezone_identifiers_list(DateTimeZone::EUROPE);

echo $european[0] . "\n"; // Europe/Amsterdam

Чтобы получить часовые пояса одной страны, используйте DateTimeZone::PER_COUNTRY вместе с кодом страны:

<?php

$usZones = timezone_identifiers_list(DateTimeZone::PER_COUNTRY, 'US');

echo $usZones[0] . "\n"; // America/Adak
echo in_array('America/New_York', $usZones, true) ? "found\n" : "missing\n"; // found

Это удобно при создании выбора с учётом страны — например, отображать только часовые пояса США после того, как пользователь выбрал «United States».

Проверка пользовательского ввода

Поскольку функция возвращает авторитетный список, это наиболее надёжный способ проверить корректность строки с часовым поясом перед её передачей в DateTimeZone или date_default_timezone_set():

<?php

function isValidTimezone(string $tz): bool
{
    return in_array($tz, timezone_identifiers_list(), true);
}

var_dump(isValidTimezone('Europe/London'));     // bool(true)
var_dump(isValidTimezone('Mars/Olympus_Mons')); // bool(false)

Применение идентификатора

Получив корректный идентификатор, установите его в качестве глобального значения по умолчанию для скрипта с помощью date_default_timezone_set():

<?php

date_default_timezone_set('America/New_York');

Или создайте объект DateTimeZone, чтобы привязать часовой пояс к конкретной дате без изменения глобального значения по умолчанию:

<?php

$timezone = new DateTimeZone('Asia/Tokyo');
$date = new DateTime('now', $timezone);

echo $date->format('Y-m-d H:i:s P');

PHP также принимает фиксированное смещение UTC вместо именованного пояса. Это полностью исключает учёт летнего времени:

<?php

$timezone = new DateTimeZone('-08:00');

Примечания и особенности

• Список формируется из базы данных IANA, поставляемой с вашей сборкой PHP, поэтому точные идентификаторы и их количество могут меняться между версиями PHP. Используйте timezone_version_get(), чтобы узнать, какая версия базы данных активна.
• Некоторые устаревшие идентификаторы являются нерекомендуемыми и могут быть удалены в будущих версиях. Предпочитайте канонические имена в формате Area/Location аббревиатурам.
• Для получения аббревиатур часовых поясов (таких как CET или PST), а не полных идентификаторов, см. timezone_abbreviations_list().
• Для более широкого обзора работы с часовыми поясами в PHP читайте PHP Timezones.

Практика

Практика