Signatur
Beschreibung
DatePeriod ermöglicht es, einen Zeitraum mit einem Startdatum, einem Intervall (DateInterval) und entweder einem Enddatum oder einer Anzahl von Wiederholungen zu definieren. Beim Iterieren über das Objekt liefert es alle Datumspunkte innerhalb dieses Zeitraums im angegebenen Rhythmus zurück.
Typische Anwendungsfälle sind das Generieren von Terminen für Kalenderanwendungen, das Berechnen von Zahlungsintervallen (z. B. monatliche Raten), das Erstellen von Berichtsperioden oder das Erzeugen von Datumslisten für Diagramme und Statistiken.
Seit PHP 8.2 implementiert DatePeriod das IteratorAggregate-Interface und kann daher direkt in foreach-Schleifen verwendet werden. Das Startdatum ist standardmäßig im Ergebnis enthalten; durch das Flag DatePeriod::EXCLUDE_START_DATE kann es ausgeschlossen werden.
Ab PHP 8.3 gibt es ergänzend DatePeriod::createFromISO8601String(), das die Erzeugung über einen ISO-8601-Wiederholungsstring erlaubt.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $start Pflicht | DateTimeInterface|string | Das Startdatum des Zeitraums. Entweder ein DateTimeInterface-Objekt oder (bei der ISO-8601-Variante) ein String im Format R<n>/<start>/<interval>/<end>. |
|
| $interval | DateInterval | Das Intervall zwischen den einzelnen Datumspunkten als DateInterval-Objekt, z. B. new DateInterval('P1M') für monatlich. |
|
| $end | DateTimeInterface|int | Das Enddatum als DateTimeInterface-Objekt oder die Anzahl der Wiederholungen als int. Bei einem Enddatum ist dieses selbst nicht im Ergebnis enthalten. |
|
| $options | int | 0 | Optionales Bitmask-Flag. Aktuell unterstützt wird DatePeriod::EXCLUDE_START_DATE, um das Startdatum aus der Iteration auszuschließen. |
Beispiele
Monatliche Termine für ein Quartal erzeugen
<?php
$start = new DateTime('2024-01-01');
$interval = new DateInterval('P1M'); // 1 Monat
$end = new DateTime('2024-04-01');
$period = new DatePeriod($start, $interval, $end);
foreach ($period as $date) {
echo $date->format('d.m.Y') . PHP_EOL;
}Wöchentliche Wiederholungen mit Startdatum ausschließen
<?php
$start = new DateTimeImmutable('2024-06-01');
$interval = new DateInterval('P1W'); // 1 Woche
$recur = 4; // 4 Wiederholungen
$period = new DatePeriod(
$start,
$interval,
$recur,
DatePeriod::EXCLUDE_START_DATE
);
foreach ($period as $date) {
echo $date->format('d.m.Y') . PHP_EOL;
}Arbeitstage eines Monats zählen (täglich iterieren)
<?php
$start = new DateTimeImmutable('2024-03-01');
$end = new DateTimeImmutable('2024-04-01');
$period = new DatePeriod($start, new DateInterval('P1D'), $end);
$workdays = 0;
foreach ($period as $day) {
if ((int)$day->format('N') < 6) { // 1=Mo … 5=Fr
$workdays++;
}
}
echo "Arbeitstage im März 2024: $workdays";Erzeugung über ISO-8601-String (ab PHP 8.3)
<?php
// R3/2024-09-01T00:00:00Z/P1M = 3 Wiederholungen, monatlich ab 01.09.2024
$period = DatePeriod::createFromISO8601String('R3/2024-09-01T00:00:00Z/P1M');
foreach ($period as $date) {
echo $date->format('d.m.Y') . PHP_EOL;
}// Wichtig · Fallstricke
Enddatum ist exklusiv: Das angegebene Enddatum selbst wird nicht in die Iteration einbezogen. Soll der letzte Tag enthalten sein, muss das Enddatum um einen Tick (z. B. +1 day) nach vorne verschoben werden.
Zeitzonenachtung: Bei der Verwendung von Zeitumstellungen (Sommer-/Winterzeit) können Intervalle in Stunden oder Minuten unerwartete Ergebnisse liefern. Es empfiehlt sich, in solchen Fällen UTC-Objekte zu verwenden oder explizit mit DateTimeZone zu arbeiten.
Unveränderlichkeit: DatePeriod selbst ist nach der Erzeugung nicht mehr veränderbar. Für andere Intervalle muss ein neues Objekt erstellt werden.
Ab PHP 8.2 wurde die Klasse so überarbeitet, dass sie sauber IteratorAggregate implementiert; älterer Code, der getStartDate(), getEndDate() oder getDateInterval() nutzt, funktioniert weiterhin.