cal_to_jd()

PHP cal_to_jd(): Convertir una fecha de calendario a un número de día Juliano

La función cal_to_jd() convierte una fecha de un calendario admitido (Gregoriano, Juliano, Judío o Republicano Francés) a un número de día Juliano — un entero único que identifica un día. Como el resultado es simplemente un número, resulta un denominador común sencillo para comparar fechas, calcular la cantidad de días entre dos fechas o convertir entre sistemas de calendario.

Esta página cubre la firma de la función, un ejemplo funcional, los calendarios admitidos, los errores más comunes y a dónde ir a continuación.

Nota: cal_to_jd() forma parte de la extensión Calendar de PHP. La extensión está incluida con PHP pero debe estar habilitada (se compila por defecto en la mayoría de las versiones). Si la función no está definida, habilita ext-calendar.

¿Qué es un número de día Juliano?

El número de día Juliano (también llamado Julian Day Number, JDN) es un recuento continuo de días que comienza desde el 1 de enero de 4713 a. C. en el calendario Juliano proléptico, definido como día 0. Cada fecha posterior se asigna a un entero positivo mayor, y las fechas anteriores serían negativas.

Este recuento es independiente del calendario: no depende de los meses, los años bisiestos ni del sistema de calendario que use una cultura. Eso lo convierte en la representación "pivote" estándar en astronomía, computación científica y cualquier código que deba interoperar entre distintos calendarios.

No confundas el número de día Juliano (un número de día) con el calendario Juliano (el calendario anterior al Gregoriano). Son conceptos distintos a pesar del nombre similar.

Sintaxis

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

Valor de retorno: el número de día Juliano como un int, o 0 si la fecha no es válida para el calendario elegido.

Ejemplo básico

Convertir el 2 de marzo de 2023 (Gregoriano) a su número de día Juliano:

Observa el orden de los argumentos: es month, day, year, no día-mes-año ni año-mes-día. Confundir este orden es el error más común al usar cal_to_jd().

Elegir la constante de calendario

El primer argumento selecciona a qué calendario pertenecen los valores de month/day/year:

La misma fecha de calendario puede producir distintos números de día Juliano dependiendo de la constante que se pase, por lo que siempre debes hacer coincidir la constante con el calendario del que proviene la 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
?>

Ambas imprimen el mismo número de día Juliano porque la reforma Gregoriana omitió 10 días: el 15 de octubre Gregoriano y el 5 de octubre Juliano son el mismo día físico.

Errores comunes

• Las fechas inválidas devuelven 0, no false. Pasar una fecha inexistente como el 30 de febrero produce 0. Valida la entrada del usuario con checkdate() antes de convertir si necesitas detectar fechas incorrectas.
• El orden de los argumentos es month, day, year. Consulta la nota anterior.
• La extensión debe estar habilitada. La función depende de ext-calendar; un error de "función no definida" significa que no está cargada.

Ida y vuelta con cal_from_jd()

cal_to_jd() tiene una función inversa: cal_from_jd() convierte un número de día Juliano de vuelta a una fecha de calendario. Juntas permiten convertir entre sistemas de calendario usando el número de día Juliano como pivote neutral:

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

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

Funciones relacionadas

• cal_from_jd() — la función inversa: número de día Juliano a una fecha de calendario.
• cal_info() — metadatos (nombres de meses, etc.) sobre un calendario.
• cal_days_in_month() — número de días en un mes determinado.
• gregoriantojd(), juliantojd(), jewishtojd(), frenchtojd() — atajos específicos de cada calendario para la misma conversión.
• Consulta la descripción general de funciones del calendario PHP.

Conclusión

cal_to_jd() reduce cualquier fecha de calendario admitida a un único entero — el número de día Juliano — proporcionando una forma neutral al calendario para comparar fechas, medir intervalos y convertir entre calendarios. Recuerda el orden de argumentos month, day, year, elige la constante de calendario que coincida con tu entrada y usa cal_from_jd() para convertir de vuelta.

Práctica