RRULE for PHP

https://github.com/rlanvin/php-rrule
Admin
A lightweight and fast PHP implementation of recurrence rules (RRULE from RFC 5545) to calculate...
Tokens:58,592
Snippets:350
Trust Score:6.9
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Error Handling Examples

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rrule-interface.md

Examples of exceptions thrown when calling getOccurrences() or getOccurrencesBetween() on infinite recurrence rules without limits.

```APIDOC
## Error Handling Examples

### Description
Demonstrates the \LogicException thrown when attempting to get all occurrences of an infinite recurrence rule without a limit, and the safe behavior with finite rules.

### Example
```php
use RRule\RRule;

$infinite = new RRule(['FREQ' => 'DAILY', 'DTSTART' => '2024-01-01']);

try {
    $infinite->getOccurrences(); // no limit on an infinite rule
} catch (\LogicException $e) {
    echo $e->getMessage(); // Cannot get all occurrences of an infinite recurrence rule.
}

try {
    $infinite->getOccurrencesBetween('2024-01-01', null);
} catch (\LogicException $e) {
    // also throws — unbounded range on an infinite rule
}

try {
    $infinite->getOccurrences(10);
} catch (\LogicException $e) {
    // not reached: a limit makes the call valid
}

// Finite rules are safe without a limit:
$finite = new RRule(['FREQ' => 'DAILY', 'DTSTART' => '2024-01-01', 'UNTIL' => '2024-01-10']);
echo count($finite->getOccurrences()); // 10
```
```

--------------------------------

### humanReadable examples with different locales and formatters

Source: https://github.com/rlanvin/php-rrule/wiki/RRule

Shows how to use the humanReadable method to generate human-readable descriptions of a recurrence rule. The examples demonstrate default output, French locale, custom date format, and a custom date formatter. Requires PHP intl extension for best results.

```php
$rule = new RRule('DTSTART;TZID=America/New_York:19970901T090000
       RRULE:FREQ=WEEKLY;INTERVAL=2;UNTIL=19971224T000000Z;WKST=SU;BYDAY=MO,WE,FR');

echo $rule->humanReadable();
// every other week on Monday, Wednesday and Friday, starting from 9/1/97, until 12/23/97

echo $rule->humanReadable(['locale' => 'fr']);
// une semaine sur deux le lundi, mercredi et vendredi, à partir du 01/09/97, jusqu'au 23/12/97

echo $rrule->humanReadable([
    'locale' => 'en_US',
    'date_format' => IntlDateFormatter::MEDIUM
]),"\n\n";
// every other week on Monday, Wednesday and Friday, starting from Sep 1, 1997, until Dec 23, 1997

echo $rule->humanReadable(['date_formatter' => function($date) { return $date->format('r'); }]);
// every other week on Monday, Wednesday and Friday, starting from Mon, 01 Sep 1997 09:00:00 -0400, until Wed, 24 Dec 1997 00:00:00 +0000
```

--------------------------------

### Get all occurrences with getOccurrences()

Source: https://github.com/rlanvin/php-rrule/wiki/RRuleInterface

Example of retrieving all occurrences as an array of DateTime objects for a finite rule.

```php
$rrule = new RRule([
    'FREQ' => 'DAILY',
    'DTSTART' => '2016-01-01',
    'UNTIL' => '2016-12-31'
]);

$result = $rrule->getOccurrences(); // an array of DateTime objects
```

--------------------------------

### getIterator() usage example

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rset.md

Demonstrates iterating over a set with a daily rule and an additional date. Outputs the dates in chronological order.

```php
$set = new RSet();
$set->addRRule(['FREQ' => 'DAILY', 'DTSTART' => '2024-01-01', 'COUNT' => 3]);
$set->addDate('2024-01-10');
foreach ($set as $occ) { echo $occ->format('Y-m-d'), ' '; }
// 2024-01-01 2024-01-02 2024-01-03 2024-01-10
```

--------------------------------

### RSet date manipulation example

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rset.md

Example usage of addDate(), getDates(), removeDate(), and clearDates(). Creates an RSet, adds two dates, counts them (outputs 2), then removes one and clears all, resulting in an empty array.

```php
$set = new RSet();
$set->addDate('2024-05-10')->addDate('2024-05-11');
var_dump(count($set->getDates()));      // 2
$set->removeDate('2024-05-10')->clearDates();
var_dump($set->getDates());             // []
```

--------------------------------

### Check if rule is finite or infinite (isFinite/isInfinite)

Source: https://github.com/rlanvin/php-rrule/wiki/RRuleInterface

Example of an infinite daily rule (no COUNT or UNTIL). isFinite() returns false and isInfinite() returns true.

