PHP cal_to_jd(): Converter uma Data de Calendário em Contagem de Dias Julianos

A função cal_to_jd() converte uma data de um calendário suportado (Gregoriano, Juliano, Judaico ou Republicano Francês) em uma Contagem de Dias Julianos — um único inteiro que identifica univocamente um dia. Como o resultado é apenas um número, é um denominador comum conveniente para comparar datas, calcular o número de dias entre duas datas ou converter entre sistemas de calendário.

Esta página aborda a assinatura da função, um exemplo funcional, os calendários suportados, as armadilhas mais comuns e para onde ir a seguir.

Nota: cal_to_jd() faz parte da extensão Calendar do PHP. A extensão é fornecida com o PHP, mas deve ser habilitada (ela é compilada por padrão na maioria das distribuições). Se a função estiver indefinida, habilite ext-calendar.

O que é uma Contagem de Dias Julianos?

A Contagem de Dias Julianos (frequentemente chamada de Número do Dia Juliano, JDN) é uma contagem contínua de dias que começa em 1º de janeiro de 4713 a.C. no calendário Juliano proléptico, definido como dia 0. Cada data posterior mapeia para um inteiro positivo maior, e datas anteriores seriam negativas.

Essa contagem é agnóstica em relação ao calendário: não depende de meses, anos bissextos ou qual sistema de calendário uma cultura usa. Isso a torna a representação "pivô" padrão em astronomia, computação científica e qualquer código que precise interoperar entre diferentes calendários.

Não confunda a Contagem de Dias Julianos (um número de dia) com o calendário Juliano (o calendário pré-gregoriano). Eles são não relacionados apesar do nome semelhante.

Sintaxe

cal_to_jd(int $calendar, int $month, int $day, int $year): int

Valor de retorno: a Contagem de Dias Julianos como um int, ou 0 se a data for inválida para o calendário escolhido.

Exemplo básico

Converter 2 de março de 2023 (Gregoriano) para sua Contagem de Dias Julianos:

Observe a ordem dos argumentos: é month, day, year, não dia-mês-ano ou ano-mês-dia. Confundir essa ordem é o erro mais comum com cal_to_jd().

Escolhendo a constante de calendário

O primeiro argumento seleciona a qual calendário seus valores de month/day/year pertencem:

A mesma data de calendário pode produzir Contagens de Dias Julianos diferentes dependendo da constante que você passa, portanto, sempre corresponda a constante ao calendário de onde veio sua entrada:

<?php
// October 15, 1582 — the day the Gregorian calendar began.
echo cal_to_jd(CAL_GREGORIAN, 10, 15, 1582), "\n"; // 2299161
echo cal_to_jd(CAL_JULIAN,    10, 5,  1582), "\n";  // 2299161
?>

Ambos imprimem a mesma Contagem de Dias Julianos porque a reforma Gregoriana pulou 10 dias: o dia 15 de outubro Gregoriano e o dia 5 de outubro Juliano são o mesmo dia físico.

Armadilhas comuns

• Datas inválidas retornam 0, não false. Passar uma data inexistente como 30 de fevereiro resulta em 0. Valide a entrada do usuário com checkdate() antes de converter, se precisar detectar datas inválidas.
• A ordem dos argumentos é month, day, year. Veja a nota acima.
• A extensão deve estar habilitada. A chamada depende de ext-calendar; um erro de "função indefinida" significa que ela não está carregada.

Viagem de volta com cal_from_jd()

cal_to_jd() tem um inverso: cal_from_jd() converte uma Contagem de Dias Julianos de volta em uma data de calendário. Juntos, permitem converter entre sistemas de calendário usando a Contagem de Dias Julianos como um pivô neutro:

<?php
$jd = cal_to_jd(CAL_GREGORIAN, 3, 2, 2023);

$date = cal_from_jd($jd, CAL_GREGORIAN);
echo $date['date']; // 3/2/2023
?>

Funções relacionadas

• cal_from_jd() — o inverso: Contagem de Dias Julianos para uma data de calendário.
• cal_info() — metadados (nomes dos meses, etc.) sobre um calendário.
• cal_days_in_month() — número de dias em um determinado mês.
• gregoriantojd(), juliantojd(), jewishtojd(), frenchtojd() — atalhos específicos de calendário para a mesma conversão.
• Veja a visão geral completa das funções de calendário PHP.

Conclusão

cal_to_jd() reduz qualquer data de calendário suportada a um único inteiro — a Contagem de Dias Julianos — oferecendo uma forma neutra em relação ao calendário para comparar datas, medir intervalos e converter entre calendários. Lembre-se da ordem dos argumentos month, day, year, escolha a constante de calendário que corresponde à sua entrada e use cal_from_jd() para converter de volta.

Prática