PHP date_sunset(): Sonnenuntergang selbst berechnen

Eine Außenbeleuchtung soll abends anspringen, wenn es dämmert. Eine feste Uhrzeit passt im Juni und im Dezember gleichermaßen schlecht, und eine bezahlte Wetter-API für eine rein astronomische Rechnung ist Verschwendung. PHP kann das selbst.

Im Bild sinkt die Sonne unter den Horizont, darüber liegen die drei Dämmerungsbänder. Alle vier Zeitpunkte lassen sich aus Koordinaten und Datum berechnen.

Was PHP date_sunset() liefert

PHP date_sunset() berechnet den Zeitpunkt des Sonnenuntergangs für einen Ort und einen Tag. Nötig sind ein Zeitstempel, Breiten- und Längengrad. Das Ergebnis kommt je nach zweitem Parameter als Zeichenkette, als Fließkommazahl in Stunden oder als Unix-Zeitstempel.

<?php

date_default_timezone_set('Europe/Berlin');



$zeitpunkt = date_sunset(

    time(),

    SUNFUNCS_RET_STRING,

    52.520008,   /* Breitengrad Berlin */

    13.404954    /* Laengengrad Berlin */

);



echo $zeitpunkt; // z.B. 20:41

Der Aufruf funktioniert, hat aber einen Haken, der weiter unten ausführlich behandelt wird: die Funktion gilt seit PHP 8.1 als veraltet. Wer heute neu baut, sollte den Nachfolger nehmen, und wer bestehenden Code pflegt, sollte wissen, was der Umbau kostet.

Die Signatur im Original

Sechs Parameter sind viel für eine Funktion, und ihre Reihenfolge ist nicht selbsterklärend. Deshalb hier die Beschreibung im Original:

date_sunset(int $timestamp, int $returnFormat = SUNFUNCS_RET_STRING,

            ?float $latitude = null, ?float $longitude = null,

            ?float $zenith = null, ?float $utcOffset = null): string|int|float|false



/* timestamp    - the day to calculate the sunset time for

   returnFormat - one of the SUNFUNCS_RET_* constants: a string, a

                  double float value, or a unix timestamp

   latitude     - degrees north of the equator, negative for south

   longitude    - degrees east of gmt, negative for west

   zenith       - the sun zenith angle, 90.83 by default

   utcOffset    - offset in hours, only used with RET_STRING

   return       - returns the sunset time in the chosen format,

                  or false on failure



   The function is deprecated since PHP 8.1. date_sun_info() returns

   the same information as an array and replaces it. */

Der Hinweis am Ende ist der wichtigste der Liste und wird weiter unten ausführlich behandelt.

Warum PHP date_sunset() als veraltet gilt

Mit PHP 8.1 wurden date_sunset() und date_sunrise() als deprecated markiert. Das heißt: Sie arbeiten weiterhin und liefern korrekte Werte, schreiben aber bei jedem Aufruf eine Meldung ins Fehlerprotokoll. Entfernt werden sie frühestens mit einer Hauptversion.

Der Grund ist nicht ein Rechenfehler, sondern die unübersichtliche Signatur mit sechs Parametern, von denen vier optional sind, sowie die Tatsache, dass für Sonnenaufgang und -untergang zwei getrennte Aufrufe nötig sind. Der Nachfolger löst beides in einem Zug.

Der Ersatz: date_sun_info()

date_sun_info() nimmt drei Parameter und gibt ein Array mit neun Zeitpunkten zurück. Alle Werte sind Unix-Zeitstempel, also frei von Formatierungs- und Zeitzonenfragen.

<?php

$info = date_sun_info(time(), 52.520008, 13.404954);



print_r(array_keys($info));

/* Array (

     [0] => sunrise

     [1] => sunset

     [2] => transit

     [3] => civil_twilight_begin

     [4] => civil_twilight_end

     [5] => nautical_twilight_begin

     [6] => nautical_twilight_end

     [7] => astronomical_twilight_begin

     [8] => astronomical_twilight_end

   ) */

Der Umbau selbst ist klein. Aus einem Aufruf von PHP date_sunset() mit vier Parametern wird ein Aufruf mit drei Parametern und ein Zugriff auf einen Schlüssel.

<?php

/* vorher */

$alt = date_sunset(time(), SUNFUNCS_RET_TIMESTAMP, 52.52, 13.40);



/* nachher */

$neu = date_sun_info(time(), 52.52, 13.40)['sunset'];



var_dump($alt === $neu); // bool(true)

Zeitzone und Formatierung richtig setzen

Der häufigste Fehler bei PHP date_sunset() hat nichts mit der Astronomie zu tun. Der zurückgegebene Zeitstempel ist zeitzonenfrei, er beschreibt einen Moment. Erst die Ausgabe entscheidet, in welcher Ortszeit dieser Moment erscheint. Wer eigenhändig Stunden addiert, liegt spätestens bei der Sommerzeit daneben.

<?php

$info = date_sun_info(time(), 52.520008, 13.404954);



$untergang = (new DateTimeImmutable('@' . $info['sunset']))

    ->setTimezone(new DateTimeZone('Europe/Berlin'));



echo $untergang->format('d.m.Y H:i');  /* 10.08.2026 20:41 */



/* dieselbe Sekunde in einer anderen Zone */

echo $untergang->setTimezone(new DateTimeZone('UTC'))->format('H:i'); // 18:41

Wie sich Zeitpunkte als Objekt erzeugen und formatieren lassen, zeigt das Tutorial zu PHP date_create() und DateTime-Objekten. Das kleine @ vor dem Zeitstempel ist wichtig. Ohne dieses Zeichen versucht DateTimeImmutable, die Zahl als Datumsangabe zu lesen, und scheitert. Wer mit Datumsrechnung wenig zu tun hatte, findet im Tutorial zur Kalenderwoche in PHP mit Start- und Enddatum den passenden Einstieg in die Objektform.

