date_isodate_set()

Die Funktion date_isodate_set() setzt das Datum eines DateTime-Objekts anhand des ISO-8601-wochenbasierten Kalenders — also über Jahr, Wochennummer und Wochentag statt über Monat und Tag. Sie ist der prozedurale Alias der Methode DateTime::setISODate(), sodass beide genau dasselbe tun.

Diese Seite behandelt die Funktionssyntax, den Unterschied zwischen dem ISO-Wochenkalender und dem gewöhnlichen Kalender, ausführbare Beispiele sowie häufige Fallstricke.

Syntax

Die Funktion date_isodate_set() hat folgende Syntax:

Die Syntax der PHP-Funktion date_isodate_set()

date_isodate_set(DateTime $object, int $year, int $week, int $dayOfWeek = 1): DateTime

wobei:

• $object — das zu ändernde DateTime-Objekt (es wird direkt verändert).
• $year — das ISO-Jahr.
• $week — die ISO-Wochennummer, 1–53.
• $dayOfWeek — der Wochentag, 1 für Montag bis 7 für Sonntag (optional, Standard ist 1).

Die Funktion gibt dasselbe DateTime-Objekt zurück, sodass Aufrufe verkettet werden können. Der äquivalente objektorientierte Aufruf lautet:

$date->setISODate($year, $week, $dayOfWeek);

Warum ISO-Wochendaten verwenden

Anders als der gewöhnliche Kalender nummeriert ISO 8601 jede Woche des Jahres und identifiziert ein Datum durch (Jahr, Woche, Wochentag). Das ist praktisch für Geschäftsberichte, Terminplanung und jedes System, das in Wochen statt in Monaten denkt.

Zwei Regeln sind wichtig:

• Woche 1 ist die Woche, die den ersten Donnerstag des Jahres enthält — gleichbedeutend mit der Woche, die den 4. Januar enthält. Deshalb können die ersten Januartage zum vorherigen ISO-Jahr gehören und die letzten Dezembertage zum nächsten.
• Außerhalb des gültigen Bereichs liegende Werte laufen über, anstatt einen Fehler auszulösen. Wird Woche 53 oder Tag 7 einer nicht existierenden Woche angefragt, rollt das Datum einfach in die nächste Woche oder das nächste Jahr vor. Zum Beispiel landet date_isodate_set($d, 2022, 52, 7) auf 2023-01-01, da die 52. Woche 2022 am Sonntag, dem 1. Januar 2023, endet.

Hinweis: date_isodate_set() ändert nur den Datums-Teil. Die Uhrzeit bleibt so, wie sie das DateTime-Objekt bereits hatte (die aktuelle Zeit bei einem neu erstellten Objekt).

Beispiele

Grundlegende Verwendung

Setzt ein Datum auf den 3. Tag (Mittwoch) der 10. ISO-Woche des Jahres 2023:

Die Funktion ändert $date direkt. Wir beginnen mit einer festen Zeit, damit die Ausgabe bei jedem Durchlauf gleich ist; nur der Datumsteil wird ersetzt.

Wochennummern können die Jahresgrenze überschreiten

Der letzte Tag der letzten Woche 2022 liegt im Januar 2023 — das ist der ISO-Kalender in Aktion, kein Fehler:

Die 52. Woche 2022 endet am Sonntag, dem 1. Januar 2023 — das ist das zurückgegebene Datum.

Objektorientiertes Äquivalent

DateTime::setISODate() erledigt dieselbe Aufgabe und gibt das Objekt zurück, was einen direkten Aufruf von format() als Kette ermöglicht:

Dies setzt das Datum auf den 1. Tag (Montag) der 24. Woche des Jahres 2023.

Verwandte Funktionen

• date_create() — erstellt ein DateTime-Objekt zum Übergeben.
• date_format() — formatiert das resultierende Datum zur Anzeige.

Fazit

date_isodate_set() setzt ein DateTime-Objekt auf ein bestimmtes (Jahr, Woche, Wochentag) mithilfe des ISO-8601-Wochenkalenders. Wichtig zu wissen: ISO-Woche 1 enthält den ersten Donnerstag des Jahres, Wochen- und Tageswerte laufen in die nächste Woche oder das nächste Jahr über statt einen Fehler zu erzeugen, und nur das Datum — nicht die Uhrzeit — wird geändert.

Übung