RSet

_{^{(version >= 1.1)}}

Creation

A RSet object is a recurrence set. It can contains multiple recurrence rules (RRULE), exclusion rules (EXRULE), single dates (RDATE) and exclusion dates (EXDATE). The resulting occurrences will be a combination of all the rules and dates. Duplicates will be ignored, and returned only once.

Contrary to RRule objects, a RSet is mutable. You can add rules at any time using the following methods.

Creation from a string

_{^{(version >= 1.5)}}

It is also possible to create a RSet object from an RFC-like syntax by passing a string to the constructor. The string consists of multiple lines separated by \n (LF), or \r\n (CRLF). Each line defines a property: RRULE, EXRULE, RDATE, EXDATE and DTSTART (there can be only one DTSTART).

Example:

$rset = new RSet(
    "DTSTART;TZID=America/New_York:19970901T090000
    RRULE:FREQ=DAILY;COUNT=3
    EXRULE:FREQ=DAILY;INTERVAL=2;COUNT=1
    EXDATE;TZID=America/New_York:19970903T090000
    RDATE;TZID=America/New_York:19970904T090000"
);

When creating from a string without DTSTART you can optionally specify the date to be used in the second argument. By default, current date will be used.

The factory method RRule::createFromRfcString() can be used to parse a string and create either a RRule or a RSet object, depending on the string.

addRRule($rrule)

Add a recurrence rule to the set.

$rrule can be an instance of RRule or a string or an array understood by the RRule constructor.

Example:

use RRule\RSet;
$rset = new RSet();
$rset->addRRule(array(
    'FREQ' => 'YEARLY',
    'COUNT' => 2,
    'BYDAY' => 'TU',
    'DTSTART' => date_create('1997-09-02 09:00')
));
$rset->addRRule(array(
    'FREQ' => 'YEARLY',
    'COUNT' => 1,
    'BYDAY' => 'TH',
    'DTSTART' => date_create('1997-09-02 09:00')
));

// getOccurrences() will return:
// 1997-09-02 09:00
// 1997-09-04 09:00
// 1997-09-09 09:00

addDate($date)

Add a single date to the set. This date will be returned as an occurrence, even if it doesn't match any rule.

$date must be a DateTime object, a string representation of the date or a timestamp (int).

Example:

use RRule\RSet;
$rset = new RSet();
$rset->addRRule(array(
    'FREQ' => 'YEARLY',
    'COUNT' => 2,
    'BYDAY' => 'TU',
    'DTSTART' => date_create('1997-09-02 09:00')
));
$rset->addDate('1997-09-09 09:00');
$rset->addDate('1997-09-04 09:00');

// getOccurrences() will return:
// 1997-09-02 09:00
// 1997-09-04 09:00
// 1997-09-09 09:00

removeDate($date)

_{^{(version >= 2.1)}}

clearDates()

_{^{(version >= 2.1)}}

addExRule($exrule)

Add a recurrence rule to the set for exclusion. Any occurrence matching this rule will be removed for the end results.

$exrule can be an instance of RRule or a string or an array understood by the RRule constructor.

addExDate($date)

Add a date for exclusion. If this date is an occurrence of any of the rule in the set, it will be ignored.

$date must be a DateTime object, a string representation of the date or a timestamp (int).

Iteration

An instance of RSet can be used directly in a foreach loop to obtain occurrences. This is most efficient way to use this class, as the occurrences are only computed one at the time, as you need them.

Occurrences are DateTime objects. The timezone of the occurrences returned can vary, if you mixed different timezones when creating the recurrence set.

Warning: if your set contains at least one rule that doesn't have UNTIL or COUNT parts, it will be an infinite loop! You MUST take care of exiting the loop yourself.

Example:

use RRule\RSet;

$rset = new RSet;
$rset->addRRule([
    'freq' => RRule::DAILY,
    'interval' => 2,
    'count' => 5,
    'dtstart' => '1997-09-02 09:00:00'
]);
$rset->addExDate('1997-09-06 09:00:00');

foreach ( $rset as $occurrence ) {
    echo $occurrence->format('r'),"\n";
}

// output:
// Tue, 02 Sep 1997 09:00:00 +0000
// Thu, 04 Sep 1997 09:00:00 +0000
// (Sat, 06 Sep 1997 09:00:00 +0000 will not be outputed because it is in EXDATE)
// Mon, 08 Sep 1997 09:00:00 +0000
// Wed, 10 Sep 1997 09:00:00 +0000

removeExDate($date)

_{^{(version >= 2.1)}}

clearExDates()

_{^{(version >= 2.1)}}

ArrayAccess

A RSet object can also be used as an array to access the Nth occurrence directly.

Example:

use RRule\RSet;

$rset = new RSet;
$rset->addRRule([
    'freq' => RRule::DAILY,
    'interval' => 2,
    'count' => 5,
    'dtstart' => '1997-09-02 09:00:00'
]);
$rset->addExDate('1997-09-06 09:00:00');

echo $rset[0]->format('r'),"\n"; // Tue, 02 Sep 1997 09:00:00 +0000
echo $rset[3]->format('r'),"\n"; // Wed, 10 Sep 1997 09:00:00 +0000

var_dump(isset($rset[0])); // bool(true)
var_dump(isset($rset[4])); // bool(false)

Methods

RRuleInterface

In addition to the Iterator interface and the ArrayAccess interface, the methods from the RRuleInterface are available. Please check the corresponding wiki page.

getRRules()

_{^{(version >= 1.4)}}

Returns a list of all the rules added with addRRule().

getExRules()

_{^{(version >= 1.4)}}

Returns a list of all the rules added with addExRule().

getDates()

_{^{(version >= 1.4)}}

Returns a list of all the dates added with addDate().

getExDates()

_{^{(version >= 1.4)}}

Returns a list of all the dates added with addExDate().

Cache

Occurrences are cached the first time they are calculated. If you use the RSet instance multiple times, caching will improve the performance considerably.

clearCache()

Calling this method will clear the internal cache of the instance, and force it to recalculate the occurrences next time you try to them.