gregoriantojd()

Introdução

A função PHP gregoriantojd() converte uma data do calendário gregoriano para uma Contagem de Dias Julianos — um único inteiro que representa uma data contando os dias decorridos desde um ponto de partida fixo. Esta página explica o que esses termos significam, apresenta a assinatura da função e seus valores de retorno, percorre um exemplo funcional e fornece links para as funções de calendário inversas e relacionadas.

gregoriantojd() faz parte da extensão Calendar nativa do PHP. Ela não está depreciada, mas a maioria dos projetos modernos só precisa de Contagens de Dias Julianos para astronomia, interoperabilidade com dados científicos ou conversão entre sistemas de calendário. Para aritmética e formatação de datas no dia a dia, prefira a classe DateTime.

História do Calendário Gregoriano

O calendário gregoriano foi introduzido como forma de corrigir os erros do calendário juliano. O calendário juliano baseava-se na ideia de que um ano tinha exatamente 365,25 dias. Porém, isso não era totalmente preciso, e o calendário foi gradualmente perdendo a sincronia com o ano solar. Quando o calendário gregoriano foi introduzido, o calendário juliano estava desatualizado em 10 dias.

O calendário gregoriano resolveu esse problema introduzindo um novo sistema para calcular anos bissextos. No calendário gregoriano, um ano é bissexto se for divisível por 4, mas não por 100, a menos que também seja divisível por 400. Isso significa que anos como 1700, 1800 e 1900 não são bissextos, mas 1600 e 2000 são.

Sintaxe

gregoriantojd(int $month, int $day, int $year): int

A função recebe três argumentos inteiros na ordem mês, dia, ano — observe que o mês vem primeiro, não o dia:

• $month — o mês, de 1 (janeiro) a 12 (dezembro).
• $day — o dia do mês, de 1 a 31.
• $year — o ano. O intervalo válido é de -4714 a 9999. O ano 0 não é válido.

A função retorna a Contagem de Dias Julianos como um inteiro, ou 0 se a data estiver fora do intervalo.

O que é uma Contagem de Dias Julianos?

Uma Contagem de Dias Julianos é uma forma de representar qualquer data do calendário como um único inteiro sempre crescente. A contagem começa ao meio-dia de 1º de janeiro de 4713 a.C. (no calendário juliano proléptico). Como cada data se torna um número, você pode encontrar o número de dias entre duas datas com uma simples subtração, independentemente de meses, anos bissextos ou limites de calendário — o que é exatamente por isso que astrônomos e formatos de dados científicos o utilizam.

Convertendo uma Data Gregoriana

Para converter 14 de fevereiro de 2023 para uma Contagem de Dias Julianos, passe o mês, o dia e o ano:

$jd = gregoriantojd(2, 14, 2023);
echo $jd; // 2459990

A variável $jd agora contém 2459990, a Contagem de Dias Julianos para essa data.

Tratando datas inválidas

Se a data estiver fora do intervalo suportado, gregoriantojd() retorna 0 em vez de lançar um erro. Trate um resultado 0 como "entrada inválida":

$jd = gregoriantojd(13, 40, 2023); // month 13, day 40 — invalid
if ($jd === 0) {
    echo "Invalid date.";
}

Convertendo de volta

Para fazer o caminho inverso — de uma Contagem de Dias Julianos de volta para uma string de data gregoriana — use a função inversa jdtogregorian():

$jd = gregoriantojd(2, 14, 2023);
echo jdtogregorian($jd); // 2/14/2023

Quando Devo Usar Isso?

Use gregoriantojd() quando precisar:

• Contar dias entre duas datas subtraindo suas Contagens de Dias Julianos.
• Converter entre sistemas de calendário (por exemplo, de gregoriano para datas julianas ou judaicas) usando as outras funções Calendar do PHP.
• Encontrar o dia da semana de uma data com jddayofweek().

Para trabalhos comuns de aplicação — analisar entrada do usuário, formatar saída, adicionar intervalos — prefira a classe DateTime, que é sensível ao fuso horário e muito mais conveniente.

Conclusão

gregoriantojd() converte uma data gregoriana em um único inteiro de Contagem de Dias Julianos, tornando a aritmética de datas e a conversão entre calendários simples. Lembre-se da ordem dos argumentos com o mês primeiro, verifique se há retorno 0 em entradas inválidas e combine com jdtogregorian() para converter de volta. Para manipulação geral de datas, a classe DateTime continua sendo a ferramenta certa.

Prática