Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.3.x will end 7 October 2024 (12 months).
  • Bug fixes for security issues in 4.3.x will end 21 April 2025 (18 months).
  • PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.2.x is supported too.
/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.

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

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.

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

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.

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

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.

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

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.

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