Home

This library offers a small, complete, and very fast, implementation of the recurrence rules documented in the iCalendar RFC. It is heavily based on python-dateutil.

RRule

Creation

The constructor accepts an associative array with all the keywords defined in the RFC ("rule parts") as key. The keys and the values are case insensitive.

Example:

// every 2 weeks on Monday, starting now
$rrule = new RRule([
    'freq' => 'weekly',
    'byday' => 'MO',
    'interval' => 2
]);

The only required key is FREQUENCY, which must be one of the following strings: YEARLY, MONTHLY, WEEKLY, DAILY, HOURLY, MINUTELY or SECONDLY, or one of the following constants RRule::YEARLY, RRule::MONTHLY, RRule::WEEKLY, RRule::DAILY, RRule::HOURLY, RRule::MINUTELY or RRule::SECONDLY.

Here is a quick description the other parameters. For more details, check the iCalendar RFC.

Name	Description
DTSTART	The recurrence start date and time. Can be given as a string understandable by PHP's DateTime constructor (for example 2015-07-01 14:46:30) a UNIX Timestamp (as int) or a DateTime object. Default is now.
INTERVAL	The interval between each FREQUENCY iteration. For example, when using YEARLY, an interval of 2 means once every two years, but with HOURLY, it means once every two hours. Default is 1.
WKST	The week start day. Must be one of the following strings MO, TU, WE, TH, FR, SA, SU. This will affect recurrences based on weekly periods. Default is MO (Monday).
COUNT	How many occurrences will be generated.
UNTIL	The limit of the recurrence. Accepts the same formats as DTSTART. If a recurrence instance happens to be the same the date given, this will be the last occurrence.
BYMONTH	The month(s) to apply the recurrence to, from 1 (January) to 12 (December). It can be a single value, or a comma-separated list or an array.
BYWEEKNO	The week number(s) to apply the recurrence to, from 1 to 53 or -53 to -1. Negative values mean that the counting start from the end of the year, so -1 means "the last week of the year". Week numbers have the meaning described in ISO8601, that is, the first week of the year is that containing at least four days of the new year. Week numbers are affected by the WKST setting. It can be a single value, or a comma-separated list or an array. Warning: negative week numbers are not fully tested yet.
BYYEARDAY	The day(s) of the year to apply the recurrence to, from 1 to 366 or -366 to -1. Negative values mean that the count starts from the end of the year, so -1 means "the last day of the year". It can be a single value, or a comma-separated list or an array.
BYMONTHDAY	The day(s) of the month to apply the recurrence to, from 1 to 31 or -31 to -1. Negative values mean that the count starts from the end of the month, so -1 means "the last day the month". It can be a single value, or a comma-separated list or an array.
BYDAY	The day(s) of the week to apply the recurrence to from MO (Monday) to SU (Sunday). Must be one of the following strings: MO, TU, WE, TH, FR, SA, SU. It can be a single value, or a comma-separated list or an array.
BYHOUR	The hour(s) to apply the recurrence to, from 0 to 23. It can be a single value, or a comma-separated list or an array.
BYMINUTE	The minute(s) to apply the recurrence to, from 0 to 59. It can be a single value, or a comma-separated list or an array.
BYSECOND	The second(s) to apply the recurrence to, from 0 to 60. It can be a single value, or a comma-separated list or an array. Warning: leap second (i.e. second 60) support is not fully tested.
BYSETPOS	The Nth occurrence (or occurrences) within the valid occurrences inside a frequency period. It can be a single value, or a comma-separated list or an array. Negative values mean that the count starts from the set. For example, a bysetpos of -1 if combined with a MONTHLY frequency, and a byweekday of MO, TU, WE, TH, FR, will result in the last work day of every month.

Iteration

An instance of RRule can be used directly in a foreach loop to obtain occurrences.

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

Array access

Methods

The following methods are available:

Examples

Notes

• Unlike documented in the RFC, and like in the Python version, the starting datetime (DTSTART) is not the first recurrence instance, unless it does fit in the specified rules. This behavior makes more sense than otherwise and is easier to work with. This will only change the results if COUNT or BYSETPOS are used.
• The current algorithm to compute occurrences is faster at lower frequencies and slower at higher the frequencies. So YEARLY is faster that MONTHLY which is faster than WEEKLY and so on. So if you want to achieve the fastest calculation time, whenever possible, try to use the lowest possible frequency. For example, to get "every day in january" it is slightly faster to write ['freq' => 'yearly','bymonth' => 1,'bymonthday' => range(1,31)] rather than ['freq' => 'daily','bymonth' => 1].
• Computing all occurrences of rule might get noticeably slow with very high frequencies (MINUTELY or SECONDELY) if the rule last a long period of time (such as many years).
• Some perfectly RFC-compliant rules are actually impossible and will produce no result. For example "every year, on week 40, in February" (week 40 will never occur in February). In a cases like that, the library will still try to find occurrences, because the rule is technically valid, before returning an empty set once all the possibilities have been exhausted.