# The DatePeriod class

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## Introduction

Represents a date period.

A date period allows iteration over a set of dates and times, recurring at regular intervals, over a given period.

## Class synopsis

class DatePeriod implements IteratorAggregate {
/* Constants */
public const int EXCLUDE_START_DATE;
public const int INCLUDE_END_DATE;
/* Properties */
public readonly ?DateTimeInterface $start;
public readonly ?DateTimeInterface $current;
public readonly ?DateTimeInterface $end;
public readonly ?DateInterval $interval;
public readonly int $recurrences;
public readonly bool $include_start_date;
public readonly bool $include_end_date;
/* Methods */
public __construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
int `$recurrences`,
int `$options` = 0
)
public __construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
DateTimeInterface `$end`,
int `$options` = 0
)
public __construct(string `$isostr`, int `$options` = 0)
public static createFromISO8601String(string `$specification`, int `$options` = 0): static
public getDateInterval(): DateInterval
public getEndDate(): ?DateTimeInterface
public getRecurrences(): ?int
public getStartDate(): DateTimeInterface
}

## Predefined Constants

`DatePeriod::EXCLUDE_START_DATE` int

  Exclude start date, used in DatePeriod::__construct().

`DatePeriod::INCLUDE_END_DATE` int

  Include end date, used in DatePeriod::__construct().

## Properties

recurrences

  The minimum amount of instances as retured by the iterator.

  If the number of recurrences has been explicitly passed through the recurrences parameter in the constructor of the DatePeriod instance, then this property contains this value, plus one if the start date has not been disabled through `DatePeriod::EXCLUDE_START_DATE`, plus one if the end date has been enabled through `DatePeriod::INCLUDE_END_DATE`.

  If the number of recurrences has not been explicitly passed, then this property contains the minimum number of returned instances. This would be `0`, plus one if the start date has not been disabled through `DatePeriod::EXCLUDE_START_DATE`, plus one if the end date has been enabled through `DatePeriod::INCLUDE_END_DATE`.

  `<?php
  $start = new DateTime('2018-12-31 00:00:00');
  $end = new DateTime('2021-12-31 00:00:00');
  $interval = new DateInterval('P1M');
  $recurrences = 5;
  // recurrences explicitly set through the constructor
  $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::EXCLUDE_START_DATE);
  echo $period->recurrences, "\n";
  $period = new DatePeriod($start, $interval, $recurrences);
  echo $period->recurrences, "\n";
  $period = new DatePeriod($start, $interval, $recurrences, DatePeriod::INCLUDE_END_DATE);
  echo $period->recurrences, "\n";
  // recurrences not set in the constructor
  $period = new DatePeriod($start, $interval, $end);
  echo $period->recurrences, "\n";
  $period = new DatePeriod($start, $interval, $end, DatePeriod::EXCLUDE_START_DATE);
  echo $period->recurrences, "\n";`

  The above example will output:

      5
      6
      7
      1
      0

  See also DatePeriod::getRecurrences().

include_end_date

  Whether to include the end date in the set of recurring dates or not.

include_start_date

  Whether to include the start date in the set of recurring dates or not.

start

  The start date of the period.

current

  During iteration this will contain the current date within the period.

end

  The end date of the period.

interval

  An ISO 8601 repeating interval specification.

## Changelog

Version | Description
--- | ---
8.4.0 | The class constants are now typed.
8.2.0 | The `DatePeriod::INCLUDE_END_DATE` constant and include_end_date property have been added.
8.0.0 | DatePeriod implements IteratorAggregate now. Previously, Traversable was implemented instead.

## Table of Contents

- DatePeriod::__construct — Creates a new DatePeriod object
- DatePeriod::createFromISO8601String — Creates a new DatePeriod object from an ISO8601 string
- DatePeriod::getDateInterval — Gets the interval
- DatePeriod::getEndDate — Gets the end date
- DatePeriod::getRecurrences — Gets the number of recurrences
- DatePeriod::getStartDate — Gets the start date

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open