timezone_open()

A Função PHP timezone_open()

timezone_open() cria um novo objeto DateTimeZone a partir de um identificador de fuso horário. É o alias em estilo procedural de new DateTimeZone() — ambos fazem exatamente a mesma coisa, então você pode usar o estilo que melhor se adaptar ao seu código.

Um objeto DateTimeZone por si só não "faz" nada. Sua função é ser passado para um objeto DateTime para que os timestamps sejam interpretados e exibidos no fuso correto. É isso que torna timezone_open() útil: ele permite que um único script exiba o mesmo instante de tempo corretamente para usuários em Nova York, Paris ou Tóquio.

Sintaxe

timezone_open(string $timezone): DateTimeZone|false

Parâmetro

• $timezone — um identificador de fuso horário. Use um nome IANA completo como "America/New_York", "Europe/Paris" ou "UTC". Abreviações como "EST" são aceitas, mas são ambíguas e é melhor evitá-las. A lista completa vem de timezone_identifiers_list().

Valor de retorno

• Um objeto DateTimeZone em caso de sucesso.
• false se o identificador não for reconhecido (um Warning também é gerado). Por isso, sempre valide identificadores fornecidos pelo usuário antes de passá-los.

Exemplos Práticos

Exemplo 1: Definindo o fuso horário padrão

timezone_open() não altera o fuso horário padrão do script — isso é tarefa de date_default_timezone_set(). Defina-o uma vez próximo ao início do seu script para que qualquer DateTime criado sem um fuso explícito use o correto:

<?php

date_default_timezone_set('America/New_York');

echo date_default_timezone_get(); // America/New_York

Exemplo 2: Criando um DateTime com um fuso horário específico

Passe o objeto retornado por timezone_open() como segundo argumento para o construtor de DateTime. 'now' é então interpretado nesse fuso:

O P no final do formato imprime o deslocamento UTC (por exemplo, +02:00), para que você possa confirmar que o fuso foi aplicado.

Exemplo 3: Convertendo entre fusos horários

Um DateTime sempre armazena um instante absoluto. Chamar setTimezone() não move o instante — apenas muda como esse instante é exibido. Aqui, o meio-dia em Nova York é mostrado como o horário equivalente em Paris:

O relógio avança seis horas porque Paris está seis horas à frente de Nova York em janeiro.

Exemplo 4: Protegendo-se contra um identificador inválido

Como timezone_open() retorna false em caso de falha, verifique o resultado antes de usá-lo — especialmente quando o identificador vem de entrada do usuário:

<?php

$tz = @timezone_open('Mars/Olympus_Mons');

if ($tz === false) {
    echo 'Unknown timezone, falling back to UTC.';
    $tz = timezone_open('UTC');
}

echo "\n", $tz->getName(); // UTC

Quando usar timezone_open()

• Exibir um instante em vários fusos — armazene tudo em UTC e converta na exibição com setTimezone().
• Ler o deslocamento ou o nome do fuso de um DateTime via timezone_name_get() ou timezone_offset_get().
• Bases de código procedurais que preferem chamadas function() em vez de new por consistência.

Se você escreve PHP orientado a objetos, new DateTimeZone('Europe/Paris') é mais natural e se comporta de forma idêntica.

Conclusão

timezone_open() constrói um objeto DateTimeZone a partir de um identificador para que os valores de DateTime sejam interpretados e exibidos no fuso correto. As ideias principais: é intercambiável com new DateTimeZone(), retorna false em caso de identificador inválido (portanto, valide a entrada) e setTimezone() altera apenas o horário exibido, nunca o instante subjacente. Para uma visão mais ampla, consulte PHP Timezones e PHP Date and Time.

Prática