cal_from_jd()

Função PHP cal_from_jd()

A função cal_from_jd() converte uma Contagem de Dias Julianos (um único inteiro) em uma data no calendário de sua escolha — Gregoriano, Juliano, Judaico ou Republicano Francês. Ela retorna um array associativo contendo o ano, mês, dia e várias strings formatadas úteis (nome do dia, nome do mês, dia da semana).

Esta página explica o que é uma Contagem de Dias Julianos, como funciona cal_from_jd(), cada chave do array que ela retorna e como ela difere das funções de calendário relacionadas no PHP. A extensão calendar deve estar habilitada para que essas funções estejam disponíveis.

Sintaxe

cal_from_jd(int $julian_day, int $calendar): array

• $julian_day — a Contagem de Dias Julianos a converter. É um inteiro; um float é truncado.
• $calendar — qual calendário usar na conversão. Use uma das constantes abaixo.

A função sempre retorna um array — não há valor de retorno de falha para uma entrada inteira válida.

O que é uma Contagem de Dias Julianos?

Uma Contagem de Dias Julianos (JDC) é uma contagem contínua de dias inteiros a partir do meio-dia UTC de 1º de janeiro de 4713 a.C. no calendário Juliano proléptico. Por ser um único inteiro crescente sem meses ou regras de ano bissexto, é ideal como um pivô neutro ao converter entre sistemas de calendário: você converte qualquer data de calendário para uma JDC e, em seguida, converte essa JDC para o calendário de destino.

Astronomia, software e pesquisa histórica utilizam-na exatamente por esse motivo — a aritmética de datas sobre um inteiro simples é fácil e inequívoca.

Não confunda a Contagem de Dias Julianos com o calendário Juliano. A contagem de dias é apenas um número; o calendário Juliano é o calendário mais antigo que o Papa Gregório XIII reformou em outubro de 1582 para criar o calendário Gregoriano que usamos hoje.

O array retornado por cal_from_jd()

Para uma dada Contagem de Dias Julianos, cal_from_jd() retorna um array associativo com as seguintes chaves:

Exemplo básico

Converta uma Contagem de Dias Julianos para uma data Gregoriana e leia os componentes:

<?php
$jd = gregoriantojd(3, 22, 2021); // JDC for March 22, 2021

$date = cal_from_jd($jd, CAL_GREGORIAN);

echo "Date string: " . $date['date'] . "\n";
echo "Year:  " . $date['year'] . "\n";
echo "Month: " . $date['monthname'] . "\n";
echo "Day:   " . $date['day'] . "\n";
echo "Weekday: " . $date['dayname'] . "\n";
?>

Isso imprime:

Date string: 3/22/2021
Year:  2021
Month: March
Day:   22
Weekday: Monday

Inspecionando o array completo

Se você não tiver certeza de quais chaves precisa, exiba o valor de retorno completo:

<?php
$jd = gregoriantojd(12, 25, 2021); // Christmas 2021
print_r(cal_from_jd($jd, CAL_GREGORIAN));
?>

Saída:

Array
(
    [date] => 12/25/2021
    [month] => 12
    [day] => 25
    [year] => 2021
    [dow] => 6
    [abbrevdayname] => Sat
    [dayname] => Saturday
    [abbrevmonth] => Dec
    [monthname] => December
)

Erros comuns

• Inteiro, não um float com .5. Ao contrário da Data Juliana astronômica, cal_from_jd() espera um inteiro de dia inteiro. Passar um float simplesmente trunca a parte fracionária.
• A extensão calendar deve estar carregada. Se você receber "Call to undefined function cal_from_jd()", habilite a extensão calendar na sua instalação do PHP.
• Escolha a constante de calendário correta. O mesmo JDC produz valores diferentes de ano/mês/dia para CAL_GREGORIAN versus CAL_JULIAN; sempre passe a constante que você realmente deseja.

Funções relacionadas

• cal_to_jd() — o inverso: converte uma data de calendário para uma Contagem de Dias Julianos.
• gregoriantojd() — obtém uma Contagem de Dias Julianos a partir de uma data Gregoriana.
• jdtogregorian() — converte uma Contagem de Dias Julianos de volta para uma string de data Gregoriana.
• cal_info() — lista nomes de meses/dias e outros metadados de um calendário.
• jddayofweek() — obtém o dia da semana para uma Contagem de Dias Julianos.

Conclusão

cal_from_jd() transforma uma Contagem de Dias Julianos em um array rico de partes de data para qualquer um dos quatro calendários suportados pelo PHP. Combinada com cal_to_jd() (ou gregoriantojd()), ela permite converter datas entre sistemas de calendário usando um único inteiro — a Contagem de Dias Julianos — como intermediário neutro.

Prática