date_sunset()

Introduction

date_sunset() est une fonction PHP héritée qui retourne l'heure du coucher du soleil pour une date et un emplacement géographique donnés. Cette page explique ce qu'elle retournait, comment ses paramètres fonctionnaient, pourquoi elle a été supprimée de PHP moderne, et par quoi la remplacer. Si vous écrivez du nouveau code, rendez-vous directement à Migration vers PHP moderne — mais comprendre la signature originale reste utile lors de la maintenance d'anciennes bases de code.

Ce que fait date_sunset()

date_sunset() calculait le moment où le soleil passait sous l'horizon pour une date et un point précis sur Terre. Elle nécessitait quatre informations :

• Une date, fournie sous forme de timestamp Unix.
• Une latitude et une longitude identifiant la position de l'observateur.
• Un angle zénithal — l'angle, mesuré depuis le zénith, auquel le soleil est considéré comme « couché ». La valeur par défaut 90.83° est légèrement supérieure à un angle droit car elle compense la réfraction atmosphérique (qui courbe la lumière solaire et fait paraître le soleil plus haut qu'il ne l'est réellement) ainsi que le rayon apparent du disque solaire.

Par défaut, la fonction retournait une string comme "18:12", mais avec le bon indicateur, elle pouvait retourner le résultat sous forme de timestamp Unix, que vous pouvez ensuite formater avec date() ou convertir avec toute autre fonction de date.

Syntaxe

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

Paramètres

• timestamp — Le timestamp Unix du jour pour lequel calculer le coucher du soleil. Construisez-le avec strtotime() ou mktime().
• returnFormat — L'une des trois constantes qui contrôlent le type de retour :
  • SUNFUNCS_RET_STRING — une string "HH:MM" (valeur par défaut).
  • SUNFUNCS_RET_DOUBLE — l'heure exprimée en heures depuis minuit (un float, par ex. 18.2).
  • SUNFUNCS_RET_TIMESTAMP — un timestamp Unix.
• latitude — La latitude de l'observateur en degrés (positif = nord).
• longitude — La longitude de l'observateur en degrés (positif = est, négatif = ouest).
• zenith — L'angle zénithal du soleil au coucher ; valeur par défaut 90.83°.
• utcOffset — Le décalage par rapport à UTC en heures ; ignoré lorsque returnFormat est un timestamp.

La fonction retournait false pour les localisations et les dates où le soleil ne se couche jamais ou ne se lève jamais (par exemple, les pôles en été ou en hiver).

Exemple (PHP 7.x legacy)

Le code suivant fonctionne sur PHP 7.x ou antérieur, où la fonction existe encore :

Résultat :

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

Comme le résultat est un timestamp, vous pouvez le reformater comme bon vous semble — date("g:i A", $sunset) afficherait 6:12 PM à la place.

Migration vers PHP moderne

date_sunset() n'existe plus, et la classe intégrée PHP DateTime gère les fuseaux horaires et le formatage, mais ne calcule pas les positions du soleil. Ainsi, une application moderne dispose de deux options pratiques.

Option 1 — Appeler une API lever/coucher du soleil

L'approche portable la plus simple consiste à interroger un service public et à lire le timestamp qu'il retourne. Cela fonctionne avec n'importe quelle version PHP et ne nécessite aucun calcul de votre côté :

<?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');
?>

Option 2 — Utiliser une bibliothèque d'astronomie

Pour un calcul hors ligne et autonome, installez un package Composer maintenu qui implémente le même algorithme de coucher du soleil (recherchez « sunrise sunset » sur Packagist ; les choix populaires incluent tienvx/php-sunrise-sunset et andreas-glaser/php-sun-info). Les noms de classes exacts dépendent du package, donc consultez toujours son README — la forme générale est : construire un calculateur à partir d'une latitude/longitude, puis lui demander le coucher du soleil pour une date donnée.

Où les heures de coucher du soleil sont utilisées

Que vous appeliez date_sunset() (legacy) ou l'une des alternatives modernes ci-dessus, les données de coucher du soleil apparaissent dans de nombreux types d'applications :

1. Applications météo — affichent le coucher du soleil du jour aux côtés des prévisions pour un emplacement.
2. Applications photo — calculent l'« heure dorée », la période juste avant le coucher du soleil où la lumière est douce et chaude, en soustrayant une heure de l'heure du coucher.
3. Applications d'événements et de planification — signalent les événements en plein air qui se prolongent jusqu'au crépuscule, ou basculent un site vers un style sombre après la nuit tombée.
4. Maison connectée et éclairage — déclenchent des lumières ou des routines à l'heure locale du coucher du soleil.

Associez l'heure du coucher du soleil à date_sunrise() pour obtenir la fenêtre de lumière du jour complète pour un emplacement.

Conclusion

date_sunset() était un moyen pratique en un seul appel d'obtenir les heures de coucher du soleil en PHP 7.x, mais elle a été supprimée en PHP 8.1 et échouera sur tout environnement PHP moderne. Pour le nouveau code, appelez une API lever/coucher du soleil ou utilisez une bibliothèque d'astronomie maintenue, et formatez le résultat avec la classe DateTime. Les cas d'usage — météo, photographie, événements, automatisation — restent inchangés ; seule la source de calcul a été déplacée hors du noyau PHP.

Pratique