date_sunset()

Introduzione

date_sunset() è una funzione PHP legacy che restituisce l'orario del tramonto per una data e una posizione geografica specificate. Questa pagina spiega cosa restituiva, come funzionavano i suoi parametri, perché è stata rimossa dal PHP moderno e cosa usare al suo posto. Se stai scrivendo nuovo codice, passa direttamente a Migrazione al PHP moderno — ma comprendere la firma originale è comunque utile quando si mantengono codebase più datate.

Cosa fa date_sunset()

date_sunset() calcolava il momento in cui il sole scendeva sotto l'orizzonte per una data specifica e un punto specifico sulla Terra. Richiedeva quattro informazioni:

• Una data, fornita come timestamp Unix.
• Una latitudine e una longitudine che identificano la posizione dell'osservatore.
• Un angolo zenitale — l'angolo, misurato verso il basso rispetto alla verticale, a cui il sole è considerato "tramontato." Il valore predefinito 90.83° è leggermente superiore a un angolo retto perché compensa la rifrazione atmosferica (che piega la luce solare e fa apparire il sole più in alto di quanto sia realmente) e il raggio apparente del disco solare.

Per impostazione predefinita, la funzione restituiva una string come "18:12", ma con il flag corretto poteva restituire il risultato come timestamp Unix, che si può poi formattare con date() o convertire con qualsiasi altra funzione data.

Sintassi

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

Parametri

• timestamp — Il timestamp Unix del giorno per cui calcolare il tramonto. Costruiscilo con strtotime() o mktime().
• returnFormat — Una delle tre costanti che controllano il tipo restituito:
  • SUNFUNCS_RET_STRING — una string "HH:MM" (predefinita).
  • SUNFUNCS_RET_DOUBLE — l'orario come ore dalla mezzanotte (un float, es. 18.2).
  • SUNFUNCS_RET_TIMESTAMP — un timestamp Unix.
• latitude — La latitudine dell'osservatore in gradi (positivo = nord).
• longitude — La longitudine dell'osservatore in gradi (positivo = est, negativo = ovest).
• zenith — L'angolo zenitale del sole al tramonto; predefinito a 90.83°.
• utcOffset — L'offset dall'UTC in ore; ignorato quando returnFormat è un timestamp.

La funzione restituiva false per le posizioni e le date in cui il sole non tramonta mai o non sorge mai (ad esempio, i poli in estate o in inverno).

Esempio (PHP 7.x legacy)

Il seguente codice funziona su PHP 7.x o precedente, dove la funzione esiste ancora:

Output:

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

Poiché il risultato è un timestamp, puoi riformattarlo come preferisci — date("g:i A", $sunset) stamperebbe 6:12 PM invece.

Migrazione al PHP moderno

date_sunset() non esiste più, e la classe DateTime integrata in PHP gestisce i fusi orari e la formattazione, ma non calcola le posizioni solari. Quindi un'app moderna ha due opzioni pratiche.

Opzione 1 — Chiamare una API sunrise/sunset

L'approccio portatile più semplice è interrogare un servizio pubblico e leggere il timestamp restituito. Funziona su qualsiasi versione di PHP e non richiede calcoli da parte tua:

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

Opzione 2 — Usare una libreria di astronomia

Per un calcolo offline e autonomo, installa un pacchetto Composer mantenuto che implementa lo stesso algoritmo del tramonto (cerca su Packagist "sunrise sunset"; le scelte più popolari includono tienvx/php-sunrise-sunset e andreas-glaser/php-sun-info). I nomi esatti delle classi dipendono dal pacchetto, quindi controlla sempre il suo README — la struttura generale è: costruire un calcolatore a partire da latitudine/longitudine, poi chiedere il tramonto per una data specificata.

Dove vengono utilizzati gli orari del tramonto

Che tu chiami date_sunset() (legacy) o una delle moderne alternative sopra descritte, i dati sul tramonto compaiono in molti tipi di applicazioni:

1. App meteo — mostrano il tramonto della giornata insieme alle previsioni per una posizione.
2. App fotografiche — calcolano la "golden hour," il periodo poco prima del tramonto in cui la luce è morbida e calda, sottraendo un'ora dall'orario del tramonto.
3. App per eventi e pianificazione — segnalano eventi all'aperto che si protraggono fino al crepuscolo, o passano a un tema scuro del sito dopo il tramonto.
4. Smart home e illuminazione — attivano luci o routine all'orario del tramonto locale.

Abbina l'orario del tramonto a date_sunrise() per ottenere la finestra completa di luce diurna per una posizione.

Conclusione

date_sunset() era un modo comodo con una sola chiamata per ottenere gli orari del tramonto in PHP 7.x, ma è stata rimossa in PHP 8.1 e fallirà su qualsiasi runtime moderno. Per il nuovo codice, chiama una API sunrise/sunset oppure usa una libreria di astronomia mantenuta, e formatta il risultato con la classe DateTime. I casi d'uso — meteo, fotografia, eventi, automazione — non sono cambiati; solo la sorgente del calcolo si è spostata fuori dal core di PHP.

Pratica