This class is used to determine new for a recurring event, when the next events occur. More...

Inheritance diagram for Sabre\VObject\Recur\EventIterator:

Collaboration diagram for Sabre\VObject\Recur\EventIterator:

Public Member Functions
	__construct ($input, $uid=null, DateTimeZone $timeZone=null)
	Creates the iterator. More...

	current ()
	Returns the date for the current position of the iterator. More...

	getDtStart ()
	This method returns the start date for the current iteration of the event. More...

	getDtEnd ()
	This method returns the end date for the current iteration of the event. More...

	getEventObject ()
	Returns a VEVENT for the current iterations of the event. More...

	key ()
	Returns the current position of the iterator. More...

	valid ()
	This is called after next, to see if the iterator is still at a valid position, or if it's at the end. More...

	rewind ()
	Sets the iterator back to the starting point. More...

	next ()
	Advances the iterator with one step. More...

	fastForward (DateTimeInterface $dateTime)
	Quickly jump to a date in the future. More...

	isInfinite ()
	Returns true if this recurring event never ends. More...

Protected Attributes
	$timeZone

	$allDay = false

	$recurIterator

	$eventDuration
	The duration, in seconds, of the master event. More...

	$masterEvent

	$overriddenEvents = []

	$overriddenEventsIndex

	$exceptions = []

	$counter

	$startDate

	$currentDate

	$nextDate

	$currentOverriddenEvent

Detailed Description

This class is used to determine new for a recurring event, when the next events occur.

This iterator may loop infinitely in the future, therefore it is important that if you use this class, you set hard limits for the amount of iterations you want to handle.

Note that currently there is not full support for the entire iCalendar specification, as it's very complex and contains a lot of permutations that's not yet used very often in software.

For the focus has been on features as they actually appear in Calendaring software, but this may well get expanded as needed / on demand

The following RRULE properties are supported

UNTIL
INTERVAL
COUNT
FREQ=DAILY
- BYDAY
- BYHOUR
- BYMONTH
FREQ=WEEKLY
- BYDAY
- BYHOUR
- WKST
FREQ=MONTHLY
- BYMONTHDAY
- BYDAY
- BYSETPOS
FREQ=YEARLY
- BYMONTH
- BYYEARDAY
- BYWEEKNO
- BYMONTHDAY (only if BYMONTH is also set)
- BYDAY (only if BYMONTH is also set)

Anything beyond this is 'undefined', which means that it may get ignored, or you may get unexpected results. The effect is that in some applications the specified recurrence may look incorrect, or is missing.

The recurrence iterator also does not yet support THISANDFUTURE.

