cal_from_jd()

Función PHP cal_from_jd()

La función cal_from_jd() convierte un Número de Día Juliano (un entero único) en una fecha del calendario de tu elección: gregoriano, juliano, judío o republicano francés. Devuelve un array asociativo que contiene el año, el mes, el día y varias cadenas de texto con formato útil (nombre del día, nombre del mes, día de la semana).

Esta página explica qué es un Número de Día Juliano, cómo funciona cal_from_jd(), cada clave del array que devuelve y cómo se diferencia de las funciones de calendario relacionadas en PHP. La extensión calendar debe estar habilitada para que estas funciones estén disponibles.

Sintaxis

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

• $julian_day — el Número de Día Juliano a convertir. Es un entero; un float se trunca.
• $calendar — el calendario al que se desea convertir. Usa una de las constantes a continuación.

La función siempre devuelve un array; no hay valor de retorno de error para una entrada de entero válida.

¿Qué es un Número de Día Juliano?

Un Número de Día Juliano (JDC) es un recuento continuo de días completos que comienza desde el mediodía UTC del 1 de enero de 4713 a. C. en el calendario juliano proléptico. Al ser un entero creciente sin meses ni reglas de años bisiestos, es ideal como pivote neutro al convertir entre sistemas de calendario: conviertes cualquier fecha de calendario a un JDC y luego conviertes ese JDC al calendario de destino.

La astronomía, el software y la investigación histórica lo utilizan exactamente por esta razón: la aritmética de fechas sobre un entero simple es sencilla e inequívoca.

No confundas el Número de Día Juliano con el calendario juliano. El número de día es solo un número; el calendario juliano es el calendario más antiguo que el Papa Gregorio XIII reformó en octubre de 1582 para crear el calendario gregoriano que usamos hoy.

El array que devuelve cal_from_jd()

Para un Número de Día Juliano dado, cal_from_jd() devuelve un array asociativo con estas claves:

Ejemplo básico

Convierte un Número de Día Juliano a una fecha gregoriana y lee los 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";
?>

Esto imprime:

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

Inspección del array completo

Si no estás seguro de qué claves necesitas, vuelca el valor de retorno completo:

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

Salida:

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

Errores comunes

• Entero, no un float con .5. A diferencia del Día Juliano astronómico, cal_from_jd() espera un entero de día completo. Pasar un float simplemente trunca la parte fraccionaria.
• La extensión calendar debe estar cargada. Si obtienes "Call to undefined function cal_from_jd()", habilita la extensión calendar en tu compilación de PHP.
• Elige la constante de calendario correcta. El mismo JDC produce valores de año/mes/día diferentes para CAL_GREGORIAN frente a CAL_JULIAN; siempre pasa la constante que realmente necesitas.

Funciones relacionadas

• cal_to_jd() — la inversa: convierte una fecha de calendario a un Número de Día Juliano.
• gregoriantojd() — obtiene un Número de Día Juliano a partir de una fecha gregoriana.
• jdtogregorian() — convierte un Número de Día Juliano de nuevo a una cadena de fecha gregoriana.
• cal_info() — lista los nombres de meses y días y otros metadatos de un calendario.
• jddayofweek() — obtiene el día de la semana para un Número de Día Juliano.

Conclusión

cal_from_jd() transforma un Número de Día Juliano en un array completo de partes de fecha para cualquiera de los cuatro calendarios soportados por PHP. Combinada con cal_to_jd() (o gregoriantojd()), permite convertir fechas entre sistemas de calendario usando un único entero — el Número de Día Juliano — como intermediario neutro.

Práctica