timezone_name_get()

Introdução

Este artigo aborda a função timezone_name_get no PHP. Exploraremos sua sintaxe, parâmetros e valores de retorno, além de exemplos do mundo real. Essa função lê o identificador de um objeto DateTimeZone, o que é útil quando você armazena um objeto de fuso horário e depois precisa do seu nome para registro, exibição ou comparação.

timezone_name_get é o alias procedural do método DateTimeZone::getName. Os dois são intercambiáveis, portanto use o estilo que melhor se adapta ao seu código.

Disponibilidade: timezone_name_get faz parte da extensão de data/hora integrada do PHP. Está sempre disponível — nenhuma extensão adicional (como intl) precisa ser instalada.

Sintaxe

A função timezone_name_get recebe um único objeto DateTimeZone e retorna o nome do fuso horário que ele representa. Veja a assinatura:

Sintaxe da função timezone_name_get() do PHP

timezone_name_get(DateTimeZone $object): string

Vamos detalhar os parâmetros:

• $object: Este é um objeto DateTimeZone que representa um fuso horário.

Parâmetros

Conforme mencionado acima, a função timezone_name_get recebe apenas um parâmetro: um objeto DateTimeZone. Esse objeto representa um fuso horário específico e é criado usando a classe DateTimeZone. Veja um exemplo de criação de um objeto DateTimeZone:

Exemplo de criação de objeto DateTimeZone no PHP

<?php

$timezone = new DateTimeZone('America/New_York');

Neste exemplo, criamos um objeto DateTimeZone que representa o Fuso Horário do Leste dos Estados Unidos.

Observação: No PHP 8+, a verificação de tipos estrita é aplicada. Passar um argumento que não seja um objeto DateTimeZone lançará um TypeError.

Valores de Retorno

A função timezone_name_get retorna uma string que representa o nome do fuso horário representado pelo objeto DateTimeZone passado como parâmetro. Veja um exemplo de como ela pode ser usada:

Exemplo de uso da função timezone_name_get() no PHP

Neste exemplo, criamos um objeto DateTimeZone representando o Fuso Horário do Leste e, em seguida, o passamos para a função timezone_name_get. A função retorna a string "America/New_York", que exibimos usando o comando echo.

A função sempre retorna o identificador canônico com o qual o objeto foi construído. Se você criar o objeto a partir de um offset ou abreviação, o nome retornado refletirá isso:

Nomes para zonas baseadas em offset e abreviação

<?php

echo timezone_name_get(new DateTimeZone('+05:00')), PHP_EOL; // Output: +05:00
echo timezone_name_get(new DateTimeZone('GMT')), PHP_EOL;    // Output: GMT
echo timezone_name_get(new DateTimeZone('UTC')), PHP_EOL;    // Output: UTC

Para zonas nomeadas, o resultado é a mesma string que você pode passar para funções como date_default_timezone_set, tornando-a um identificador seguro para ida e volta.

Exemplos do Mundo Real

Agora que cobrimos os fundamentos da função timezone_name_get, vamos explorar alguns exemplos do mundo real de como ela pode ser usada.

Exemplo 1: Exibindo Fusos Horários em um Menu Dropdown

Suponha que queremos criar um formulário que permita aos usuários selecionar seu fuso horário. Podemos usar a classe DateTimeZone junto com a função timezone_name_get para popular um menu dropdown com todos os fusos horários disponíveis. Veja um exemplo:

Exibindo Fusos Horários em um Menu Dropdown no PHP

<select name="timezone">
  <?php foreach(DateTimeZone::listIdentifiers() as $timezone): ?>
    <option value="<?php echo $timezone; ?>">
      <?php echo $timezone; ?>
    </option>
  <?php endforeach; ?>
</select>

Neste exemplo, usamos o método listIdentifiers da classe DateTimeZone para obter uma lista de todos os fusos horários disponíveis. Como listIdentifiers já retorna os nomes canônicos dos fusos horários, podemos usar $timezone diretamente tanto para o valor quanto para o rótulo, tornando o código mais eficiente.

Exemplo 2: Convertendo uma Data para Outro Fuso Horário

Suponha que temos uma data no Fuso Horário do Pacífico e queremos convertê-la para o Fuso Horário do Leste. Podemos usar a classe DateTime junto com DateTimeZone e a função timezone_name_get para realizar isso. Veja um exemplo:

Convertendo uma Data para Outro Fuso Horário no PHP

Neste exemplo, criamos um objeto DateTime representando uma data e hora no Fuso Horário do Pacífico, usando o identificador de fuso horário America/Los_Angeles. Em seguida, criamos um clone desse objeto e usamos o método setTimezone para convertê-lo para o Fuso Horário do Leste, com o identificador America/New_York. Por fim, exibimos as datas em ambos os fusos horários usando o método format e verificamos os nomes dos fusos horários ativos com timezone_name_get.

Observe que o horário do Leste exibe 12:00:00 em relação ao 09:00:00 do Pacífico — três horas à frente, exatamente como esperado.

Alternativa orientada a objetos

Como timezone_name_get é apenas um wrapper em torno de DateTimeZone::getName, você pode chamar o método diretamente:

Estilo procedural vs. orientado a objetos

<?php

$timezone = new DateTimeZone('Europe/Berlin');

echo timezone_name_get($timezone), PHP_EOL; // Procedural
echo $timezone->getName(), PHP_EOL;          // Object-oriented
// Both output: Europe/Berlin

Ambas as formas retornam a mesma string. O método orientado a objetos se encadeia bem quando você já tem uma instância de DateTimeZone.

Funções relacionadas

• timezone_open — cria um objeto DateTimeZone cujo nome você pode ler posteriormente.
• date_timezone_get — obtém o DateTimeZone associado a um objeto DateTime.
• timezone_offset_get — obtém o offset de uma zona (em segundos) em relação ao UTC para um dado momento.
• timezone_identifiers_list — lista todos os identificadores de fuso horário válidos.

Para uma visão mais ampla, consulte o capítulo PHP Timezones.

Conclusão

Este artigo abordou a função timezone_name_get no PHP, incluindo sua sintaxe, parâmetros, valores de retorno e casos de uso práticos. Ela retorna o identificador canônico armazenado em um objeto DateTimeZone, está disponível sem nenhuma extensão adicional e espelha o método DateTimeZone::getName. Esperamos que esses insights ajudem você a lidar com conversões de fuso horário de forma mais confiável em seus projetos.

Prática