```php
$rrule = new RRule([
    'FREQ' => 'DAILY',
    'INTERVAL' => 1,
    // no COUNT or UNTIL
]);
$rrule->isFinite(); // false
$rrule->isInfinite(); // true
```

--------------------------------

### Get occurrences between dates with getOccurrencesBetween()

Source: https://github.com/rlanvin/php-rrule/wiki/RRuleInterface

Example of retrieving occurrences between two dates for a monthly rule with BYDAY=1MO. The output shows the first Monday of January 2016.

```php
$rrule = new RRule([
    'FREQ' => 'MONTHLY',
    'BYDAY' => '1MO',
    'DTSTART' => '2016-01-01',
    'UNTIL' => '2016-12-31'
]);

$result = $rrule->getOccurrencesBetween('2016-01-01', '2016-01-31');
print_r($result);

// only the first Monday between 1 January and 31 January
// Array
// (
//     [0] => DateTime Object
//         (
//             [date] => 2016-01-04 00:00:00.000000
//             [timezone_type] => 3
//             [timezone] => Europe/Helsinki
//         )
// )
```

--------------------------------

### humanReadable() usage example

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rrule.md

Creates a monthly RRule with COUNT=6 and prints the human-readable description in English and French. The output depends on locale and intl availability.

```php
$rrule = new RRule(['FREQ' => 'MONTHLY', 'DTSTART' => '2015-06-01', 'COUNT' => 6]);
echo $rrule->humanReadable();
// monthly on the 1st of the month, starting from 01/06/2015, 6 times
// (date rendering depends on the locale and whether the intl extension is loaded)

echo $rrule->humanReadable(['locale' => 'fr_FR']);
// tous les mois le 1er du mois, à partir du 01/06/2015, 6 fois (approximate — ICU-version dependent)
```

--------------------------------

### Create RRule from RFC-like string formats

Source: https://github.com/rlanvin/php-rrule/wiki/RRule

Shows the four accepted string formats for creating an RRule object: a multi-line string with DTSTART and RRULE separated by a newline, a single-line string with the RRULE property, just the RRULE value, and (since version 1.5) an RRULE value with an optional DateTime as the second argument. The DTSTART and RRULE must be on separate lines; DTSTART inside RRULE is invalid. When creating from a string without DTSTART, the second argument (or the current date by default) is used as the start date.

```php
new RRule('DTSTART;TZID=America/New_York:19970901T090000
RRULE:FREQ=DAILY;UNTIL=19971224T000000Z;WKST=SU;BYDAY=MO,WE,FR;BYMONTH=1');

new RRule('RRULE:FREQ=DAILY;UNTIL=19971224T000000Z;WKST=SU;BYDAY=MO,WE,FR;BYMONTH=1');

new RRule('FREQ=DAILY;UNTIL=19971224T000000Z;WKST=SU;BYDAY=MO,WE,FR;BYMONTH=1');

new RRule('FREQ=DAILY', new DateTime('1997-12-24')); // since version 1.5
```

--------------------------------

### getOccurrences() usage example

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rrule-interface.md

Creates a daily RRule with COUNT=30 and retrieves the first 5 occurrences, echoing the count (5).

```php
$rrule = new RRule(['FREQ' => 'DAILY', 'DTSTART' => '2024-01-01', 'COUNT' => 30]);
$first5 = $rrule->getOccurrences(5);
echo count($first5); // 5
```

--------------------------------

### getNthOccurrenceFrom() example

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rrule-interface.md

Example usage of getNthOccurrenceFrom() with a daily RRule. Shows index 0 returning the date itself, positive index returning an occurrence after, and negative index returning an occurrence before.

```php
$rrule = new RRule(['FREQ' => 'DAILY', 'DTSTART' => '2024-01-01', 'COUNT' => 30]);

$rrule->getNthOccurrenceFrom('2024-01-10', 0);   // 2024-01-10 (it is an occurrence)
$rrule->getNthOccurrenceFrom('2024-01-10', 2);   // 2024-01-12
$rrule->getNthOccurrenceFrom('2024-01-10', -2);  // 2024-01-08
```

--------------------------------

### createFromRfcString() usage example

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rrule.md

Shows how createFromRfcString() returns an RRule for a single RRULE without extra date rules, and an RSet when $force_rset is true. The first call echoes RRule\RRule, the second RRule\RSet.

```php
use RRule\RRule;

$rule = RRule::createFromRfcString("DTSTART:19970902T090000\nRRULE:FREQ=WEEKLY;BYDAY=TU,TH;COUNT=10");
echo get_class($rule); // RRule\RRule

$set = RRule::createFromRfcString("DTSTART:19970902T090000\nRRULE:FREQ=WEEKLY\nRDATE:19970904T090000", true);
echo get_class($set);  // RRule\RSet
```

