PHP Reference ยท Date and Time
The DatePeriod class
Reference for the PHP DatePeriod class: iterate dates between a start and end at a fixed interval, with recurrences, EXCLUDE_START_DATE and ISO 8601 strings.
DatePeriod produces a series of dates. Give it a start date, an interval and an end date (or a number of repetitions), and it can be used directly in a foreach loop. It is the cleanest way to build calendars, daily reports, subscription schedules and "every second Tuesday" lists.
It is an iterator: dates are created one at a time as you loop. Each element is a DateTimeImmutable if you started from an immutable date, or a DateTime object if you started from a mutable one. The end date is exclusive unless you ask otherwise.
<?php $p = new DatePeriod(new DateTime("2025-01-01"), new DateInterval("P1D"), 2); foreach ($p as $day) { echo $day->format("m-d "); // 01-01 01-02 01-03 }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.
Syntax
new DatePeriod(DateTimeInterface $start, DateInterval $interval, int $recurrences, int $options = 0) new DatePeriod(DateTimeInterface $start, DateInterval $interval, DateTimeInterface $end, int $options = 0) DatePeriod::createFromISO8601String(string $specification, ?int $options = null): static // PHP 8.3 $period->getStartDate(): DateTimeInterface $period->getEndDate(): ?DateTimeInterface $period->getDateInterval(): DateInterval $period->getRecurrences(): ?int
| Name | Description |
|---|---|
$start |
The first date of the series. Its class (DateTime or DateTimeImmutable) decides the class of each item. |
$interval |
Step between dates. |
$recurrences |
Number of repetitions after the start date. A period with 3 recurrences yields 4 dates (3 if EXCLUDE_START_DATE). |
$end |
Exclusive end date; the series stops before reaching it. |
$options |
DatePeriod::EXCLUDE_START_DATE, and DatePeriod::INCLUDE_END_DATE (PHP 8.2 and later). |
$specification |
An ISO 8601 repeating interval such as R5/2025-01-01T00:00:00Z/P1D. |
Return value: an object that implements IteratorAggregate; iterating yields date objects. Use iterator_to_array() to get an array.
Usage notes
- Exclusive end. To include the last day use
DatePeriod::INCLUDE_END_DATE(PHP 8.2+) or add a day to the end. - Recurrences count repeats, not items.
R3means the start plus three more. - Every item is a fresh object, so it is safe to modify or store it.
- Lazy. The loop does not allocate the whole series, which keeps long ranges cheap.
- Reusable. A
DatePeriodcan be looped over more than once. - Month stepping has the usual month-end problem:
P1Mfrom 31 January goes to 3 March. Generate month ends withmodify("last day of next month"). - Time zones. The time zone of the start date is used; daylight saving shifts are handled for named zones.
- Filtering: use
foreachwith anif, orCallbackFilterIterator, to skip weekends or holidays. - Inspecting the period with
var_dump()shows internal properties that are version-dependent; use the getters.