Entendendo a Função PHP Date Timezone Version Get

A função timezone_version_get() retorna a versão do banco de dados de fuso horário incluído na extensão intl. O banco de dados de fuso horário (comumente chamado de tz database ou IANA tz data) é a fonte canônica das regras de fuso horário do mundo — offsets UTC, transições de horário de verão e mudanças históricas. Os governos alteram essas regras regularmente, portanto o banco de dados é revisado várias vezes por ano e marcado com uma versão como 2024.1.

Conhecer a versão é importante porque regras desatualizadas produzem horários errados. Se um país altera a data de início do horário de verão e seu servidor ainda usa um banco de dados antigo, todos os cálculos de data nessa transição estarão errados em uma hora. A função timezone_version_get() permite que você leia qual versão o PHP está realmente usando para que possa auditá-la, registrá-la ou alertar quando estiver desatualizada.

Esta página cobre a sintaxe, como chamá-la com segurança, como interpretar o resultado e como ela se relaciona com as outras funções de fuso horário do PHP.

Sintaxe

A função timezone_version_get() tem uma sintaxe muito simples. Aqui está a sintaxe:

A sintaxe da função PHP timezone_version_get()

string timezone_version_get ( void )

Disponível desde PHP 5.2.0.

Esta função não recebe nenhum argumento e retorna uma string contendo apenas o número da versão, como 2023.3 ou 2024.1. O formato é YYYY.N — o ano com quatro dígitos do lançamento IANA seguido pelo lançamento sequencial dentro daquele ano (a, b, c… no IANA tornam-se .1, .2, .3 aqui).

Nota: timezone_version_get() faz parte da extensão intl, não da extensão principal de data/hora. Ela reporta a cópia de dados de fuso horário do intl/ICU incluída, que pode diferir da versão usada pelas classes DateTime/DateTimeZone do PHP. Para verificar se a extensão intl está presente, use extension_loaded('intl') antes de chamá-la.

Uso

Uma chamada típica é feita da seguinte forma:

1. Proteja com extension_loaded('intl') para que o script não falhe em servidores sem a extensão.
2. Chame timezone_version_get() para obter a string de versão.
3. Armazene, registre ou exiba o valor — ou compare-o com um mínimo esperado.

Exemplo

Aqui está um trecho de código de exemplo que mostra como usar a função timezone_version_get() em suas aplicações PHP:

Exemplo da função timezone_version_get() em PHP

Nota: Esta função requer a extensão intl. Se a extensão não estiver habilitada, a função não estará disponível. O exemplo acima inclui uma verificação para evitar um erro fatal.

Aviso quando o banco de dados está desatualizado

Como a versão é apenas uma string YYYY.N, você pode compará-la com um mínimo de sua confiança. Isso é útil para um endpoint de verificação de integridade ou uma proteção de implantação:

<?php
$minimum = '2024.1';
$current = timezone_version_get();

if (version_compare($current, $minimum, '<')) {
    echo "Warning: timezone database $current is older than $minimum. Update the intl/ICU library.";
} else {
    echo "Timezone database $current is up to date.";
}
?>

version_compare() trata a versão com pontos como uma versão de software, portanto 2024.1 é corretamente comparada como mais recente que 2023.3.

Funções relacionadas

timezone_version_get() é a única função que reporta a versão do banco de dados. O restante do conjunto de ferramentas de fuso horário do PHP trabalha com os dados em si:

• date_default_timezone_set() e date_default_timezone_get() — define e lê o fuso horário padrão usado por todas as funções de data.
• timezone_identifiers_list() — lista todos os identificadores de fuso horário suportados (por exemplo, Europe/London).
• timezone_name_get() — obtém o nome de um objeto DateTimeZone.
• timezone_abbreviations_list() — mapeia abreviações como CET para seus offsets.

Conclusão

timezone_version_get() é uma função pequena, mas prática: ela informa exatamente qual banco de dados de fuso horário IANA a extensão intl está usando. Sempre proteja a chamada com extension_loaded('intl') e considere comparar a versão retornada com um mínimo conhecido para que regras de fuso horário desatualizadas sejam detectadas durante a implantação, em vez de aparecerem como timestamps errados em produção.

Prática