--------------------------------

### ArrayAccess usage example

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rrule.md

Creates a daily RRule with COUNT=3 and accesses occurrences by index. $rrule[1] returns the second occurrence; isset($rrule[5]) is false because only 3 occurrences exist.

```php
$rrule = new RRule(['FREQ' => 'DAILY', 'DTSTART' => '2024-01-01', 'COUNT' => 3]);
echo $rrule[1]->format('Y-m-d'); // 2024-01-02
var_dump(isset($rrule[5])); // false
```

--------------------------------

### occursAt() usage example

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rset.md

Demonstrates checking if specific dates occur in a set with a daily rule and an exclusion date. Outputs true for included date and false for excluded date.

```php
$set = new RSet();
$set->addRRule(['FREQ' => 'DAILY', 'DTSTART' => '2024-01-01', 'COUNT' => 10]);
$set->addExDate('2024-01-03');
var_dump($set->occursAt('2024-01-02')); // true
var_dump($set->occursAt('2024-01-03')); // false — excluded
```

--------------------------------

### getIterator() usage example

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rrule.md

Iterates over a weekly RRule with BYDAY=MO and COUNT=3, printing each occurrence. Output is '2024-01-01 2024-01-08 2024-01-15'.

```php
$rrule = new RRule(['FREQ' => 'WEEKLY', 'BYDAY' => 'MO', 'DTSTART' => '2024-01-01', 'COUNT' => 3]);
foreach ($rrule as $occ) { echo $occ->format('Y-m-d'), ' '; } // 2024-01-01 2024-01-08 2024-01-15
```

--------------------------------

### Basic construction from an array

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rrule.md

Creates a new RRule instance from an associative array of rule parts. The example iterates over occurrences and prints each formatted date. Requires the RRule class from the library.

```php
use RRule\RRule;

$rrule = new RRule([
    'FREQ' => 'MONTHLY',
    'INTERVAL' => 1,
    'DTSTART' => '2015-06-01',
    'COUNT' => 6
]);

foreach ($rrule as $occurrence) {
    echo $occurrence->format('D d M Y'), "\n";
}
```

--------------------------------

### Create and iterate a basic RRule with COUNT

Source: https://github.com/rlanvin/php-rrule/blob/master/README.md

Creates a monthly RRule with a count of 6 occurrences starting from 2015-06-01, iterates over the occurrences to print their dates, and outputs a human-readable description of the rule. The humanReadable() method requires the intl extension for full functionality. The expected output is shown in the comments.

```php
use RRule\RRule;

$rrule = new RRule([
	'FREQ' => 'MONTHLY',
	'INTERVAL' => 1,
	'DTSTART' => '2015-06-01',
	'COUNT' => 6
]);

foreach ($rrule as $occurrence) {
	echo $occurrence->format('D d M Y'),", ";
}
// Mon 01 Jun 2015, Wed 01 Jul 2015, Sat 01 Aug 2015, Tue 01 Sep 2015, Thu 01 Oct 2015, Sun 01 Nov 2015

echo $rrule->humanReadable(),"\n";
// monthly on the 1st of the month, starting from 01/06/2015, 6 times

```

--------------------------------

### Count occurrences with count()

Source: https://github.com/rlanvin/php-rrule/wiki/RRuleInterface

Example of counting occurrences for a finite rule (with UNTIL). count($rrule) returns 366 for a leap year.

```php
$rrule = new RRule([
    'FREQ' => 'DAILY',
    'DTSTART' => '2016-01-01',
    'UNTIL' => '2016-12-31'
]);

count($rrule); // 366, it's a leap year!
```

--------------------------------

### Error handling for infinite RRule

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rrule-interface.md

Error handling examples for infinite RRule instances. Calling getOccurrences() without a limit or getOccurrencesBetween() with an unbounded range throws a LogicException; providing a limit makes the call valid. Finite rules (with UNTIL) are safe without a limit.

```php
use RRule\RRule;

$infinite = new RRule(['FREQ' => 'DAILY', 'DTSTART' => '2024-01-01']);

try {
    $infinite->getOccurrences(); // no limit on an infinite rule
} catch (\LogicException $e) {
    echo $e->getMessage(); // Cannot get all occurrences of an infinite recurrence rule.
}

try {
    $infinite->getOccurrencesBetween('2024-01-01', null);
} catch (\LogicException $e) {
    // also throws — unbounded range on an infinite rule
}

try {
    $infinite->getOccurrences(10);
} catch (\LogicException $e) {
    // not reached: a limit makes the call valid
}

// Finite rules are safe without a limit:
$finite = new RRule(['FREQ' => 'DAILY', 'DTSTART' => '2024-01-01', 'UNTIL' => '2024-01-10']);
echo count($finite->getOccurrences()); // 10
```

