jdmonthname()

Função PHP: cal_jdmonthname()

A função PHP cal_jdmonthname() retorna o nome do mês para um dado número de dia juliano, no sistema de calendário especificado. Esta página abrange o que é um número de dia juliano, a sintaxe da função e suas constantes de modo, exemplos executáveis, o que ela retorna e os pontos de atenção.

Atenção: A URL deste capítulo é historicamente nomeada jdmonthname, mas a função PHP moderna é cal_jdmonthname(). O antigo alias jdmonthname() fazia parte da família jd que o PHP removeu no PHP 8.0 — use cal_jdmonthname() no lugar.

Sintaxe

cal_jdmonthname(int $julian_day, int $mode): string

• $julian_day — um número de dia juliano (um inteiro), normalmente produzido por cal_to_jd() a partir de uma data regular.
• $mode — qual calendário utilizar para ler o nome do mês. Os valores aceitos são:

A função retorna o nome do mês como uma string. Ela depende da extensão calendar, que deve estar habilitada na sua instalação do PHP.

O que é um número de dia juliano?

Antes de nos aprofundarmos em como a função cal_jdmonthname() funciona, é essencial entender o que é um número de dia juliano. Um número de dia juliano é uma contagem contínua de dias que começou ao meio-dia de 1º de janeiro de 4713 a.C. Foi introduzido por Joseph Scaliger em 1583 para facilitar cálculos astronômicos e comparações de datas.

O que a função cal_jdmonthname faz?

A função cal_jdmonthname() recebe dois parâmetros: o número de dia juliano e uma constante de modo (um dos valores CAL_MONTH_* na tabela acima) que seleciona o calendário e se você deseja o nome longo ou abreviado. A função retorna o nome do mês correspondente como uma string.

Um ponto de confusão comum: o primeiro passo (cal_to_jd()) usa constantes de calendário como CAL_GREGORIAN, mas o modo passado para cal_jdmonthname() deve ser uma constante CAL_MONTH_*. Elas não são intercambiáveis.

Veja um exemplo:

Exemplo da função cal_jdmonthname() em PHP

<?php
// Convert today's date to a Julian day count.
$jd = cal_to_jd(CAL_GREGORIAN, (int) date("m"), (int) date("d"), (int) date("Y"));

// Read the long Gregorian month name back from that Julian day.
echo "Today is " . cal_jdmonthname($jd, CAL_MONTH_GREGORIAN_LONG) . ".";
?>

Em um mês como março, isso imprime: Today is March.

Como usar a função cal_jdmonthname?

Para usar a função cal_jdmonthname() no seu código PHP, você precisa seguir estes passos:

1. Determine o número de dia juliano para a data de interesse. Você pode usar a função cal_to_jd() para converter uma data gregoriana em um número de dia juliano.
2. Chame a função cal_jdmonthname(), passando o número de dia juliano e uma constante de modo (por exemplo, CAL_MONTH_GREGORIAN_LONG ou CAL_MONTH_JULIAN_LONG).
3. Use o valor retornado no seu código conforme necessário.

Nota: As funções antigas da extensão jd foram removidas no PHP 8.0. Sempre use as funções cal_* para operações de calendário no PHP moderno.

Exemplo

Veja como você pode obter tanto o nome completo quanto o abreviado para a mesma data, alterando apenas a constante de modo:

Como usar a função cal_jdmonthname() em PHP?

<?php
$jd = cal_to_jd(CAL_GREGORIAN, 3, 1, 2023);   // March 1, 2023

echo "Long:  " . cal_jdmonthname($jd, CAL_MONTH_GREGORIAN_LONG)  . "\n"; // Long:  March
echo "Short: " . cal_jdmonthname($jd, CAL_MONTH_GREGORIAN_SHORT) . "\n"; // Short: Mar
?>

Como a única coisa que mudou é o modo, esta é a forma mais limpa de alternar entre nomes completos (March) e abreviações (Mar), ou entre sistemas de calendário, sem precisar recalcular a data.

Nota sobre o calendário juliano: Passar um modo CAL_MONTH_JULIAN_* lê o mesmo número de dia juliano pelo calendário juliano mais antigo. Como o calendário juliano atualmente está cerca de 13 dias atrás do gregoriano, uma data próxima ao início ou fim de um mês pode resultar em um nome de mês diferente em relação à leitura gregoriana.

Benefícios de usar a função cal_jdmonthname

Usar a função cal_jdmonthname() pode tornar o trabalho com números de dia juliano no PHP muito mais fácil e eficiente. Veja alguns benefícios de usar essa função:

1. Economia de tempo: Em vez de calcular manualmente o nome do mês para um determinado número de dia juliano, você pode simplesmente chamar a função cal_jdmonthname().
2. Consistência: A função garante que você obtenha o nome do mês correto sempre, o que reduz o risco de erros no seu código.
3. Flexibilidade: A função permite especificar o sistema de calendário, o que lhe dá mais controle sobre como seu código exibe informações em diferentes calendários históricos ou regionais.

Pontos de atenção

• Use uma constante CAL_MONTH_*, não uma constante de calendário CAL_*. Passar CAL_GREGORIAN (valor 0) coincidentemente mapeia para CAL_MONTH_GREGORIAN_LONG, mas CAL_JULIAN não fornecerá nomes de meses julianos — use CAL_MONTH_JULIAN_LONG no lugar.
• A extensão calendar deve estar habilitada. Em muitas instalações padrão ela não está. Se você obtiver Call to undefined function cal_jdmonthname(), habilite ext-calendar na sua configuração do PHP.
• Os antigos aliases jd* foram removidos. jdmonthname() e similares foram removidos no PHP 8.0; sempre use as funções cal_* no código moderno.

Funções relacionadas

• cal_to_jd() — converte uma data de calendário em um número de dia juliano (a entrada para esta função).
• cal_from_jd() — converte um número de dia juliano de volta em partes de data, incluindo o número e nome do mês.
• cal_days_in_month() — número de dias em um determinado mês.
• cal_info() — nomes de meses e dias para um calendário inteiro de uma vez.

Conclusão

A função cal_jdmonthname() é uma ferramenta útil para desenvolvedores PHP que trabalham com números de dia juliano: ela transforma um número bruto de dias em um nome de mês legível no sistema de calendário de sua escolha. Use-a junto com cal_to_jd() para a conversão de data, lembre-se de passar um modo CAL_MONTH_* e certifique-se de que a extensão calendar está habilitada.

Practice