Skip to content
Tutorials Center
My learning

Topics

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
<?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

PHP Daily and weekly series

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.

PHP Calendars, filtering and ISO strings

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

PHP
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. R3 means 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 DatePeriod can be looped over more than once.
  • Month stepping has the usual month-end problem: P1M from 31 January goes to 3 March. Generate month ends with modify("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 foreach with an if, or CallbackFilterIterator, to skip weekends or holidays.
  • Inspecting the period with var_dump() shows internal properties that are version-dependent; use the getters.