--------------------------------

### Construction from an RFC string with error handling

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rrule.md

Creates a new RRule instance from an RFC 5545 string. The example catches InvalidArgumentException and logs the error message. Useful when the rule string may contain unsupported parts or conflicts.

```php
use RRule\RRule;

try {
    $rrule = new RRule("DTSTART:19970902T090000\nRRULE:FREQ=YEARLY;COUNT=3");
    echo $rrule->rfcString();
} catch (\InvalidArgumentException $e) {
    // e.g. unsupported rule parts, illegal FREQ, UNTIL+COUNT conflict
    error_log('Invalid recurrence rule: ' . $e->getMessage());
}
```

--------------------------------

### Daily recurrence with count=10

Source: https://github.com/rlanvin/php-rrule/wiki/RRule

Creates a daily recurrence rule limited to 10 occurrences, starting from 1997-09-02 09:00:00. The output shows the first 10 dates generated.

```php
$rrule = new RRule([
    'freq' => 'daily',
    'count' => 10,
    'dtstart' => '1997-09-02 09:00:00'
]);
// 1997-09-02 09:00:00
// 1997-09-03 09:00:00
// 1997-09-04 09:00:00
// 1997-09-05 09:00:00
// 1997-09-06 09:00:00
// 1997-09-07 09:00:00
// 1997-09-08 09:00:00
// 1997-09-09 09:00:00
// 1997-09-10 09:00:00
// 1997-09-11 09:00:00
```

--------------------------------

### occursAt() usage example

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rrule.md

Shows occursAt() returning true for a date within the rule's occurrences and false for a date after the COUNT limit. The rule is daily starting 2024-01-01 with COUNT=10.

```php
use RRule\RRule;

$rrule = new RRule(['FREQ' => 'DAILY', 'DTSTART' => '2024-01-01', 'COUNT' => 10]);
var_dump($rrule->occursAt('2024-01-03')); // true
var_dump($rrule->occursAt('2024-01-20')); // false (after COUNT)
```

--------------------------------

### Create and iterate an RRule for monthly first Mondays

Source: https://github.com/rlanvin/php-rrule/wiki/Home

Creates an RRule for the first Monday of each month in 2016 and iterates over occurrences, printing each date. The output shows the expected dates from January to December 2016.

```php
$rrule = new RRule\RRule([
    'FREQ' => 'MONTHLY',
    'INTERVAL' => 1,
    'BYDAY' => '1MO',
    'DTSTART' => '2016-01-01',
    'UNTIL' => '2016-12-31'
]);

foreach ($rrule as $occurrence ) {
	echo $occurrence->format('Y-m-d'),"\n";
}

// 2016-01-04
// 2016-02-01
// 2016-03-07
// 2016-04-04
// 2016-05-02
// 2016-06-06
// 2016-07-04
// 2016-08-01
// 2016-09-05
// 2016-10-03
// 2016-11-07
// 2016-12-05
```

--------------------------------

### getOccurrencesBefore() example

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rrule-interface.md

Example usage of getOccurrencesBefore() with a daily RRule. Returns the last 3 occurrences before 2024-01-15, which are 2024-01-12, 2024-01-13, and 2024-01-14.

```php
$rrule = new RRule(['FREQ' => 'DAILY', 'DTSTART' => '2024-01-01', 'COUNT' => 30]);
$last3 = $rrule->getOccurrencesBefore('2024-01-15', false, 3);
// 2024-01-12, 2024-01-13, 2024-01-14
```

--------------------------------

### new RRule(string $rfcString, ?DateTime $dtstart = null)

Source: https://github.com/rlanvin/php-rrule/wiki/RRule

Creates an RRule object from an RFC-like string. The string can be a multi-line string with DTSTART and RRULE, a single-line RRULE, or just the RRULE property value. Optionally, a DateTime can be provided as the second argument for versions >= 1.5 when DTSTART is not in the string.

```APIDOC
## Constructor: new RRule(string $rfcString, ?DateTime $dtstart = null)

### Description
Creates an RRule object from an RFC-like string. The string may be a multiple line string (`DTSTART` and `RRULE`), a single line string (only `RRULE`), or just the `RRULE` property value. `DTSTART` and `RRULE` must be separated by `\n` (LF) or `\r\n` (CRLF). For versions >= 1.5, 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.

### Method
Constructor

### Endpoint
`new RRule($rfcString, $dtstart = null)`

### Parameters
#### Constructor Parameters
- **$rfcString** (string) - Required - The RFC-like string containing DTSTART and/or RRULE.
- **$dtstart** (\DateTime|null) - Optional - The date to use as DTSTART when not present in the string. Available since version 1.5.

### Request Example
```php
new RRule('DTSTART;TZID=America/New_York:19970901T090000\nRRULE:FREQ=DAILY;UNTIL=19971224T000000Z;WKST=SU;BYDAY=MO,WE,FR;BYMONTH=1');

