Documentation

EventIterator
in package

Application

implements Iterator

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.

Interfaces, Classes and Traits

Iterator

$allDay : bool: True if we're iterating an all-day event.
$counter : int: Internal event counter.
$currentDate : DateTimeImmutable: Where we are currently in the iteration process.
$currentOverriddenEvent : VEVENT: The event that overwrites the current iteration.
$eventDuration : mixed: The duration, in seconds, of the master event.
$exceptions : array<string|int, mixed>: A list of recurrence-id's that are either part of EXDATE, or are overridden.
$masterEvent : VEVENT: A reference to the main (master) event.
$nextDate : DateTimeImmutable: The next date from the rrule parser.
$overriddenEvents : array<string|int, mixed>: List of overridden events.
$overriddenEventsIndex : array<string|int, mixed>: Overridden event index.
$recurIterator : RRuleIterator: RRULE parser.
$startDate : DateTimeImmutable: The very start of the iteration process.
$timeZone : DateTimeZone: Reference timeZone for floating dates and times.
__construct() : mixed: Creates the iterator.
current() : DateTimeImmutable: Returns the date for the current position of the iterator.
fastForward() : mixed: Quickly jump to a date in the future.
getDtEnd() : DateTimeImmutable: This method returns the end date for the current iteration of the event.
getDtStart() : DateTimeImmutable: This method returns the start date for the current iteration of the event.
getEventObject() : VEvent: Returns a VEVENT for the current iterations of the event.
isInfinite() : bool: Returns true if this recurring event never ends.
key() : int: Returns the current position of the iterator.
next() : mixed: Advances the iterator with one step.
rewind() : mixed: Sets the iterator back to the starting point.
valid() : bool: This is called after next, to see if the iterator is still at a valid position, or if it's at the end.

$allDay

True if we're iterating an all-day event.


    protected
        bool
    $allDay
     = false

$counter

Internal event counter.


    protected
        int
    $counter

$currentDate

Where we are currently in the iteration process.


    protected
        DateTimeImmutable
    $currentDate

$currentOverriddenEvent

The event that overwrites the current iteration.


    protected
        VEVENT
    $currentOverriddenEvent

$eventDuration

The duration, in seconds, of the master event.


    protected
        mixed
    $eventDuration

We use this to calculate the DTEND for subsequent events.

$exceptions

A list of recurrence-id's that are either part of EXDATE, or are overridden.


    protected
        array<string|int, mixed>
    $exceptions
     = []

$masterEvent

A reference to the main (master) event.


    protected
        VEVENT
    $masterEvent

$nextDate

The next date from the rrule parser.


    protected
        DateTimeImmutable
    $nextDate

Sometimes we need to temporary store the next date, because an overridden event came before.

$overriddenEvents

List of overridden events.


    protected
        array<string|int, mixed>
    $overriddenEvents
     = []

$overriddenEventsIndex

Overridden event index.


    protected
        array<string|int, mixed>
    $overriddenEventsIndex

Key is timestamp, value is the list of indexes of the item in the $overriddenEvent property.

$recurIterator

RRULE parser.


    protected
        RRuleIterator
    $recurIterator

$startDate

The very start of the iteration process.


    protected
        DateTimeImmutable
    $startDate

$timeZone

Reference timeZone for floating dates and times.


    protected
        DateTimeZone
    $timeZone

__construct()

Creates the iterator.


    public
                __construct(Component|array<string|int, mixed> $input[, string|null $uid = null ][, DateTimeZone $timeZone = null ]) : mixed

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

$input : Component|array<string|int, mixed>
$uid : string|null = null
$timeZone : DateTimeZone = null: reference timezone for floating dates and times

Return values

mixed —

current()

Returns the date for the current position of the iterator.


    public
                current() : DateTimeImmutable

Return values

DateTimeImmutable —

fastForward()

Quickly jump to a date in the future.


    public
                fastForward(DateTimeInterface $dateTime) : mixed

Parameters

$dateTime : DateTimeInterface

Return values

mixed —

getDtEnd()

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


    public
                getDtEnd() : DateTimeImmutable

Return values

DateTimeImmutable —

getDtStart()

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


    public
                getDtStart() : DateTimeImmutable

Return values

DateTimeImmutable —

getEventObject()

Returns a VEVENT for the current iterations of the event.


    public
                getEventObject() : VEvent

This VEVENT will have a recurrence id, and its DTSTART and DTEND altered.

Return values

VEvent —

isInfinite()

Returns true if this recurring event never ends.


    public
                isInfinite() : bool

Return values

bool —

key()

Returns the current position of the iterator.


    public
                key() : int

This is for us simply a 0-based index.

Return values

int —

next()

Advances the iterator with one step.


    public
                next() : mixed

Return values

mixed —

rewind()

Sets the iterator back to the starting point.


    public
                rewind() : mixed

Return values

mixed —

valid()

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


    public
                valid() : bool

Return values

bool —