timezone_offset_get()

A função timezone_offset_get() no PHP retorna o deslocamento de fuso horário em segundos em relação ao Tempo Universal Coordenado (UTC) para um dado objeto DateTimeInterface. Este guia abrange sua sintaxe, parâmetros e uso prático.

Entendendo timezone_offset_get()

A função timezone_offset_get() retorna o deslocamento do fuso horário em segundos em relação ao Tempo Universal Coordenado (UTC) para uma data e hora especificadas. É uma função nativa do PHP que permite aos desenvolvedores manipular datas e horas de acordo com fusos horários específicos.

Sintaxe

A sintaxe da função timezone_offset_get() no PHP é a seguinte:

A sintaxe da função timezone_offset_get() no PHP

<?php
timezone_offset_get(DateTimeZone $object, DateTimeInterface $datetime): int

De forma procedural, a função recebe um DateTimeZone e o DateTimeInterface para o qual você deseja o deslocamento, e retorna o deslocamento em segundos. A maioria das pessoas usa o equivalente orientado a objetos, DateTimeZone::getOffset(), que é mais legível:

<?php
$tz   = new DateTimeZone('America/Los_Angeles');
$date = new DateTime('2019-01-01 12:00:00', $tz);

// These two calls are equivalent:
$offset = timezone_offset_get($tz, $date);
$offset = $tz->getOffset($date);

Parâmetros

A função timezone_offset_get() recebe dois parâmetros:

1. $object - Um objeto DateTimeZone cujo deslocamento você deseja obter.
2. $datetime - Um objeto DateTimeInterface (um DateTime ou DateTimeImmutable) que representa o instante de tempo para o qual o deslocamento é calculado.

O instante importa: por causa do horário de verão, o mesmo fuso horário pode ter um deslocamento diferente no verão e no inverno, portanto você deve informar à função qual instante deseja.

Valor de Retorno e Notas

• Valor de Retorno: Retorna um deslocamento inteiro em segundos. É negativo para fusos horários a oeste do UTC (as Américas) e positivo para os que estão a leste.
• Versão do PHP: Disponível desde o PHP 5.2.0.
• Tratamento de Horário de Verão: O deslocamento leva automaticamente em conta o horário de verão. Para America/Los_Angeles, uma data de inverno retorna -28800 (UTC-8), enquanto uma data de verão retorna -25200 (UTC-7).
• Horas, não segundos: Para converter o resultado em horas, divida por 3600 (por exemplo, -28800 / 3600 = -8).

Aplicações Práticas

A função timezone_offset_get() no PHP é uma ferramenta poderosa para trabalhar com datas e horas em fusos horários específicos. Algumas aplicações práticas desta função incluem:

1. Exibir informações de data e hora de acordo com a preferência de fuso horário do usuário.
2. Converter informações de data e hora de um fuso horário para outro.
3. Realizar cálculos de data e hora com deslocamentos de fuso horário precisos.

Exemplo de Uso

Aqui está um exemplo de uso da função timezone_offset_get() no PHP:

Exemplo da função PHP timezone_offset_get()

A data de janeiro está fora do horário de verão, portanto o deslocamento é -28800 segundos (UTC-8):

-28800

Vendo o horário de verão em ação

Chamar o mesmo fuso horário com uma data de verão retorna um deslocamento diferente, porque o Horário de Verão do Pacífico é UTC-7. Formatar o deslocamento em horas torna o resultado mais fácil de ler:

<?php
$tz = new DateTimeZone('America/Los_Angeles');

foreach (['2019-01-01 12:00:00', '2019-07-01 12:00:00'] as $when) {
    $date    = new DateTime($when, $tz);
    $seconds = $tz->getOffset($date);
    $hours   = $seconds / 3600;
    echo "$when => $seconds seconds (UTC$hours)\n";
}

2019-01-01 12:00:00 => -28800 seconds (UTC-8)
2019-07-01 12:00:00 => -25200 seconds (UTC-7)

Conclusão

timezone_offset_get() (e seu equivalente orientado a objetos DateTimeZone::getOffset()) fornece a distância exata de um fuso horário em relação ao UTC em segundos para um momento específico, com o horário de verão já considerado. Divida por 3600 quando precisar de horas e lembre-se de passar a data relevante para que o horário de verão seja resolvido corretamente.

Para aprofundar, consulte date_default_timezone_set() para definir o fuso horário padrão do script, timezone_name_get() para ler o nome de um fuso horário, e a lista completa de fusos horários do PHP.

Prática