new RRule('RRULE:FREQ=DAILY;UNTIL=19971224T000000Z;WKST=SU;BYDAY=MO,WE,FR;BYMONTH=1');

new RRule('FREQ=DAILY;UNTIL=19971224T000000Z;WKST=SU;BYDAY=MO,WE,FR;BYMONTH=1');

new RRule('FREQ=DAILY', new DateTime('1997-12-24')); // since version 1.5
```

### Response
#### Success Response
- Returns an `RRule` object.

#### Error Handling
- For versions >= 1.3, throws `InvalidArgumentException` if the string is invalid.

### Notes
- In the RFC, `DTSTART` and `RRULE` are two different properties and must be on separate lines. It is not valid to have `DTSTART` inside `RRULE`.
- When creating from a string, there is less flexibility on the date formats for `DTSTART` and `UNTIL`. See the table below for allowed formats.

| `DTSTART` | `UNTIL` | Comment |
|-----------|---------|---------|
| Date (`19970901`) | Date | |
| Date with local time (`19970901T090000`) | Date with local time | PHP's default timezone will be used |
| Date with UTC time (`19970901T090000Z`) | Date with UTC time | |
| Date with local time and time zone reference (`TZID=America/New_York:19980119T020000`) | Date with UTC time (`19970901T090000Z`) | There is no way to specify a different timezone for UNTIL in the RFC syntax. |
| Provided in the 2nd argument | Date with UTC time (`19970901T090000Z`) | Not recommended, if `UNTIL` is present in the string, so should `DTSTART` |
```

--------------------------------

### isFinite() and isInfinite()

Source: https://github.com/rlanvin/php-rrule/wiki/RRuleInterface

Methods to check if the rule is finite or infinite.

```APIDOC
## isFinite() and isInfinite()

### Description
Indicate whether or not the rule has an end (count or until), or is infinite. Return `true` or `false`.

### Method
isFinite() / isInfinite()

### Parameters
None

### Return Value
- **bool** - `true` if the rule is finite (has COUNT or UNTIL), `false` otherwise for `isFinite()`. `isInfinite()` returns the opposite.

### Example
```php
$rrule = new RRule([
    'FREQ' => 'DAILY',
    'INTERVAL' => 1,
    // no COUNT or UNTIL
]);
$rrule->isFinite(); // false
$rrule->isInfinite(); // true
```
```

--------------------------------

### RRule::parseDate() usage examples

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rrule-interface.md

Usage examples for RRule::parseDate(). It accepts a Unix timestamp (interpreted with UTC), a date string, or a DateTimeImmutable (cloned with microseconds stripped). Returns a DateTimeImmutable if a DateTimeImmutable was passed, otherwise a DateTime.

```php
$dt = RRule::parseDate(1704067200);          // Unix timestamp => UTC DateTime
$dt = RRule::parseDate('2024-01-01 10:00');  // parsed string
$dt = RRule::parseDate(new \DateTimeImmutable('2024-01-01')); // cloned DateTimeImmutable, microseconds stripped
```

--------------------------------

### getNthOccurrenceBefore()

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rrule-interface.md

Method to get the Nth occurrence before a given date.

```APIDOC
## getNthOccurrenceBefore()

### Description
Returns the Nth occurrence strictly before a reference date.

### Method
`getNthOccurrenceBefore($date, $index)`

### Parameters
- **$date** (mixed) - Required - Reference date.
- **$index** (int) - Required - The index of the occurrence (1-based).

### Return
`\DateTime|null` - Returns `null` when fewer than `$index` occurrences exist before `$date`.

### Exceptions
- `\InvalidArgumentException` - Thrown when `$index <= 0` with message 'Index must be a positive integer'.
```

--------------------------------

### getRule()

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rrule.md

Returns the original rule array exactly as passed to the constructor, with upper-cased keys and merged with defaults, including DTSTART.

```APIDOC
## getRule()

### Description
Returns the original rule array exactly as passed to the constructor (upper-cased keys, merged with defaults), including `DTSTART`.

### Method
`getRule()`

### Signature
```php
public function getRule()
```

### Parameters
None.

### Return Type
`array`

### Exceptions
None.
```

--------------------------------

### getNthOccurrenceFrom()

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rrule-interface.md

Method to get the Nth occurrence from a reference date, supporting both forward and backward lookup.

