date_sunset()

Introducción

date_sunset() es una función PHP heredada que devuelve la hora de la puesta de sol para una fecha y ubicación geográfica determinadas. Esta página explica qué devolvía, cómo funcionaban sus parámetros, por qué fue eliminada del PHP moderno y qué usar en su lugar. Si estás escribiendo código nuevo, salta a Migración a PHP moderno — pero entender la firma original sigue siendo útil al mantener bases de código más antiguas.

Qué hace date_sunset()

date_sunset() calculaba el momento en que el sol se ocultaba bajo el horizonte para una fecha específica y un punto concreto de la Tierra. Necesitaba cuatro datos:

• Una fecha, suministrada como un timestamp Unix.
• Una latitud y longitud que identifican la posición del observador.
• Un ángulo cenital — el ángulo, medido hacia abajo desde la vertical, en el que se considera que el sol ha "puesto". El valor predeterminado 90.83° es ligeramente mayor que un ángulo recto porque compensa la refracción atmosférica (que dobla la luz solar y hace que el sol parezca más alto de lo que realmente está) y el radio aparente del disco solar.

Por defecto la función devolvía un string como "18:12", pero con el indicador correcto podía devolver el resultado como un timestamp Unix, que luego puedes formatear con date() o convertir con cualquier otra función de fecha.

Sintaxis

date_sunset(
    int $timestamp,
    int $returnFormat = SUNFUNCS_RET_STRING,
    float $latitude = ini_get("date.default_latitude"),
    float $longitude = ini_get("date.default_longitude"),
    float $zenith = ini_get("date.sunset_zenith"),
    float $utcOffset = 0
): mixed

Parámetros

• timestamp — El timestamp Unix del día para el que calcular la puesta de sol. Constrúyelo con strtotime() o mktime().
• returnFormat — Una de tres constantes que controlan el tipo de retorno:
  • SUNFUNCS_RET_STRING — un string "HH:MM" (el predeterminado).
  • SUNFUNCS_RET_DOUBLE — la hora como horas desde medianoche (un float, p. ej. 18.2).
  • SUNFUNCS_RET_TIMESTAMP — un timestamp Unix.
• latitude — La latitud del observador en grados (positivo = norte).
• longitude — La longitud del observador en grados (positivo = este, negativo = oeste).
• zenith — El ángulo cenital del sol en la puesta de sol; por defecto 90.83°.
• utcOffset — El desplazamiento desde UTC en horas; se ignora cuando returnFormat es un timestamp.

La función devolvía false en ubicaciones y fechas donde el sol nunca se pone o nunca sale (por ejemplo, los polos en verano o invierno).

Ejemplo (PHP 7.x heredado)

Lo siguiente se ejecuta en PHP 7.x o anterior, donde la función todavía existe:

Salida:

Sunset on March 3, 2023 in San Francisco was at 18:12

Como el resultado es un timestamp, puedes reformatearlo de la manera que quieras — date("g:i A", $sunset) imprimiría 6:12 PM en su lugar.

Migración a PHP moderno

date_sunset() ya no existe, y la clase DateTime integrada de PHP maneja zonas horarias y formato pero no calcula posiciones solares. Por ello, una aplicación moderna tiene dos opciones prácticas.

Opción 1 — Llamar a una API de amanecer/atardecer

El enfoque portátil más sencillo es consultar un servicio público y leer el timestamp que devuelve. Esto funciona en cualquier versión de PHP y no requiere cálculos de tu parte:

<?php
// Free, no-key API: https://sunrise-sunset.org/api
$lat = 37.7749;
$lng = -122.4194;
$date = '2023-03-03';

$url = "https://api.sunrise-sunset.org/json?lat={$lat}&lng={$lng}&date={$date}&formatted=0";
$response = json_decode(file_get_contents($url), true);

// The API returns ISO-8601 UTC strings
$sunsetUtc = new DateTime($response['results']['sunset']);
$sunsetUtc->setTimezone(new DateTimeZone('America/Los_Angeles'));

echo "Sunset: " . $sunsetUtc->format('H:i');
?>

Opción 2 — Usar una biblioteca de astronomía

Para un cálculo sin conexión y autónomo, instala un paquete Composer mantenido que porte el mismo algoritmo de puesta de sol (busca en Packagist "sunrise sunset"; las opciones populares incluyen tienvx/php-sunrise-sunset y andreas-glaser/php-sun-info). Los nombres exactos de las clases dependen del paquete, así que revisa siempre su README — la forma general es: construir una calculadora a partir de una latitud/longitud y luego pedirle la puesta de sol de una fecha determinada.

Dónde se usan los horarios de puesta de sol

Ya sea que llames a date_sunset() (heredado) o a una de las alternativas modernas anteriores, los datos de puesta de sol aparecen en muchos tipos de aplicaciones:

1. Aplicaciones meteorológicas — muestran la puesta de sol del día junto al pronóstico para una ubicación.
2. Aplicaciones de fotografía — calculan la "hora dorada", el período justo antes de la puesta de sol en que la luz es suave y cálida, restando una hora del tiempo de puesta de sol.
3. Aplicaciones de eventos y programación — marcan eventos al aire libre que se prolongan hasta el anochecer, o cambian un sitio a estilo oscuro después de oscurecer.
4. Hogar inteligente e iluminación — activan luces o rutinas a la hora local de puesta de sol.

Combina la hora de puesta de sol con date_sunrise() para obtener la ventana completa de luz diurna para una ubicación.

Conclusión

date_sunset() era una forma conveniente de obtener los horarios de puesta de sol con una sola llamada en PHP 7.x, pero fue eliminada en PHP 8.1 y fallará en cualquier entorno de ejecución moderno. Para código nuevo, llama a una API de amanecer/atardecer o usa una biblioteca de astronomía mantenida, y formatea el resultado con la clase DateTime. Los casos de uso — meteorología, fotografía, eventos, automatización — no han cambiado; solo la fuente de cálculo ha salido del núcleo de PHP.

Práctica