timezone_identifiers_list()

Introdução

A função timezone_identifiers_list() retorna um array com todos os identificadores de fuso horário que o PHP conhece. Os identificadores de fuso horário são strings no formato Area/Location (por exemplo, America/New_York, Europe/London, Asia/Tokyo) e provêm do banco de dados de fusos horários IANA incluído no PHP.

Esta página aborda a assinatura da função, como interpretar o valor retornado, como filtrar a lista por continente ou país e os usos mais comuns no mundo real: criar um menu suspenso de fusos horários e validar nomes de fusos horários fornecidos pelo usuário.

Sintaxe

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

Ambos os parâmetros são opcionais e foram adicionados no PHP 5.3, com o comportamento do filtro por país refinado em versões posteriores:

• $timezoneGroup — uma constante DateTimeZone que limita o resultado a uma região, como DateTimeZone::EUROPE, DateTimeZone::AMERICA ou DateTimeZone::ASIA. O valor padrão DateTimeZone::ALL retorna todos os identificadores padrão.
• $countryCode — um código de país de duas letras conforme a ISO 3166-1 (por exemplo, 'US', 'GB', 'IN'). Só tem efeito quando $timezoneGroup está definido como DateTimeZone::PER_COUNTRY.

A função retorna um array de strings indexado numericamente. Os identificadores são retornados em ordem alfabética.

timezone_identifiers_list() é o alias procedural de DateTimeZone::listIdentifiers() — ambos produzem o mesmo resultado.

Listando todos os identificadores

<?php

$identifiers = timezone_identifiers_list();

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

Saída (a contagem exata depende da versão do PHP/IANA):

419 timezones
Africa/Abidjan
Africa/Accra

Você pode iterar sobre o array para exibir todos os fusos horários disponíveis:

<?php

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

Filtrando por região ou país

Passe uma constante de grupo DateTimeZone para restringir a lista a um continente:

<?php

$european = timezone_identifiers_list(DateTimeZone::EUROPE);

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

Para obter os fusos horários de um único país, use DateTimeZone::PER_COUNTRY junto com um código de país:

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

Isso é útil quando você deseja um seletor com consciência de país — por exemplo, exibir apenas os fusos horários dos EUA após o usuário selecionar "United States".

Validando a entrada do usuário

Como a função retorna uma lista autoritativa, é a forma mais segura de verificar se uma string de fuso horário é válida antes de passá-la para DateTimeZone ou 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)

Aplicando um identificador

Depois de ter um identificador válido, defina-o como o padrão em todo o script com date_default_timezone_set():

<?php

date_default_timezone_set('America/New_York');

Ou crie um objeto DateTimeZone para associar um fuso horário a uma data específica sem alterar o padrão global:

<?php

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

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

O PHP também aceita um deslocamento UTC fixo em vez de um fuso nomeado. Isso ignora completamente as regras de horário de verão:

<?php

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

Notas e armadilhas

• A lista é construída a partir do banco de dados IANA incluído na sua versão do PHP, portanto os identificadores exatos e a contagem podem mudar entre versões do PHP. Use timezone_version_get() para verificar qual versão do banco de dados está ativa.
• Alguns identificadores legados estão obsoletos e podem ser removidos em versões futuras. Prefira os nomes canônicos Area/Location em vez de abreviações.
• Para abreviações de fuso horário (como CET ou PST) em vez de identificadores completos, consulte timezone_abbreviations_list().
• Para uma visão geral mais ampla sobre como trabalhar com fusos horários no PHP, leia PHP Timezones.

Practice

Practice