```APIDOC
## getNthOccurrenceFrom()

### Description
Bidirectional lookup of occurrences relative to a reference date.

### Method
`getNthOccurrenceFrom($date, $index)`

### Parameters
- **$date** (mixed) - Required - Reference date.
- **$index** (int) - Required - `0` → `$date` itself if it is an occurrence (else `null`); positive → Nth occurrence **after**; negative → Nth occurrence **before** (uses `-1*$index`).

### Return
`\DateTime|null`

### Exceptions
- `\InvalidArgumentException` - Thrown when `$index` is not numeric with message 'Malformed index (must be a numeric)'.

### Example
```php
$rrule = new RRule(['FREQ' => 'DAILY', 'DTSTART' => '2024-01-01', 'COUNT' => 30]);

$rrule->getNthOccurrenceFrom('2024-01-10', 0);   // 2024-01-10 (it is an occurrence)
$rrule->getNthOccurrenceFrom('2024-01-10', 2);   // 2024-01-12
$rrule->getNthOccurrenceFrom('2024-01-10', -2);  // 2024-01-08
```
```

--------------------------------

### getRule() method signature

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rrule.md

Returns the original rule array exactly as passed to the constructor (upper-cased keys, merged with defaults), including DTSTART. Return type: array. No parameters, no exceptions.

```php
public function getRule()
```

--------------------------------

### createFromRfcString() static method signature

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rrule.md

Takes an RFC 5545 string and returns either an RRule or an RSet. When $force_rset is false, detection heuristic: zero RRULE occurrences → RRule; more than one RRULE, or a single one accompanied by EXDATE/RDATE/EXRULE → RSet; otherwise RRule. Return type: RRule|RSet.

```php
static public function createFromRfcString($string, $force_rset = false)
```

--------------------------------

### RRule Class API

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/errors.md

Documentation for the RRule class constructor and key methods, including error handling patterns.

```APIDOC
## [CONSTRUCTOR] RRule::__construct()

### Description
Creates a new RRule instance from an RFC 5545 RRULE string or an array of rule parts. Throws \InvalidArgumentException for invalid input.

### Method
Constructor

### Endpoint
`new RRule(array|string $rule)`

### Parameters
#### Constructor Parameters
- **$rule** (array|string) - Required - The RRULE definition as an array (e.g. `['FREQ' => 'DAILY', 'COUNT' => 0]`) or an RFC 5545 string.

### Request Example
```php
$rrule = new RRule(['FREQ' => 'DAILY', 'COUNT' => 0]);
```

### Response
#### Success Response
- Returns a new RRule instance.

#### Error Response
- **\InvalidArgumentException** - Thrown when input validation fails (e.g. COUNT must be >= 1).

### Error Handling
- Catch `\InvalidArgumentException` for all input validation failures.

## [METHOD] RRule::getOccurrences()

### Description
Returns all occurrences of the rule. Throws \LogicException if called on an infinite rule.

### Method
GET

### Endpoint
`RRule::getOccurrences()`

### Parameters
None.

### Request Example
```php
$infinite = new RRule(['FREQ' => 'DAILY']);
$infinite->getOccurrences();
```

### Response
#### Success Response
- Returns an array of DateTime objects representing all occurrences.

#### Error Response
- **\LogicException** - Thrown when attempting to read an unbounded (infinite) rule.

### Error Handling
- Guard with `isFinite()`/`isInfinite()` before calling to avoid `\LogicException`.

## [METHOD] RRule::humanReadable()

### Description
Converts the rule to a human-readable string. Throws \RuntimeException for environment failures (missing translations, broken intl).

### Method
GET

### Endpoint
`RRule::humanReadable(array $options = [])`

### Parameters
#### Optional Parameters
- **$options** (array) - Optional - An associative array with a `locale` key (e.g. `['locale' => 'xx_XX']`).

### Request Example
```php
$rrule->humanReadable(['locale' => 'xx_XX']);
```

### Response
#### Success Response
- Returns a human-readable string representation of the rule.

#### Error Response
- **\RuntimeException** - Thrown when the locale is missing or intl is broken.

### Error Handling
- Treat `\RuntimeException` as recoverable; fall back to a default locale (e.g. `'en'`).

## [METHOD] RRule::count()

### Description
Returns the number of occurrences in the rule. Throws \LogicException if called on an infinite rule.

### Method
GET

### Endpoint
`RRule::count()`

### Parameters
None.

### Request Example
```php
$rrule->count();
```

### Response
#### Success Response
- Returns an integer count of occurrences.

#### Error Response
- **\LogicException** - Thrown when attempting to count an unbounded (infinite) rule.

### Error Handling
- Guard with `isFinite()`/`isInfinite()` before calling to avoid `\LogicException`.

## [METHOD] RRule::isFinite() / RRule::isInfinite()

### Description
Checks whether the rule is finite or infinite. Useful for guarding against \LogicException.

### Method
GET

### Endpoint
`RRule::isFinite()` / `RRule::isInfinite()`

### Parameters
None.

### Request Example
```php
if ($rrule->isFinite()) {
    $occurrences = $rrule->getOccurrences();
}
```

### Response
#### Success Response
- Returns a boolean indicating whether the rule is finite or infinite.

### Error Handling
- No exceptions are thrown by these methods.

## [METHOD] RRule::offsetSet() / RRule::offsetUnset()

### Description
ArrayAccess methods for setting and unsetting rule parts. Not recommended for use.

### Method
PUT / DELETE

### Endpoint
`RRule::offsetSet($offset, $value)` / `RRule::offsetUnset($offset)`

### Parameters
#### Path Parameters
- **$offset** (mixed) - Required - The array key to set or unset.
- **$value** (mixed) - Required for offsetSet - The value to set.

### Request Example
```php
// Not recommended; avoid using these methods.
```

### Response
#### Success Response
- No return value.

### Error Handling
- Never call these methods; they are not recommended for consumer use.
```

