# The DatePeriod class

&reftitle.intro;

Represents a date period.

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

&reftitle.classsynopsis;

         DatePeriod

         implements
         IteratorAggregate

        &Constants;

         public
         const
         int
         DatePeriod::EXCLUDE_START_DATE

         public
         const
         int
         DatePeriod::INCLUDE_END_DATE

        &Properties;

         public
         readonly
         DateTimeInterfacenull
         start

         public
         readonly
         DateTimeInterfacenull
         current

         public
         readonly
         DateTimeInterfacenull
         end

         public
         readonly
         DateIntervalnull
         interval

         public
         readonly
         int
         recurrences

         public
         readonly
         bool
         include_start_date

         public
         readonly
         bool
         include_end_date

        &Methods;

&reftitle.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`.

&reftitle.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";
      ?>

  &example.outputs;

      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.

&reftitle.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.

&reference.datetime.entities.dateperiod;