Função PHP date_timezone_get()

A função date_timezone_get() retorna o fuso horário associado a um objeto DateTime como um objeto DateTimeZone. Saber qual fuso horário uma data carrega é o que diferencia um timestamp que significa "15h em Nova York" de um que significa "15h em algum lugar indefinido" — e errar isso é uma das fontes mais comuns de bugs de horas erradas em aplicações PHP.

Esta página aborda a assinatura da função, o que ela retorna (inclusive em caso de falha), o equivalente orientado a objetos que você verá com mais frequência em código real, e exemplos práticos como leitura e conversão de fuso horário.

Entendendo Fusos Horários em PHP

Um fuso horário é uma região geográfica que compartilha o mesmo horário padrão. Cada um é identificado por um nome IANA único, como America/New_York ou Europe/London. O PHP vem com o banco de dados IANA completo; você pode listar todos os nomes suportados com timezone_identifiers_list().

Todo objeto DateTime carrega um fuso horário internamente. Se você não especificar um, ele utiliza o fuso horário padrão do script — o valor definido por date_default_timezone_set() (ou, na ausência disso, a diretiva date.timezone no php.ini). Para alterar o fuso horário de um objeto existente em vez de lê-lo, use date_timezone_set().

Um ponto importante: date_timezone_get() não converte o horário. Ela apenas reporta o rótulo de fuso horário atualmente associado ao objeto. Para de fato deslocar o valor do horário para outro fuso, você muda o fuso horário com setTimezone() / date_timezone_set().

A Função date_timezone_get()

date_timezone_get() é o alias procedural do método DateTime::getTimezone(). Ambos fazem a mesma coisa — retornam a instância de DateTimeZone mantida por um objeto DateTime (ou DateTimeImmutable).

Sintaxe

date_timezone_get(DateTimeInterface $object): DateTimeZone|false

O equivalente orientado a objetos:

$object->getTimezone();

Parâmetros

• $object: Um objeto DateTime ou DateTimeImmutable do qual o fuso horário será lido.

Valor de Retorno

Em caso de sucesso, retorna um objeto DateTimeZone. Retorna false em caso de falha (por exemplo, se o objeto não tiver informações de fuso horário associadas). Chame getName() no resultado para obter a string IANA, como "Europe/London".

Exemplos

Aqui estão alguns exemplos de como a função date_timezone_get() pode ser utilizada:

Exemplo 1: Obtendo o Fuso Horário da Data e Hora Atual

Um DateTime criado sem um fuso horário explícito herda o padrão do script, portanto a saída aqui é o que foi passado para date_default_timezone_set() — UTC neste exemplo.

Exemplo 2: Obtendo o Fuso Horário Após Alterá-lo

Após setTimezone() reatribuir o fuso, date_timezone_get() reporta o novo valor, America/New_York.

Exemplo 3: Lendo o Deslocamento e Convertendo Entre Fusos

Como date_timezone_get() retorna um objeto DateTimeZone completo, você pode passá-lo para outras chamadas que reconhecem fusos horários — por exemplo, para ler o deslocamento UTC ou para converter um momento de um fuso para outro:

<?php
// 9:00 AM in London on a summer date (BST, UTC+1)
$london = new DateTime('2023-07-01 09:00:00', new DateTimeZone('Europe/London'));

$tz = date_timezone_get($london);
echo $tz->getName(), "\n";                  // Europe/London
echo $tz->getOffset($london) / 3600, "\n";  // 1  (hours east of UTC)

// Convert the same instant to Tokyo time
$london->setTimezone(new DateTimeZone('Asia/Tokyo'));
echo $london->format('Y-m-d H:i'), "\n";    // 2023-07-01 17:00

O instante é idêntico; apenas a representação do horário muda — 09:00 BST em Londres equivale a 17:00 JST em Tóquio. Consulte date_format() para os caracteres de formatação usados acima.

Armadilhas Comuns

• Ela lê, não converte. date_timezone_get() apenas retorna o fuso associado. Reatribuir o resultado a outra variável não alterará a data — use setTimezone() para isso.
• Fuso padrão vs. fuso explícito. Um objeto criado sem um fuso horário herda o padrão do script. Se esse padrão estiver errado, cada leitura parecerá correta, mas o horário subjacente estará incorreto. Defina-o uma vez com date_default_timezone_set().
• Prefira a forma OOP em código moderno. $object->getTimezone() é a mesma chamada e se lê de forma mais natural dentro de cadeias de métodos.

Conclusão

date_timezone_get() retorna o DateTimeZone associado a um objeto DateTime, fornecendo o nome IANA e as ferramentas para ler deslocamentos ou converter entre fusos. Combinada com date_default_timezone_set() e date_timezone_set(), ela permite manter os timestamps sem ambiguidade para usuários e servidores em diferentes partes do mundo.

Prática