date_sunset()

Einführung

date_sunset() ist eine veraltete PHP-Funktion, die die Uhrzeit des Sonnenuntergangs für ein bestimmtes Datum und einen bestimmten geografischen Standort zurückgibt. Diese Seite erklärt, was sie zurückgegeben hat, wie ihre Parameter funktionierten, warum sie aus modernem PHP entfernt wurde und was stattdessen verwendet werden sollte. Wenn Sie neuen Code schreiben, springen Sie direkt zu Migration zu modernem PHP — das Verständnis der ursprünglichen Signatur ist jedoch weiterhin nützlich, wenn Sie ältere Codebasen pflegen.

Was date_sunset() macht

date_sunset() berechnete den Moment, in dem die Sonne für ein bestimmtes Datum und einen bestimmten Punkt auf der Erde unter den Horizont sank. Dafür benötigte sie vier Informationen:

• Ein Datum, angegeben als Unix-Zeitstempel.
• Breiten- und Längengrad, um die Position des Beobachters zu identifizieren.
• Ein Zenitwinkel — der Winkel, gemessen senkrecht nach unten vom Scheitelpunkt, bei dem die Sonne als „untergegangen" gilt. Der Standardwert von 90.83° ist etwas größer als ein rechter Winkel, da er die atmosphärische Refraktion ausgleicht (die das Sonnenlicht beugt und die Sonne höher erscheinen lässt, als sie tatsächlich ist) sowie den scheinbaren Radius der Sonnenscheibe berücksichtigt.

Standardmäßig gab die Funktion einen string wie "18:12" zurück, aber mit dem richtigen Flag konnte sie das Ergebnis als Unix-Zeitstempel zurückgeben, der sich dann mit date() formatieren oder mit einer anderen Datumsfunktion konvertieren lässt.

Syntax

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

Parameter

• timestamp — Der Unix-Zeitstempel des Tages, für den der Sonnenuntergang berechnet werden soll. Erstellen Sie ihn mit strtotime() oder mktime().
• returnFormat — Eine von drei Konstanten, die den Rückgabetyp steuern:
  • SUNFUNCS_RET_STRING — ein "HH:MM"-string (Standard).
  • SUNFUNCS_RET_DOUBLE — die Zeit als Stunden seit Mitternacht (ein Float, z. B. 18.2).
  • SUNFUNCS_RET_TIMESTAMP — ein Unix-Zeitstempel.
• latitude — Der Breitengrad des Beobachters in Grad (positiv = Nord).
• longitude — Der Längengrad des Beobachters in Grad (positiv = Ost, negativ = West).
• zenith — Der Zenitwinkel der Sonne beim Sonnenuntergang; Standard ist 90.83°.
• utcOffset — Der Versatz von UTC in Stunden; wird ignoriert, wenn returnFormat ein Zeitstempel ist.

Die Funktion gab false zurück für Standorte und Daten, an denen die Sonne nie untergeht oder nie aufgeht (zum Beispiel an den Polen im Sommer oder Winter).

Beispiel (Legacy PHP 7.x)

Das folgende Beispiel läuft auf PHP 7.x oder früher, wo die Funktion noch existiert:

Ausgabe:

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

Da das Ergebnis ein Zeitstempel ist, können Sie es beliebig neu formatieren — date("g:i A", $sunset) würde stattdessen 6:12 PM ausgeben.

Migration zu modernem PHP

date_sunset() existiert nicht mehr, und die in PHP integrierte DateTime-Klasse verarbeitet Zeitzonen und Formatierungen, berechnet jedoch keine Sonnenpositionen. Daher hat eine moderne Anwendung zwei praktische Optionen.

Option 1 — Eine Sonnenaufgangs-/Sonnenuntergangs-API aufrufen

Der einfachste portable Ansatz ist, einen öffentlichen Dienst abzufragen und den zurückgegebenen Zeitstempel zu lesen. Dies funktioniert mit jeder PHP-Version und erfordert keine eigenen Berechnungen:

<?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 — Eine Astronomie-Bibliothek verwenden

Für eine Offline-Berechnung ohne externe Abhängigkeiten installieren Sie ein gepflegtes Composer-Paket, das denselben Sonnenuntergangsalgorithmus portiert (suchen Sie auf Packagist nach "sunrise sunset"; beliebte Optionen sind tienvx/php-sunrise-sunset und andreas-glaser/php-sun-info). Die genauen Klassennamen hängen vom jeweiligen Paket ab, prüfen Sie daher immer dessen README — die allgemeine Struktur ist: einen Rechner mit Breiten- und Längengrad erstellen und dann den Sonnenuntergang für ein bestimmtes Datum abfragen.

Anwendungsfälle für Sonnenuntergangszeiten

Egal ob Sie date_sunset() (Legacy) oder eine der modernen Alternativen verwenden, Sonnenuntergangs­daten kommen in vielen Arten von Anwendungen vor:

1. Wetter-Apps — zeigen den Sonnenuntergang des Tages zusammen mit der Vorhersage für einen Standort an.
2. Fotografie-Apps — leiten die „goldene Stunde" ab, den Zeitraum kurz vor dem Sonnenuntergang, wenn das Licht weich und warm ist, indem eine Stunde von der Sonnenuntergangszeit subtrahiert wird.
3. Veranstaltungs- und Planungs-Apps — markieren Outdoor-Events, die bis zur Dämmerung dauern, oder wechseln das Seitendesign nach Einbruch der Dunkelheit zu einem dunklen Stil.
4. Smart-Home und Beleuchtung — lösen Lichter oder Routinen zur lokalen Sonnenuntergangszeit aus.

Kombinieren Sie die Sonnenuntergangszeit mit date_sunrise(), um das vollständige Tageslichtfenster für einen Standort zu erhalten.

Fazit

date_sunset() war in PHP 7.x eine praktische Einzeilen-Lösung zum Abrufen von Sonnenuntergangszeiten, wurde jedoch in PHP 8.1 entfernt und schlägt auf jeder modernen Laufzeitumgebung fehl. Für neuen Code empfiehlt es sich, eine Sonnenaufgangs-/Sonnenuntergangs-API aufzurufen oder eine gepflegte Astronomie-Bibliothek zu verwenden und das Ergebnis mit der DateTime-Klasse zu formatieren. Die Anwendungsfälle — Wetter, Fotografie, Veranstaltungen, Automatisierung — sind unverändert; nur die Berechnungsquelle wurde aus dem PHP-Kern ausgelagert.

Übungen