timezone_name_from_abbr()

Introdução

Neste artigo, abordaremos a sintaxe, os parâmetros e o valor de retorno da função PHP timezone_name_from_abbr(), além de exemplos práticos de uso.

Entendendo a função PHP timezone_name_from_abbr()

A função timezone_name_from_abbr() em PHP retorna o nome completo do fuso horário IANA (como America/New_York) que corresponde a uma determinada abreviação (como EST). Ela retorna o nome do fuso horário em caso de sucesso ou false em caso de falha.

Esta é a operação inversa de buscar uma abreviação para uma zona conhecida. Um caso de uso comum é analisar uma string de data onde apenas a abreviação está disponível (por exemplo, uma linha de log contendo EST) e você precisa de um identificador de zona canônico para construir um DateTimeZone.

Nota: Esta função é notoriamente não confiável porque muitas abreviações de fuso horário são ambíguas ou não padronizadas — EST, IST e CST mapeiam para várias regiões ao redor do mundo. O manual do PHP recomenda usar DateTimeZone para aplicações em produção. Ao usar timezone_name_from_abbr(), sempre forneça o parâmetro $gmtOffset para que o PHP possa desambiguar entre zonas que compartilham uma abreviação.

Sintaxe

A sintaxe da função timezone_name_from_abbr() é a seguinte:

Sintaxe da função PHP timezone_name_from_abbr()

<?php

string|false timezone_name_from_abbr(string $abbr, int $gmtOffset = -1, int $isdst = -1)

Parâmetros

A função aceita três parâmetros:

• $abbr - O nome abreviado do fuso horário (por exemplo, EST ou CEST). Não diferencia maiúsculas de minúsculas.
• $gmtOffset - O deslocamento GMT do fuso horário em segundos (não em horas). Este parâmetro é opcional, mas altamente recomendado. Se não fornecido (-1), o PHP tenta adivinhar com base apenas em $abbr, o que pode retornar false ou um fuso horário incorreto devido a abreviações ambíguas.
• $isdst - Um sinalizador que indica se o horário de verão está em vigor: 1 para horário de verão, 0 para horário padrão, -1 (o padrão) para ignorar. Quando definido, apenas as zonas que correspondem a esse estado de horário de verão são consideradas.

Uma maneira prática de calcular o deslocamento em segundos é horas × 3600 — por exemplo, UTC−5 é -5 * 3600 = -18000.

Valor de Retorno

A função timezone_name_from_abbr() retorna o nome do fuso horário (uma string como America/New_York) em caso de sucesso, ou false em caso de falha quando nenhuma zona corresponde à abreviação e ao deslocamento fornecidos.

Exemplos

Vejamos alguns exemplos práticos de como a função timezone_name_from_abbr() pode ser usada em PHP.

Exemplo de uso da função timezone_name_from_abbr() em PHP

Nos exemplos acima, estamos passando os nomes abreviados de fuso horário EST e PST junto com seus respectivos deslocamentos GMT em segundos. A função retorna os nomes completos de fuso horário correspondentes, America/New_York e America/Los_Angeles, respectivamente. Sempre verifique se o retorno é false para lidar com casos em que a abreviação não é reconhecida.

O resultado pode então ser passado diretamente para um DateTimeZone para realizar cálculos reais com datas:

<?php

$name = timezone_name_from_abbr('CET', 3600);     // "Europe/Berlin"
$date = new DateTime('2024-01-15 12:00', new DateTimeZone($name));
echo $date->format('Y-m-d H:i T'); // outputs "2024-01-15 12:00 CET"

Funções relacionadas

• timezone_abbreviations_list() - lista todas as abreviações que o PHP conhece, com deslocamentos e nomes de zonas.
• timezone_identifiers_list() - retorna todos os identificadores de fuso horário IANA válidos.
• date_default_timezone_set() - define o fuso horário padrão para todas as funções de data/hora.

Conclusão

Abordamos a sintaxe e o uso da função PHP timezone_name_from_abbr(). Esta função pode converter nomes abreviados de fuso horário em seus identificadores completos, porém, como as abreviações são ambíguas, você deve sempre fornecer $gmtOffset e preferir DateTimeZone para aplicações robustas. Esperamos que este artigo tenha sido útil.

Prática