Sabre\VObject\Recur\EventIterator Class Reference

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:

Data Structures
class	ExpandFloatingTimesTest
class	FifthTuesdayProblemTest
class	HandleRDateExpandTest
	This is a unittest for Issue #53. More...
class	IncorrectExpandTest
	This is a unittest for Issue #53. More...
class	InfiniteLoopProblemTest
class	Issue26Test
class	MainTest
class	MaxInstancesTest
class	MissingOverriddenTest

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/) 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.

1. You can pass a VCALENDAR component and a UID.
2. You can pass an array of VEVENTs (all UIDS should match).
3. 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.

References $end, $events, Sabre\VObject\$input, Sabre\VObject\Recur\EventIterator\$startDate, Sabre\VObject\Recur\EventIterator\$timeZone, Sabre\VObject\Recur\EventIterator\rewind(), and Sabre\VObject\Recur\EventIterator\valid().

                                                                             {

        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');
        }

    }

Here is the call graph for this function:

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.

References Sabre\VObject\Recur\EventIterator\$currentDate.

                       {

        if ($this->currentDate) {
            return clone $this->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.

References Sabre\VObject\Recur\EventIterator\getDtEnd(), Sabre\VObject\Recur\EventIterator\next(), and Sabre\VObject\Recur\EventIterator\valid().

Referenced by Sabre\VObject\Component\VEvent\isInTimeRange().

                                                      {

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

    }

Here is the call graph for this function:

Here is the caller graph for this function:

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.

References Sabre\VObject\Recur\EventIterator\$currentDate, $end, and Sabre\VObject\Recur\EventIterator\valid().

Referenced by Sabre\VObject\Recur\EventIterator\fastForward(), and Sabre\VObject\Recur\EventIterator\getEventObject().

                        {

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

    }

Here is the call graph for this function:

Here is the caller graph for this function:

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.

References Sabre\VObject\Recur\EventIterator\$currentDate.

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

                          {

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

    }

Here is the caller graph for this function:

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.

References Sabre\VObject\Recur\EventIterator\$currentOverriddenEvent, Sabre\VObject\Recur\EventIterator\$masterEvent, Sabre\VObject\Recur\EventIterator\getDtEnd(), and Sabre\VObject\Recur\EventIterator\getDtStart().

                              {

        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;

    }

Here is the call graph for this function:

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.

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

                   {

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

    }

Here is the caller graph for this function:

next()

Sabre\VObject\Recur\EventIterator::next

(

)

Advances the iterator with one step.

Returns

void

Definition at line 349 of file EventIterator.php.

References Sabre\VObject\Recur\EventIterator\$nextDate, $timestamp, and Sabre\VObject\Recur\EventIterator\key().

Referenced by Sabre\VObject\Recur\EventIterator\fastForward(), and Sabre\VObject\Recur\EventIterator\rewind().

                    {

        $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;

    }

Here is the call graph for this function:

Here is the caller graph for this function:

rewind()

Sabre\VObject\Recur\EventIterator::rewind

(

)

Sets the iterator back to the starting point.

Definition at line 323 of file EventIterator.php.

References $index, $key, Sabre\VObject\Recur\EventIterator\$startDate, and Sabre\VObject\Recur\EventIterator\next().

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

                      {

        $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();

    }

Here is the call graph for this function:

Here is the caller graph for this function:

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.

References Sabre\VObject\Recur\EventIterator\$currentDate, and Sabre\VObject\Settings\$maxRecurrences.

Referenced by Sabre\VObject\Recur\EventIterator\__construct(), Sabre\VObject\Recur\EventIterator\fastForward(), and Sabre\VObject\Recur\EventIterator\getDtEnd().

                     {

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

    }

Here is the caller graph for this function:

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.

Referenced by Sabre\VObject\Recur\EventIterator\current(), Sabre\VObject\Recur\EventIterator\getDtEnd(), Sabre\VObject\Recur\EventIterator\getDtStart(), and Sabre\VObject\Recur\EventIterator\valid().

$currentOverriddenEvent

Sabre\VObject\Recur\EventIterator::$currentOverriddenEvent

protected

Definition at line 511 of file EventIterator.php.

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

$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.

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

$nextDate

Sabre\VObject\Recur\EventIterator::$nextDate

protected

Definition at line 504 of file EventIterator.php.

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

$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.

Referenced by Sabre\VObject\Recur\EventIterator\__construct(), and Sabre\VObject\Recur\EventIterator\rewind().

$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