Date Recur field API

API for Date Recur field.

Field item occurrences

How to work with field values.

Get occurrences for a field

Iterating over occurrences.

foreach ($entity->field_dates->occurrences as $occurrence) {
  /** @var \Drupal\date_recur\DateRange $occurrence */
}

$entity->field_dates->occurrences returns a generator which generates \Drupal\date_recur\DateRange objects. See Occurrence Generator below.

Determine if a field item is recurring.

/** @var bool $isRecurring */
$isRecurring = $entity->field_dates[0]->isRecurring();

Get helper for a field item

Helpers provide additional utilities:

Get the utility helper for a field value:

/** @var \Drupal\date_recur\DateRecurHelperInterface $helper */
$helper = $entity->field_dates[0]->getHelper();

Determine if a field item is infinite:

/** @var bool $isInfinite */
$isInfinite = $helper->isInfinite();

Get the individual rules for a field item.

/** @var \Drupal\date_recur\DateRecurRuleInterface[] $rules */
$rules = $helper->getRules();

Occurrence generator

Get the occurrences for a field item as a generator. Each occurrence is an instance of \Drupal\date_recur\DateRange.

/** @var \DateTimeInterface|null $rangeStart */
/** @var \DateTimeInterface|null $rangeEnd */
/** @var \Generator $generator */
$generator = $helper->generateOccurrences($rangeStart, $rangeEnd);

A generator is designed to be iterated over. If the rule is infinite and no $rangeEnd argument is provided the generator will never exit. Add some kind of limiter to your iteration function, for example:

$i = 0;
foreach ($helper->generateOccurrences() as $occurrence) {
  $i++;
  if ($i > 100) {
    break;
  }
}

Calculate Occurrences

Calculate all occurrences into an array.

/** @var \DateTimeInterface|null $rangeStart */
/** @var \DateTimeInterface|null $rangeEnd */
/** @var int|null $limit */
/** @var \Drupal\date_recur\DateRange[] $occurrences */
$occurrences = $helper->getOccurrences($rangeStart, $rangeEnd, $limit);

An exception is thrown if the field value contains a rule which is infinite AND no value is provided for both $rangeEnd AND $limit arguments.

Occurrences are generated in chronological order of the start date.

Usage examples.

Get five occurrences from now:

$now = new \DateTime();
$occurrences = $helper->getOccurrences($now, NULL, 5);

Get all occurrences from the first occurrence, and a date in the future:

$rangeEnd = new \DateTime('4th October 2022');
$occurrences = $helper->getOccurrences(NULL, $rangeEnd);

Get all occurrences between a date, and a date in the future

$rangeStart = new \DateTime('1st February 1988');
$rangeEnd = new \DateTime('4th October 1996');
$occurrences = $helper->getOccurrences($rangeStart, $rangeEnd);

Range Objects

Various helpers return \Drupal\date_recur\DateRange objects. A date range is an immutable object and consists of the start and end date times for an individual occurrence.

The dates can be extracted from DateRange objects:

/** @var \Drupal\date_recur\DateRange $occurrence */
/** @var \DateTimeInterface $occurrenceStart */
$occurrenceStart = $occurrence->getStart();
/** @var \DateTimeInterface $occurrenceEnd */
$occurrenceEnd = $occurrence->getEnd();