--------------------------------

### Access RRule occurrences by index with array access

Source: https://github.com/rlanvin/php-rrule/wiki/RRule

Use array access on an RRule object to get the Nth occurrence directly. isset() returns false for out-of-range indices.

```php
use RRule\RRule;

// every 2 days, 5 times
$rrule = new RRule([
    'freq' => RRule::DAILY,
    'interval' => 2,
    'count' => 5,
    'dtstart' => '1997-09-02 09:00:00'
]);

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

var_dump(isset($rrule[0])); // bool(true)
var_dump(isset($rrule[5])); // bool(false)
```

--------------------------------

### Create a MONTHLY RRule with BYDAY

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/configuration.md

Creates a recurrence rule that occurs every two months on the first and last Sunday, with times at 9:00 and 17:00. The DTSTART must be a parseable value; UNTIL is inclusive and mutually exclusive with COUNT. The BYDAY signed ordinals are allowed with MONTHLY frequency.

```php
use RRule\RRule;

$rrule = new RRule([
    'FREQ'       => 'MONTHLY',
    'INTERVAL'   => 2,
    'DTSTART'    => '2015-06-01 09:00:00',
    'UNTIL'      => '2016-06-01',
    'BYDAY'      => ['1SU', '-1SU'],   // first and last Sunday
    'BYHOUR'     => [9, 17],
]);
```

--------------------------------

### Require Composer autoloader

Source: https://github.com/rlanvin/php-rrule/blob/master/README.md

Autoloads the php-rrule library after installation via Composer. This line is typically placed at the top of a PHP script to enable use of the library's classes.

```php
require 'vendor/autoload.php';
```

--------------------------------

### Create RSet from RFC-like string

Source: https://github.com/rlanvin/php-rrule/wiki/RSet

Creates an RSet object from a multi-line string with RRULE, EXRULE, RDATE, EXDATE, and DTSTART properties. Lines are separated by \n or \r\n. DTSTART is optional; if omitted, the second argument can specify a date, otherwise the current date is used.

```php
$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"
);
```

--------------------------------

### Import RSet class

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rset.md

Imports the RSet class from the RRule namespace.

```php
use RRule\RSet;
```

--------------------------------

### rfcString() method signature

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rrule.md

Formats the rule as an RFC 5545 property block. When $include_timezone is true, DTSTART is emitted with a TZID= parameter (or as UTC ...Z for UTC/GMT time zones); UNTIL is emitted in UTC per the RFC. When false, local DTSTART/UNTIL without timezone are emitted. Return type: string — e.g. "DTSTART;TZID=Europe/Helsinki:20150601T000000\nRRULE:FREQ=MONTHLY;COUNT=6". The DTSTART: prefix is only emitted when a DTSTART exists; default-valued INTERVAL=1 and WKST=MO are omitted.

```php
public function rfcString($include_timezone = true)
```

--------------------------------

### Iterate over RRule occurrences with foreach

Source: https://github.com/rlanvin/php-rrule/wiki/RRule

Use RRule in a foreach loop to get occurrences one at a time. The rule must have UNTIL or COUNT to avoid an infinite loop. Occurrences are DateTime objects in the same timezone as DTSTART.

```php
use RRule\RRule;

// every 2 days, 5 times
$rrule = new RRule([
    'freq' => RRule::DAILY,
    'interval' => 2,
    'count' => 5,
    'dtstart' => '1997-09-02 09:00:00'
]);

foreach ( $rrule 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
// Mon, 08 Sep 1997 09:00:00 +0000
// Wed, 10 Sep 1997 09:00:00 +0000
```

--------------------------------