Der Zenit-Parameter und die Dämmerungsstufen

Bei PHP date_sunset() steuert der fünfte Parameter, welcher Sonnenstand als "Untergang" gilt. Gemessen wird der Winkel zwischen Zenit und Sonnenmittelpunkt, größere Werte bedeuten also eine tiefer stehende Sonne.

Der Vorteil des Nachfolgers wird hier besonders deutlich: Wer bei PHP date_sunset() alle vier Zeitpunkte braucht, ruft die Funktion viermal mit unterschiedlichem Zenit auf. date_sun_info() liefert sie in einem Durchgang.

<?php

$info = date_sun_info(time(), 52.520008, 13.404954);

$zone = new DateTimeZone('Europe/Berlin');



$stufen = [

    'Sonnenuntergang'         => 'sunset',

    'buergerliche Daemmerung' => 'civil_twilight_end',

    'nautische Daemmerung'    => 'nautical_twilight_end',

    'astronomische Daemmerung'=> 'astronomical_twilight_end',

];



foreach ($stufen as $name => $schluessel) {

    $wert = $info[$schluessel];

    if (!is_int($wert)) {

        echo "$name: tritt heute nicht ein\n";

        continue;

    }

    $zeit = (new DateTimeImmutable('@' . $wert))->setTimezone($zone);

    printf("%-26s %s\n", $name, $zeit->format('H:i'));

}

Koordinaten und Tageslänge

Breiten- und Längengrad findet man in jeder Kartenanwendung. Für die ersten Versuche genügt diese kleine Liste.

Aus Aufgang und Untergang ergibt sich die Tageslänge als reine Differenz. Formatiert wird sie mit gmdate(), nicht mit date(), denn es geht um eine Dauer und nicht um eine Uhrzeit. date() würde die Zeitzone daraufrechnen und zwei Stunden zu viel anzeigen.

<?php

$info = date_sun_info(mktime(12, 0, 0, 6, 21, 2026), 48.1351, 11.5820);



$sekunden = $info['sunset'] - $info['sunrise'];

echo gmdate('H:i', $sekunden); /* 16:04 am laengsten Tag */

Polartag und Polarnacht abfangen

Nicht überall geht die Sonne jeden Tag auf und unter. Nördlich des Polarkreises liefert das Array statt eines Zeitstempels einen Wahrheitswert: true bedeutet, die Sonne bleibt über dem Horizont, false bedeutet, sie kommt gar nicht erst herauf. Eine ungeprüfte Formatierung bricht an dieser Stelle.

<?php

/* Tromsoe im Juni */

$info = date_sun_info(mktime(12, 0, 0, 6, 21, 2026), 69.6492, 18.9553);



var_dump($info['sunset']); /* bool(true), Mitternachtssonne */



if (is_bool($info['sunset'])) {

    echo $info['sunset']

        ? 'Die Sonne geht heute nicht unter'

        : 'Die Sonne geht heute nicht auf';

} else {

    echo date('H:i', $info['sunset']);

}

Die Prüfung mit is_bool() oder is_int() gehört in jede Anwendung, die nicht nur mitteleuropäische Orte kennt. Sie kostet zwei Zeilen und verhindert eine Ausgabe, die bei true sonst kommentarlos "01:00" anzeigen würde.

Der folgende Ablauf zeigt den Weg vom Ort bis zur ausgegebenen Uhrzeit mit dieser Weiche.

flowchart TD
  A[Koordinaten und Datum] --> B[date_sun_info]
  B --> C{Wert ist Zeitstempel}
  C -->|nein| D[Polartag oder Polarnacht]
  C -->|ja| E[DateTimeImmutable]
  E --> F[setTimezone Europe Berlin]
  F --> G[format H:i]

Erst nach dieser Weiche darf formatiert werden, vorher nicht.

Wie genau ist die Rechnung?

Ein Vergleich der Ausgabe von PHP date_sunset() mit einem Ortskalender zeigt oft Abweichungen von wenigen Minuten. Das ist kein Fehler. Die Formel rechnet für eine Kugel auf Meereshöhe und berücksichtigt die Lichtbrechung in der Atmosphäre über den Standardzenit von 90,833 Grad. Nicht berücksichtigt sind die Höhenlage des Beobachters und Berge oder Gebäude am Horizont. Für eine Beleuchtungssteuerung, einen Kalender oder eine Wetterrubrik ist das mehr als genau genug.

<?php

/* Schaltzeit mit 20 Minuten Vorlauf, taeglich per Cronjob */

$info = date_sun_info(time(), 52.520008, 13.404954);



if (is_int($info['sunset'])) {

    $schalten = (new DateTimeImmutable('@' . $info['sunset']))

        ->setTimezone(new DateTimeZone('Europe/Berlin'))

        ->modify('-20 minutes');



    file_put_contents('/var/lib/licht/naechste-schaltzeit', $schalten->format('H:i'));

}

Fazit

PHP date_sunset() rechnet korrekt, ist aber seit PHP 8.1 nicht mehr die erste Wahl. date_sun_info() liefert dieselbe Zahl, dazu den Sonnenaufgang und alle drei Dämmerungsstufen, und der Umbau besteht aus einer Zeile.

Drei Dinge entscheiden darüber, ob die Ausgabe stimmt: Der Rückgabewert ist ein Zeitstempel und wird über DateTimeZone in Ortszeit gebracht, Dauern werden mit gmdate() formatiert, und nördlich des Polarkreises kommt statt einer Zahl ein Wahrheitswert zurück. Wer diese drei Punkte beachtet, braucht für Sonnenzeiten keinen externen Dienst mehr.