Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.0.x will end 8 May 2023 (12 months).
  • Bug fixes for security issues in 4.0.x will end 13 November 2023 (18 months).
  • PHP version: minimum PHP 7.3.0 Note: the minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is also supported.
/calendar/classes/ -> rrule_manager.php (source)

[Source view]

Defines calendar class to manage recurrence rule (rrule) during ical imports.

Copyright: 2014 onwards Ankit Agarwal
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 1357 lines (51 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class

rrule_manager:: (33 methods):
  __construct()
  parse_rrule()
  create_events()
  parse_rrule_property()
  set_frequency()
  get_day()
  set_until()
  set_count()
  set_interval()
  set_bysecond()
  set_byminute()
  set_byhour()
  set_byday()
  set_bymonthday()
  set_byyearday()
  set_byweekno()
  set_bymonth()
  set_bysetpos()
  validate_rules()
  create_recurring_events()
  generate_recurring_event_times()
  get_interval()
  has_by_rules()
  filter_by_month()
  filter_by_weekno()
  filter_by_yearday()
  filter_by_monthday()
  filter_by_day()
  apply_hour_minute_second_rules()
  filter_by_setpos()
  get_period_bounds_list()
  in_bounds()
  get_period_boundaries()


Class: rrule_manager  - X-Ref

Defines calendar class to manage recurrence rule (rrule) during ical imports.

Please refer to RFC 2445 {@link http://www.ietf.org/rfc/rfc2445.txt} for detail explanation of the logic.
Here is a basic extract from it to explain various params:-
recur = "FREQ"=freq *(
; either UNTIL or COUNT may appear in a 'recur',
; but UNTIL and COUNT MUST NOT occur in the same 'recur'
( ";" "UNTIL" "=" enddate ) /
( ";" "COUNT" "=" 1*DIGIT ) /
; the rest of these keywords are optional,
; but MUST NOT occur more than once
( ";" "INTERVAL" "=" 1*DIGIT )          /
( ";" "BYSECOND" "=" byseclist )        /
( ";" "BYMINUTE" "=" byminlist )        /
( ";" "BYHOUR" "=" byhrlist )           /
( ";" "BYDAY" "=" bywdaylist )          /
( ";" "BYMONTHDAY" "=" bymodaylist )    /
( ";" "BYYEARDAY" "=" byyrdaylist )     /
( ";" "BYWEEKNO" "=" bywknolist )       /
( ";" "BYMONTH" "=" bymolist )          /
( ";" "BYSETPOS" "=" bysplist )         /
( ";" "WKST" "=" weekday )              /
( ";" x-name "=" text )
)

freq       = "SECONDLY" / "MINUTELY" / "HOURLY" / "DAILY"
/ "WEEKLY" / "MONTHLY" / "YEARLY"
enddate    = date
enddate    =/ date-time            ;An UTC value
byseclist  = seconds / ( seconds *("," seconds) )
seconds    = 1DIGIT / 2DIGIT       ;0 to 59
byminlist  = minutes / ( minutes *("," minutes) )
minutes    = 1DIGIT / 2DIGIT       ;0 to 59
byhrlist   = hour / ( hour *("," hour) )
hour       = 1DIGIT / 2DIGIT       ;0 to 23
bywdaylist = weekdaynum / ( weekdaynum *("," weekdaynum) )
weekdaynum = [([plus] ordwk / minus ordwk)] weekday
plus       = "+"
minus      = "-"
ordwk      = 1DIGIT / 2DIGIT       ;1 to 53
weekday    = "SU" / "MO" / "TU" / "WE" / "TH" / "FR" / "SA"
;Corresponding to SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY,
;FRIDAY, SATURDAY and SUNDAY days of the week.
bymodaylist = monthdaynum / ( monthdaynum *("," monthdaynum) )
monthdaynum = ([plus] ordmoday) / (minus ordmoday)
ordmoday   = 1DIGIT / 2DIGIT       ;1 to 31
byyrdaylist = yeardaynum / ( yeardaynum *("," yeardaynum) )
yeardaynum = ([plus] ordyrday) / (minus ordyrday)
ordyrday   = 1DIGIT / 2DIGIT / 3DIGIT      ;1 to 366
bywknolist = weeknum / ( weeknum *("," weeknum) )
weeknum    = ([plus] ordwk) / (minus ordwk)
bymolist   = monthnum / ( monthnum *("," monthnum) )
monthnum   = 1DIGIT / 2DIGIT       ;1 to 12
bysplist   = setposday / ( setposday *("," setposday) )
setposday  = yeardaynum

__construct($rrule)   X-Ref
Constructor for the class

param: string $rrule Recurrence rule

parse_rrule()   X-Ref
Parse the recurrence rule and setup all properties.


create_events($passedevent)   X-Ref
Create events for specified rrule.

param: calendar_event $passedevent Properties of event to create.

parse_rrule_property($prop)   X-Ref
Parse a property of the recurrence rule.

param: string $prop property string with type-value pair

set_frequency($freq)   X-Ref
Sets Frequency property.

param: string $freq Frequency of event

get_day($daystring)   X-Ref
Gets the day from day string.

return: string Day represented by the parameter.
param: string $daystring Day string (MO, TU, etc)

set_until($until)   X-Ref
Sets the UNTIL rule.

param: string $until The date string representation of the UNTIL rule.

set_count($count)   X-Ref
Sets the COUNT rule.

param: string $count The count value.

set_interval($intervalstr)   X-Ref
Sets the INTERVAL rule.

The INTERVAL rule part contains a positive integer representing how often the recurrence rule repeats.
The default value is "1", meaning:
- every second for a SECONDLY rule, or
- every minute for a MINUTELY rule,
- every hour for an HOURLY rule,
- every day for a DAILY rule,
- every week for a WEEKLY rule,
- every month for a MONTHLY rule and
- every year for a YEARLY rule.

param: string $intervalstr The value for the interval rule.

set_bysecond($bysecond)   X-Ref
Sets the BYSECOND rule.

The BYSECOND rule part specifies a comma-separated list of seconds within a minute.
Valid values are 0 to 59.

param: string $bysecond Comma-separated list of seconds within a minute.

set_byminute($byminute)   X-Ref
Sets the BYMINUTE rule.

The BYMINUTE rule part specifies a comma-separated list of seconds within an hour.
Valid values are 0 to 59.

param: string $byminute Comma-separated list of minutes within an hour.

set_byhour($byhour)   X-Ref
Sets the BYHOUR rule.

The BYHOUR rule part specifies a comma-separated list of hours of the day.
Valid values are 0 to 23.

param: string $byhour Comma-separated list of hours of the day.

set_byday($byday)   X-Ref
Sets the BYDAY rule.

The BYDAY rule part specifies a comma-separated list of days of the week;
- MO indicates Monday;
- TU indicates Tuesday;
- WE indicates Wednesday;
- TH indicates Thursday;
- FR indicates Friday;
- SA indicates Saturday;
- SU indicates Sunday.

Each BYDAY value can also be preceded by a positive (+n) or negative (-n) integer.
If present, this indicates the nth occurrence of the specific day within the MONTHLY or YEARLY RRULE.
For example, within a MONTHLY rule, +1MO (or simply 1MO) represents the first Monday within the month,
whereas -1MO represents the last Monday of the month.
If an integer modifier is not present, it means all days of this type within the specified frequency.
For example, within a MONTHLY rule, MO represents all Mondays within the month.

param: string $byday Comma-separated list of days of the week.

set_bymonthday($bymonthday)   X-Ref
Sets the BYMONTHDAY rule.

The BYMONTHDAY rule part specifies a comma-separated list of days of the month.
Valid values are 1 to 31 or -31 to -1. For example, -10 represents the tenth to the last day of the month.

param: string $bymonthday Comma-separated list of days of the month.

set_byyearday($byyearday)   X-Ref
Sets the BYYEARDAY rule.

The BYYEARDAY rule part specifies a comma-separated list of days of the year.
Valid values are 1 to 366 or -366 to -1. For example, -1 represents the last day of the year (December 31st)
and -306 represents the 306th to the last day of the year (March 1st).

param: string $byyearday Comma-separated list of days of the year.

set_byweekno($byweekno)   X-Ref
Sets the BYWEEKNO rule.

The BYWEEKNO rule part specifies a comma-separated list of ordinals specifying weeks of the year.
Valid values are 1 to 53 or -53 to -1. This corresponds to weeks according to week numbering as defined in [ISO 8601].
A week is defined as a seven day period, starting on the day of the week defined to be the week start (see WKST).
Week number one of the calendar year is the first week which contains at least four (4) days in that calendar year.
This rule part is only valid for YEARLY rules. For example, 3 represents the third week of the year.

Note: Assuming a Monday week start, week 53 can only occur when Thursday is January 1 or if it is a leap year and Wednesday
is January 1.

param: string $byweekno Comma-separated list of number of weeks.

set_bymonth($bymonth)   X-Ref
Sets the BYMONTH rule.

The BYMONTH rule part specifies a comma-separated list of months of the year.
Valid values are 1 to 12.

param: string $bymonth Comma-separated list of months of the year.

set_bysetpos($bysetpos)   X-Ref
Sets the BYSETPOS rule.

The BYSETPOS rule part specifies a comma-separated list of values which corresponds to the nth occurrence within the set of
events specified by the rule. Valid values are 1 to 366 or -366 to -1.
It MUST only be used in conjunction with another BYxxx rule part.

For example "the last work day of the month" could be represented as: RRULE:FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1

param: string $bysetpos Comma-separated list of values.

validate_rules()   X-Ref
Validate the rules as a whole.


create_recurring_events($event, $eventtimes)   X-Ref
Creates calendar events for the recurring events.

param: stdClass $event The parent event.
param: int[] $eventtimes The timestamps of the recurring events.

generate_recurring_event_times($event)   X-Ref
Generates recurring events based on the parent event and the RRULE set.

If multiple BYxxx rule parts are specified, then after evaluating the specified FREQ and INTERVAL rule parts,
the BYxxx rule parts are applied to the current set of evaluated occurrences in the following order:
BYMONTH, BYWEEKNO, BYYEARDAY, BYMONTHDAY, BYDAY, BYHOUR, BYMINUTE, BYSECOND and BYSETPOS;
then COUNT and UNTIL are evaluated.

return: array The list of timestamps that obey the given RRULE.
param: stdClass $event The event object.

get_interval()   X-Ref
Generates a DateInterval object based on the FREQ and INTERVAL rules.

return: DateInterval

has_by_rules()   X-Ref
Determines whether the RRULE has BYxxx rules or not.

return: bool True if there is one or more BYxxx rules to process. False, otherwise.

filter_by_month($eventdates)   X-Ref
Filter event times based on the BYMONTH rule.

return: int[] Array of filtered timestamps.
param: int[] $eventdates Timestamps of event times to be filtered.

filter_by_weekno($eventdates)   X-Ref
Filter event times based on the BYWEEKNO rule.

return: int[] Array of filtered timestamps.
param: int[] $eventdates Timestamps of event times to be filtered.

filter_by_yearday($eventdates)   X-Ref
Filter event times based on the BYYEARDAY rule.

return: int[] Array of filtered timestamps.
param: int[] $eventdates Timestamps of event times to be filtered.

filter_by_monthday($eventdates)   X-Ref
Filter event times based on the BYMONTHDAY rule.

return: int[] Array of filtered timestamps.
param: int[] $eventdates The event times to be filtered.

filter_by_day($event, $eventdates, $until)   X-Ref
Filter event times based on the BYDAY rule.

return: int[] Array of filtered timestamps.
param: stdClass $event The parent event.
param: int[] $eventdates The event times to be filtered.
param: int $until Event times generation limit date.

apply_hour_minute_second_rules(DateTime $eventdatetime, $eventdates)   X-Ref
Applies BYHOUR, BYMINUTE and BYSECOND rules to the calculated event dates.
Defaults to the DTSTART's hour/minute/second component when not defined.

return: array List of updated event timestamps that contain the time component of the event times.
param: DateTime $eventdatetime The parent event DateTime object pertaining to the DTSTART.
param: int[] $eventdates Array of candidate event date timestamps.

filter_by_setpos($event, $eventtimes, $until)   X-Ref
Filter event times based on the BYSETPOS rule.

return: int[] Array of filtered timestamps.
param: stdClass $event The parent event.
param: int[] $eventtimes The event times to be filtered.
param: int $until Event times generation limit date.

get_period_bounds_list($eventtime, $until)   X-Ref
Gets the list of period boundaries covered by the recurring events.

return: array List of period bounds, with start and next properties.
param: int $eventtime The event timestamp.
param: int $until The end timestamp.

in_bounds($time, $bounds)   X-Ref
Determine whether the date-time in question is within the bounds of the periods that are covered by the RRULE.

return: bool
param: int $time The timestamp to be evaluated.
param: array $bounds Array of period boundaries covered by the RRULE.

get_period_boundaries($eventtime)   X-Ref
Determines the start and end DateTime objects that serve as references to determine whether a calculated event timestamp
falls on the period defined by these DateTimes objects.

return: DateTime[]
param: int $eventtime Unix timestamp of the event time.