### Parse RRULE with DTSTART using RfcParser::parseRRule()

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rfc-parser.md

Parses a complete RFC 5545 RRULE string that includes a DTSTART with timezone and an RRULE with FREQ, INTERVAL, BYDAY, and UNTIL. The resulting array contains DateTime objects for DTSTART and UNTIL, and string values for the other properties.

```php
use RRule\RfcParser;

$parts = RfcParser::parseRRule(
    "DTSTART;TZID=Europe/Helsinki:19970902T090000\nRRULE:FREQ=WEEKLY;INTERVAL=2;BYDAY=TU,TH;UNTIL=19971224T000000Z"
);
// $parts['DTSTART'] => DateTime 1997-09-02 09:00 Europe/Helsinki
// $parts['FREQ']    => 'WEEKLY'
// $parts['INTERVAL']=> '2'
// $parts['BYDAY']   => 'TU,TH'
// $parts['UNTIL']   => DateTime 1997-12-24 00:00 UTC
```

--------------------------------

### RSet Constructor

Source: https://github.com/rlanvin/php-rrule/wiki/RSet

Creates a new RSet object, optionally from an RFC-like string.

```APIDOC
## RSet Constructor

### Description
Creates a new RSet object. Can be created empty or from an RFC-like string.

### Method
Constructor

### Endpoint
`new RSet($string = null, $defaultDtstart = null)`

### Parameters
- **$string** (string|null) - Optional - RFC-like string with lines separated by \n or \r\n. Each line defines a property: RRULE, EXRULE, RDATE, EXDATE, DTSTART.
- **$defaultDtstart** (DateTime|string|null) - Optional - Default start date used when DTSTART is not present in the string. Defaults to current date.

### Request Example
```php
$rset = new RSet(
    "DTSTART;TZID=America/New_York:19970901T090000\nRRULE:FREQ=DAILY;COUNT=3\nEXRULE:FREQ=DAILY;INTERVAL=2;COUNT=1\nEXDATE;TZID=America/New_York:19970903T090000\nRDATE;TZID=America/New_York:19970904T090000"
);
```

### Response
Returns a new RSet object.

```

--------------------------------

### Access RSet occurrences by index with ArrayAccess

Source: https://github.com/rlanvin/php-rrule/wiki/RSet

Use array syntax to directly access the Nth occurrence. The example shows that index 0 returns the first occurrence, index 3 returns the fourth, and isset returns false for index 4 because the set has only 4 occurrences after excluding the EXDATE.

```php
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)
```

--------------------------------

### Create RRule: every 2 weeks on Monday

Source: https://github.com/rlanvin/php-rrule/wiki/RRule

Instantiates an RRule object with a weekly frequency, Monday as the day, and an interval of 2. The constructor accepts an associative array with rule parts as keys; keys and values are case-insensitive.

```php
$rrule = new RRule\RRule([
    'freq' => 'weekly',
    'byday' => 'MO',
    'interval' => 2
]);
```

--------------------------------

### Construct RSet from RFC block

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rset.md

Constructs an RSet from an RFC 5545 block containing DTSTART, RRULE, and EXDATE. The count is 9 because the excluded Monday is removed.

```php
use RRule\RSet;

$set = new RSet("DTSTART:19970902T090000\nRRULE:FREQ=WEEKLY;BYDAY=MO,WE;COUNT=10\nEXDATE:19970908T090000");
echo $set->count(); // 9 (the Monday is excluded)
```

--------------------------------

### Iterate over RSet with foreach

Source: https://github.com/rlanvin/php-rrule/wiki/RSet

Use foreach to efficiently iterate over occurrences one at a time. The set includes a rule with COUNT=5 and an EXDATE, so the output skips the excluded date. Warning: if any rule lacks UNTIL or COUNT, the loop is infinite and must be exited manually.

```php
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
```

--------------------------------

### new RRule

Source: https://github.com/rlanvin/php-rrule/wiki/RRule

Creates a new RRule instance with the given recurrence rule parameters.

```APIDOC
## RRule Constructor

### Description
Creates a new RRule instance with the given recurrence rule parameters.

### Method
new RRule

### Parameters
- **$rule** (array) - Required - An associative array containing recurrence rule parameters such as 'freq', 'count', 'dtstart', 'until', 'bymonth', 'byday'.

### Example
```php
$rrule = new RRule([
    'freq' => 'daily',
    'count' => 10,
    'dtstart' => '1997-09-02 09:00:00'
]);
```
```

--------------------------------

### getExDates() method signature

Source: https://github.com/rlanvin/php-rrule/blob/master/_autodocs/api-reference/rset.md

Returns an array of \DateTime objects representing the current EXDATE list.

```php
public function getExDates()
```
Tokens:
Raw