Copyright: Copyright (C) fruux GmbH (https://fruux.com/)

Author: Evert Pot (http://evertpot.com/) @license http://sabre.io/license/ Modified BSD License

Definition at line 61 of file EventIterator.php.

Constructor & Destructor Documentation

◆ __construct()

Sabre\VObject\Recur\EventIterator::__construct	(		$input,
			$uid = `null`,
		DateTimeZone	$timeZone = `null`
	)

Creates the iterator.

There's three ways to set up the iterator.

You can pass a VCALENDAR component and a UID.
You can pass an array of VEVENTs (all UIDS should match).
You can pass a single VEVENT component.

Only the second method is recomended. The other 1 and 3 will be removed at some point in the future.

The $uid parameter is only required for the first method.

Parameters

Component \| array	$input
string \| null	$uid
DateTimeZone	$timeZone	Reference timezone for floating dates and times.

Definition at line 96 of file EventIterator.php.

                                                                             {
 
        if (is_null($timeZone)) {
            $timeZone = new DateTimeZone('UTC');
        }
        $this->timeZone = $timeZone;
 
        if (is_array($input)) {
            $events = $input;
        } elseif ($input instanceof VEvent) {
            // Single instance mode.
            $events = [$input];
        } else {
            // Calendar + UID mode.
            $uid = (string)$uid;
            if (!$uid) {
                throw new InvalidArgumentException('The UID argument is required when a VCALENDAR is passed to this constructor');
            }
            if (!isset($input->VEVENT)) {
                throw new InvalidArgumentException('No events found in this calendar');
            }
            $events = $input->getByUID($uid);
 
        }
 
        foreach ($events as $vevent) {
 
            if (!isset($vevent->{'RECURRENCE-ID'})) {
 
                $this->masterEvent = $vevent;
 
            } else {
 
                $this->exceptions[
                    $vevent->{'RECURRENCE-ID'}->getDateTime($this->timeZone)->getTimeStamp()
                ] = true;
                $this->overriddenEvents[] = $vevent;
 
            }
 
        }
 
        if (!$this->masterEvent) {
            // No base event was found. CalDAV does allow cases where only
            // overridden instances are stored.
            //
            // In this particular case, we're just going to grab the first
            // event and use that instead. This may not always give the
            // desired result.
            if (!count($this->overriddenEvents)) {
                throw new InvalidArgumentException('This VCALENDAR did not have an event with UID: ' . $uid);
            }
            $this->masterEvent = array_shift($this->overriddenEvents);
        }
 
        $this->startDate = $this->masterEvent->DTSTART->getDateTime($this->timeZone);
        $this->allDay = !$this->masterEvent->DTSTART->hasTime();
 
        if (isset($this->masterEvent->EXDATE)) {
 
            foreach ($this->masterEvent->EXDATE as $exDate) {
 
                foreach ($exDate->getDateTimes($this->timeZone) as $dt) {
                    $this->exceptions[$dt->getTimeStamp()] = true;
                }
 
            }
 
        }
 
        if (isset($this->masterEvent->DTEND)) {
            $this->eventDuration =
                $this->masterEvent->DTEND->getDateTime($this->timeZone)->getTimeStamp() -
                $this->startDate->getTimeStamp();
        } elseif (isset($this->masterEvent->DURATION)) {
            $duration = $this->masterEvent->DURATION->getDateInterval();
            $end = clone $this->startDate;
            $end = $end->add($duration);
            $this->eventDuration = $end->getTimeStamp() - $this->startDate->getTimeStamp();
        } elseif ($this->allDay) {
            $this->eventDuration = 3600 * 24;
        } else {
            $this->eventDuration = 0;
        }
 
        if (isset($this->masterEvent->RDATE)) {
            $this->recurIterator = new RDateIterator(
                $this->masterEvent->RDATE->getParts(),
                $this->startDate
            );
        } elseif (isset($this->masterEvent->RRULE)) {
            $this->recurIterator = new RRuleIterator(
                $this->masterEvent->RRULE->getParts(),
                $this->startDate
            );
        } else {
            $this->recurIterator = new RRuleIterator(
                [
                    'FREQ'  => 'DAILY',
                    'COUNT' => 1,
                ],
                $this->startDate
            );
        }
 
        $this->rewind();
        if (!$this->valid()) {
            throw new NoInstancesException('This recurrence rule does not generate any valid instances');
        }
 
    }

References $events, Sabre\VObject\$input, and Sabre\VObject\Recur\EventIterator\$timeZone.

Member Function Documentation

◆ current()

Sabre\VObject\Recur\EventIterator::current ( )

Returns the date for the current position of the iterator.

Returns: DateTimeImmutable

Definition at line 213 of file EventIterator.php.

                       {
 
        if ($this->currentDate) {
            return clone $this->currentDate;
        }
 
    }

References $currentDate.

◆ fastForward()

Sabre\VObject\Recur\EventIterator::fastForward ( DateTimeInterface $dateTime )

Quickly jump to a date in the future.

Parameters

DateTimeInterface $dateTime

Definition at line 410 of file EventIterator.php.

                                                      {
 
        while ($this->valid() && $this->getDtEnd() <= $dateTime) {
            $this->next();
        }
 
    }

◆ getDtEnd()

Sabre\VObject\Recur\EventIterator::getDtEnd ( )

This method returns the end date for the current iteration of the event.

Returns: DateTimeImmutable

Definition at line 241 of file EventIterator.php.

                        {
 
        if (!$this->valid()) {
            return;
        }
        $end = clone $this->currentDate;
        return $end->modify('+' . $this->eventDuration . ' seconds');
 
    }

References $currentDate, and $end.

◆ getDtStart()

Sabre\VObject\Recur\EventIterator::getDtStart ( )

This method returns the start date for the current iteration of the event.

Returns: DateTimeImmutable

Definition at line 227 of file EventIterator.php.

                          {
 
        if ($this->currentDate) {
            return clone $this->currentDate;
        }
 
    }

References $currentDate.

◆ getEventObject()

Sabre\VObject\Recur\EventIterator::getEventObject ( )

Returns a VEVENT for the current iterations of the event.

This VEVENT will have a recurrence id, and it's DTSTART and DTEND altered.

Returns: VEvent

Definition at line 259 of file EventIterator.php.

                              {
 
        if ($this->currentOverriddenEvent) {
            return $this->currentOverriddenEvent;
        }
 
        $event = clone $this->masterEvent;
 
        // Ignoring the following block, because PHPUnit's code coverage
        // ignores most of these lines, and this messes with our stats.
        //
        // @codeCoverageIgnoreStart
        unset(
            $event->RRULE,
            $event->EXDATE,
            $event->RDATE,
            $event->EXRULE,
            $event->{'RECURRENCE-ID'}
        );
        // @codeCoverageIgnoreEnd
 
        $event->DTSTART->setDateTime($this->getDtStart(), $event->DTSTART->isFloating());
        if (isset($event->DTEND)) {
            $event->DTEND->setDateTime($this->getDtEnd(), $event->DTEND->isFloating());
        }
        $recurid = clone $event->DTSTART;
        $recurid->name = 'RECURRENCE-ID';
        $event->add($recurid);
        return $event;
 
    }

◆ isInfinite()

Sabre\VObject\Recur\EventIterator::isInfinite ( )

Returns true if this recurring event never ends.

Returns: bool

Definition at line 423 of file EventIterator.php.

                          {
 
        return $this->recurIterator->isInfinite();
 
    }

◆ key()

Sabre\VObject\Recur\EventIterator::key ( )

Returns the current position of the iterator.

This is for us simply a 0-based index.

Returns: int

Definition at line 298 of file EventIterator.php.

                   {
 
        // The counter is always 1 ahead.
        return $this->counter - 1;
 
    }

◆ next()

Sabre\VObject\Recur\EventIterator::next ( )

Advances the iterator with one step.

Returns: void

Definition at line 349 of file EventIterator.php.

                    {
 
        $this->currentOverriddenEvent = null;
        $this->counter++;
        if ($this->nextDate) {
            // We had a stored value.
            $nextDate = $this->nextDate;
            $this->nextDate = null;
        } else {
            // We need to ask rruleparser for the next date.
            // We need to do this until we find a date that's not in the
            // exception list.
            do {
                if (!$this->recurIterator->valid()) {
                    $nextDate = null;
                    break;
                }
                $nextDate = $this->recurIterator->current();
                $this->recurIterator->next();
            } while (isset($this->exceptions[$nextDate->getTimeStamp()]));
 
        }
 
 
        // $nextDate now contains what rrule thinks is the next one, but an
        // overridden event may cut ahead.
        if ($this->overriddenEventsIndex) {
 
            $offsets = end($this->overriddenEventsIndex);
            $timestamp = key($this->overriddenEventsIndex);
            $offset = end($offsets);
            if (!$nextDate || $timestamp < $nextDate->getTimeStamp()) {
                // Overridden event comes first.
                $this->currentOverriddenEvent = $this->overriddenEvents[$offset];
 
                // Putting the rrule next date aside.
                $this->nextDate = $nextDate;
                $this->currentDate = $this->currentOverriddenEvent->DTSTART->getDateTime($this->timeZone);
 
                // Ensuring that this item will only be used once.
                array_pop($this->overriddenEventsIndex[$timestamp]);
                if (!$this->overriddenEventsIndex[$timestamp]) {
                    array_pop($this->overriddenEventsIndex);
                }
 
                // Exit point!
                return;
 
            }
 
        }
 
        $this->currentDate = $nextDate;
 
    }

References $timestamp.

◆ rewind()

Sabre\VObject\Recur\EventIterator::rewind ( )

Sets the iterator back to the starting point.

Definition at line 323 of file EventIterator.php.

                      {
 
        $this->recurIterator->rewind();
        // re-creating overridden event index.
        $index = [];
        foreach ($this->overriddenEvents as $key => $event) {
            $stamp = $event->DTSTART->getDateTime($this->timeZone)->getTimeStamp();
            $index[$stamp][] = $key;
        }
        krsort($index);
        $this->counter = 0;
        $this->overriddenEventsIndex = $index;
        $this->currentOverriddenEvent = null;
 
        $this->nextDate = null;
        $this->currentDate = clone $this->startDate;
 
        $this->next();
 
    }

References $index, and $key.

◆ valid()

Sabre\VObject\Recur\EventIterator::valid ( )

This is called after next, to see if the iterator is still at a valid position, or if it's at the end.

Returns: bool

Definition at line 311 of file EventIterator.php.

                     {
 
        if ($this->counter > Settings::$maxRecurrences && Settings::$maxRecurrences !== -1) {
            throw new MaxInstancesExceededException('Recurring events are only allowed to generate ' . Settings::$maxRecurrences);
        }
        return !!$this->currentDate;
 
    }

References $currentDate.

Field Documentation

◆ $allDay

Sabre\VObject\Recur\EventIterator::$allDay = false

protected

Definition at line 75 of file EventIterator.php.

◆ $counter

Sabre\VObject\Recur\EventIterator::$counter

protected

Definition at line 480 of file EventIterator.php.

◆ $currentDate

Sabre\VObject\Recur\EventIterator::$currentDate

protected

Definition at line 494 of file EventIterator.php.

◆ $currentOverriddenEvent

Sabre\VObject\Recur\EventIterator::$currentOverriddenEvent

protected

Definition at line 511 of file EventIterator.php.

◆ $eventDuration

Sabre\VObject\Recur\EventIterator::$eventDuration

protected

The duration, in seconds, of the master event.

We use this to calculate the DTEND for subsequent events.

Definition at line 441 of file EventIterator.php.

◆ $exceptions

Sabre\VObject\Recur\EventIterator::$exceptions = []

protected

Definition at line 473 of file EventIterator.php.

◆ $masterEvent

Sabre\VObject\Recur\EventIterator::$masterEvent

protected

Definition at line 448 of file EventIterator.php.

◆ $nextDate

Sabre\VObject\Recur\EventIterator::$nextDate

protected

Definition at line 504 of file EventIterator.php.

◆ $overriddenEvents

Sabre\VObject\Recur\EventIterator::$overriddenEvents = []

protected

Definition at line 455 of file EventIterator.php.

◆ $overriddenEventsIndex

Sabre\VObject\Recur\EventIterator::$overriddenEventsIndex

protected

Definition at line 465 of file EventIterator.php.

◆ $recurIterator

Sabre\VObject\Recur\EventIterator::$recurIterator

protected

Definition at line 434 of file EventIterator.php.

◆ $startDate

Sabre\VObject\Recur\EventIterator::$startDate

protected

Definition at line 487 of file EventIterator.php.

◆ $timeZone

Sabre\VObject\Recur\EventIterator::$timeZone

protected

Definition at line 68 of file EventIterator.php.

Referenced by Sabre\VObject\Recur\EventIterator\__construct().

The documentation for this class was generated from the following file:

libs/composer/vendor/sabre/vobject/lib/Recur/EventIterator.php

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ current()

◆ fastForward()

◆ getDtEnd()

◆ getDtStart()

◆ getEventObject()

◆ isInfinite()

◆ key()

◆ next()

◆ rewind()

◆ valid()

Field Documentation

◆ $allDay

◆ $counter

◆ $currentDate

◆ $currentOverriddenEvent

◆ $eventDuration

◆ $exceptions

◆ $masterEvent

◆ $nextDate

◆ $overriddenEvents

◆ $overriddenEventsIndex

◆ $recurIterator

◆ $startDate

◆ $timeZone