Bitrix API

Rule

This class is responsible for providing a programmatic way of building, parsing, and handling RRULEs.

http://www.ietf.org/rfc/rfc2445.txt

Information, not contained in the built/parsed RRULE, necessary to determine the various recurrence instance start time and dates are derived from the DTSTART property (default: \DateTime()).

For example, "FREQ=YEARLY;BYMONTH=1" doesn't specify a specific day within the month or a time. This information would be the same as what is specified for DTSTART.

BYxxx rule parts modify the recurrence in some manner. BYxxx rule parts for a period of time which is the same or greater than the frequency generally reduce or limit the number of occurrences of the recurrence generated.

For example, "FREQ=DAILY;BYMONTH=1" reduces the number of recurrence instances from all days (if BYMONTH tag is not present) to all days in January.

BYxxx rule parts for a period of time less than the frequency generally increase or expand the number of occurrences of the recurrence.

For example, "FREQ=YEARLY;BYMONTH=1,2" increases the number of days within the yearly recurrence set from 1 (if BYMONTH tag is not present) to 2.

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.

Here is an example of evaluating multiple BYxxx rule parts.

FREQ=YEARLY;INTERVAL=2;BYMONTH=1;BYDAY=SU;BYHOUR=8,9;BYMINUTE=30

First, the "INTERVAL=2" would be applied to "FREQ=YEARLY" to arrive at "every other year". Then, "BYMONTH=1" would be applied to arrive at "every January, every other year". Then, "BYDAY=SU" would be applied to arrive at "every Sunday in January, every other year". Then, "BYHOUR=8,9" would be applied to arrive at "every Sunday in January at 8 AM and 9 AM, every other year". Then, "BYMINUTE=30" would be applied to arrive at "every Sunday in January at 8:30 AM and 9:30 AM, every other year". Then, lacking information from RRULE, the second is derived from DTSTART, to end up in "every Sunday in January at 8:30:00 AM and 9:30:00 AM, every other year". Similarly, if the BYMINUTE, BYHOUR, BYDAY, BYMONTHDAY or BYMONTH rule part were missing, the appropriate minute, hour, day or month would have been retrieved from the "DTSTART" property.

Example: The following is a rule which specifies 10 meetings which occur every other day:

FREQ=DAILY;COUNT=10;INTERVAL=2

Table of Contents

Constants

TZ_FIXED  = 'fixed'
TZ_FLOAT  = 'floating'

Properties

$freqs  : mixed

Methods

__construct()  : mixed
Construct a new Rule.
createFromArray()  : Rule
Create a Rule object based on a RRULE array.
createFromString()  : Rule
Create a Rule object based on a RRULE string.
getByDay()  : array<string|int, mixed>
Get an array of days of the week (SU, MO, TU, ..)
getByDayTransformedToWeekdays()  : array<string|int, mixed>
Get an array of Weekdays
getByHour()  : array<string|int, mixed>
Get an array of hours of the day.
getByMinute()  : array<string|int, mixed>
Get an array of minutes within an hour.
getByMonth()  : array<string|int, mixed>
Get an array of months of the year.
getByMonthDay()  : array<string|int, mixed>
Get an array of days of the month.
getBySecond()  : array<string|int, mixed>
Get an array of seconds within a minute.
getBySetPosition()  : array<string|int, mixed>
Get the array of values which corresponds to the nth occurrence within the set of events specified by the rule.
getByWeekNumber()  : array<string|int, mixed>
Get an array of ordinals specifying weeks of the year.
getByYearDay()  : array<string|int, mixed>
Get an array of days of the year.
getCount()  : int|null
Get the number of occurrences at which the recurrence is range-bound.
getEndDate()  : DateTimeInterface|null
getExDates()  : array<string|int, DateExclusion>
Get the array of dates that will not be included in a recurrence set.
getFreq()  : int
Get the type of recurrence rule (as integer).
getFreqAsText()  : string
Get the type of recurrence rule (as text).
getInterval()  : int
Get the interval that represents how often the recurrence rule repeats.
getRDates()  : array<string|int, DateInclusion>
Get the array of dates that will be included in a recurrence set.
getStartDate()  : DateTimeInterface
getString()  : string
Get the RRULE as a string
getTimezone()  : null|string
Get timezone to use for \DateTimeInterface objects that are UTC.
getUntil()  : DateTimeInterface|null
Get the \DateTimeInterface that the recurrence lasts until.
getWeekStart()  : string
Get the day on which the workweek starts.
getWeekStartAsNum()  : int
Get the day on which the workweek starts, as an integer from 0-6, 0 being Monday and 6 being Sunday.
hasByMonth()  : mixed
loadFromArray()  : Rule
Populate the object based on a RRULE array.
loadFromString()  : Rule
Populate the object based on a RRULE string.
parseString()  : array<string|int, mixed>
Parse string for parts
repeatsIndefinitely()  : bool
setByDay()  : $this
This rule specifies an array of days of the week;
setByHour()  : $this
This rule specifies an array of hours of the day.
setByMinute()  : $this
This rule specifies an array of minutes within an hour.
setByMonth()  : $this
This rule specifies an array of months of the year.
setByMonthDay()  : $this
This rule specifies an array of days of the month.
setBySecond()  : $this
This rule specifies an array of seconds within a minute.
setBySetPosition()  : $this
This rule specifies an array 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.
setByWeekNumber()  : $this
This rule specifies an array of ordinals specifying weeks of the year.
setByYearDay()  : $this
This rule specifies an array of days of the year.
setCount()  : $this
The count defines the number of occurrences at which to range-bound the recurrence. The DTSTART counts as the first occurrence.
setEndDate()  : $this
This date specifies the last possible instance in the recurrence set.
setExDates()  : $this
This rule specifies an array of exception dates that will not be included in a recurrence set.
setFreq()  : $this
Identifies the type of recurrence rule.
setInterval()  : $this
The interval represents how often the recurrence rule repeats.
setRDates()  : $this
This rule specifies an array of dates that will be included in a recurrence set.
setStartDate()  : $this
This date specifies the first instance in the recurrence set.
setTimezone()  : $this
setUntil()  : $this
Define a \DateTimeInterface value which bounds the recurrence rule in an inclusive manner. If the value specified is synchronized with the specified recurrence, this DateTime becomes the last instance of the recurrence. If not present, and a COUNT is also not present, the RRULE is considered to repeat forever.
setWeekStart()  : $this
This rule specifies the day on which the workweek starts.

Constants

TZ_FIXED

public mixed TZ_FIXED = 'fixed'

TZ_FLOAT

public mixed TZ_FLOAT = 'floating'

Properties

$freqs

public static mixed $freqs = array('YEARLY' => 0, 'MONTHLY' => 1, 'WEEKLY' => 2, 'DAILY' => 3, 'HOURLY' => 4, 'MINUTELY' => 5, 'SECONDLY' => 6)

Methods

__construct()

Construct a new Rule.

public __construct([string $rrule = null ][, string|DateTimeInterface|null $startDate = null ][, string|DateTimeInterface|null $endDate = null ][, string $timezone = null ]) : mixed
Parameters
$rrule : string = null

RRULE string

$startDate : string|DateTimeInterface|null = null
$endDate : string|DateTimeInterface|null = null
$timezone : string = null
Tags
throws
InvalidRRule

createFromArray()

Create a Rule object based on a RRULE array.

public static createFromArray(array<string|int, mixed> $rrule[, string|DateTimeInterface $startDate = null ][, DateTimeInterface|null $endDate = null ][, string $timezone = null ]) : Rule
Parameters
$rrule : array<string|int, mixed>

RRULE array

$startDate : string|DateTimeInterface = null
$endDate : DateTimeInterface|null = null
$timezone : string = null
Tags
throws
InvalidRRule
Return values
Rule

createFromString()

Create a Rule object based on a RRULE string.

public static createFromString(string $rrule[, string|DateTimeInterface $startDate = null ][, DateTimeInterface|null $endDate = null ][, string $timezone = null ]) : Rule
Parameters
$rrule : string

RRULE string

$startDate : string|DateTimeInterface = null
$endDate : DateTimeInterface|null = null
$timezone : string = null
Tags
throws
InvalidRRule
Return values
Rule

getByDay()

Get an array of days of the week (SU, MO, TU, ..)

public getByDay() : array<string|int, mixed>
Return values
array<string|int, mixed>

getByDayTransformedToWeekdays()

Get an array of Weekdays

public getByDayTransformedToWeekdays() : array<string|int, mixed>
Tags
throws
InvalidWeekday
Return values
array<string|int, mixed> —

of Weekdays

getByHour()

Get an array of hours of the day.

public getByHour() : array<string|int, mixed>
Return values
array<string|int, mixed>

getByMinute()

Get an array of minutes within an hour.

public getByMinute() : array<string|int, mixed>
Return values
array<string|int, mixed>

getByMonth()

Get an array of months of the year.

public getByMonth() : array<string|int, mixed>
Return values
array<string|int, mixed>

getByMonthDay()

Get an array of days of the month.

public getByMonthDay() : array<string|int, mixed>
Return values
array<string|int, mixed>

getBySecond()

Get an array of seconds within a minute.

public getBySecond() : array<string|int, mixed>
Return values
array<string|int, mixed>

getBySetPosition()

Get the array of values which corresponds to the nth occurrence within the set of events specified by the rule.

public getBySetPosition() : array<string|int, mixed>
Return values
array<string|int, mixed>

getByWeekNumber()

Get an array of ordinals specifying weeks of the year.

public getByWeekNumber() : array<string|int, mixed>
Return values
array<string|int, mixed>

getByYearDay()

Get an array of days of the year.

public getByYearDay() : array<string|int, mixed>
Return values
array<string|int, mixed>

getCount()

Get the number of occurrences at which the recurrence is range-bound.

public getCount() : int|null
Return values
int|null

getEndDate()

public getEndDate() : DateTimeInterface|null
Return values
DateTimeInterface|null

getExDates()

Get the array of dates that will not be included in a recurrence set.

public getExDates() : array<string|int, DateExclusion>
Return values
array<string|int, DateExclusion>

getFreq()

Get the type of recurrence rule (as integer).

public getFreq() : int
Return values
int

getFreqAsText()

Get the type of recurrence rule (as text).

public getFreqAsText() : string
Return values
string

getInterval()

Get the interval that represents how often the recurrence rule repeats.

public getInterval() : int
Return values
int

getRDates()

Get the array of dates that will be included in a recurrence set.

public getRDates() : array<string|int, DateInclusion>
Return values
array<string|int, DateInclusion>

getStartDate()

public getStartDate() : DateTimeInterface
Return values
DateTimeInterface

getString()

Get the RRULE as a string

public getString([string $timezoneType = self::TZ_FLOAT ]) : string
Parameters
$timezoneType : string = self::TZ_FLOAT
Return values
string

getTimezone()

Get timezone to use for \DateTimeInterface objects that are UTC.

public getTimezone() : null|string
Return values
null|string

getUntil()

Get the \DateTimeInterface that the recurrence lasts until.

public getUntil() : DateTimeInterface|null
Return values
DateTimeInterface|null

getWeekStart()

Get the day on which the workweek starts.

public getWeekStart() : string
Return values
string

getWeekStartAsNum()

Get the day on which the workweek starts, as an integer from 0-6, 0 being Monday and 6 being Sunday.

public getWeekStartAsNum() : int
Return values
int

hasByMonth()

public hasByMonth() : mixed

loadFromArray()

Populate the object based on a RRULE array.

public loadFromArray(mixed $parts) : Rule
Parameters
$parts : mixed
Tags
throws
InvalidRRule
Return values
Rule

loadFromString()

Populate the object based on a RRULE string.

public loadFromString(string $rrule) : Rule
Parameters
$rrule : string

RRULE string

Tags
throws
InvalidRRule
Return values
Rule

parseString()

Parse string for parts

public parseString(string $rrule) : array<string|int, mixed>
Parameters
$rrule : string
Tags
throws
InvalidRRule
Return values
array<string|int, mixed>

repeatsIndefinitely()

public repeatsIndefinitely() : bool
Return values
bool

setByDay()

This rule specifies an array of days of the week;

public setByDay(array<string|int, mixed> $byDay) : $this

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.

DO NOT MIX DAYS AND DAYS WITH MODIFIERS. This is not supported.

Parameters
$byDay : array<string|int, mixed>

Array of days of the week

Tags
throws
InvalidRRule
Return values
$this

setByHour()

This rule specifies an array of hours of the day.

public setByHour(array<string|int, mixed> $byHour) : $this

Valid values are 0 to 23.

Parameters
$byHour : array<string|int, mixed>

Array of hours of the day

Return values
$this

setByMinute()

This rule specifies an array of minutes within an hour.

public setByMinute(array<string|int, mixed> $byMinute) : $this

Valid values are 0 to 59.

Parameters
$byMinute : array<string|int, mixed>

Array of minutes within an hour

Return values
$this

setByMonth()

This rule specifies an array of months of the year.

public setByMonth(array<string|int, mixed> $byMonth) : $this

Valid values are 1 to 12.

Parameters
$byMonth : array<string|int, mixed>

Array of months of the year from 1 to 12

Return values
$this

setByMonthDay()

This rule specifies an array of days of the month.

public setByMonthDay(array<string|int, mixed> $byMonthDay) : $this

Valid values are 1 to 31 or -31 to -1.

For example, -10 represents the tenth to the last day of the month.

Parameters
$byMonthDay : array<string|int, mixed>

Array of days of the month from -31 to 31

Return values
$this

setBySecond()

This rule specifies an array of seconds within a minute.

public setBySecond(array<string|int, mixed> $bySecond) : $this

Valid values are 0 to 59.

Parameters
$bySecond : array<string|int, mixed>

Array of seconds within a minute

Return values
$this

setBySetPosition()

This rule specifies an array 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.

public setBySetPosition(array<string|int, mixed> $bySetPosition) : $this

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

Each BYSETPOS value can include a positive or negative integer. If present, this indicates the nth occurrence of the specific occurrence within the set of events specified by the rule.

Parameters
$bySetPosition : array<string|int, mixed>

Array of values which corresponds to the nth occurrence within the set of events specified by the rule.

Return values
$this

setByWeekNumber()

This rule specifies an array of ordinals specifying weeks of the year.

public setByWeekNumber(array<string|int, mixed> $byWeekNumber) : $this

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 setWeekStart). Week number one of the calendar year is the first week which contains at least four days in that calendar year. This rule 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.

Parameters
$byWeekNumber : array<string|int, mixed>

Array of ordinals specifying weeks of the year.

Return values
$this

setByYearDay()

This rule specifies an array of days of the year.

public setByYearDay(array<string|int, mixed> $byYearDay) : $this

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).

Parameters
$byYearDay : array<string|int, mixed>

Array of days of the year from -1 to 306

Return values
$this

setCount()

The count defines the number of occurrences at which to range-bound the recurrence. The DTSTART counts as the first occurrence.

public setCount(int $count) : $this

Either COUNT or UNTIL may be specified, but COUNT and UNTIL MUST NOT both be specified.

Parameters
$count : int

Number of occurrences

Return values
$this

setEndDate()

This date specifies the last possible instance in the recurrence set.

public setEndDate(DateTimeInterface|null $endDate) : $this
Parameters
$endDate : DateTimeInterface|null

Date of the last possible instance in the recurrence

Return values
$this

setExDates()

This rule specifies an array of exception dates that will not be included in a recurrence set.

public setExDates(array<string|int, string>|array<string|int, DateExclusion> $exDates) : $this
Parameters
$exDates : array<string|int, string>|array<string|int, DateExclusion>

Array of dates that will not be included in the recurrence set.

Return values
$this

setFreq()

Identifies the type of recurrence rule.

public setFreq(string|int $freq) : $this

May be one of:

  • Frequency::SECONDLY to specify repeating events based on an interval of a second or more.
  • Frequency::MINUTELY to specify repeating events based on an interval of a minute or more.
  • Frequency::HOURLY to specify repeating events based on an interval of an hour or more.
  • Frequency::DAILY to specify repeating events based on an interval of a day or more.
  • Frequency::WEEKLY to specify repeating events based on an interval of a week or more.
  • Frequency::MONTHLY to specify repeating events based on an interval of a month or more.
  • Frequency::YEAR to specify repeating events based on an interval of a year or more.
Parameters
$freq : string|int

Frequency of recurrence.

Tags
throws
InvalidArgument
Return values
$this

setInterval()

The interval represents how often the recurrence rule repeats.

public setInterval(int $interval) : $this

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.

Parameters
$interval : int

Positive integer that represents how often the recurrence rule repeats.

Tags
throws
InvalidArgument
Return values
$this

setRDates()

This rule specifies an array of dates that will be included in a recurrence set.

public setRDates(array<string|int, string>|array<string|int, DateInclusion> $rDates) : $this
Parameters
$rDates : array<string|int, string>|array<string|int, DateInclusion>

Array of dates that will be included in the recurrence set.

Return values
$this

setStartDate()

This date specifies the first instance in the recurrence set.

public setStartDate(DateTimeInterface|null $startDate[, bool|null $includeInString = null ]) : $this
Parameters
$startDate : DateTimeInterface|null

Date of the first instance in the recurrence

$includeInString : bool|null = null

If true, include as DTSTART when calling getString()

Return values
$this

setUntil()

Define a \DateTimeInterface value which bounds the recurrence rule in an inclusive manner. If the value specified is synchronized with the specified recurrence, this DateTime becomes the last instance of the recurrence. If not present, and a COUNT is also not present, the RRULE is considered to repeat forever.

public setUntil(DateTimeInterface $until) : $this

Either UNTIL or COUNT may be specified, but UNTIL and COUNT MUST NOT both be specified.

Parameters
$until : DateTimeInterface

The upper bound of the recurrence.

Return values
$this

setWeekStart()

This rule specifies the day on which the workweek starts.

public setWeekStart(string $weekStart) : $this

Valid values are MO, TU, WE, TH, FR, SA and SU.

This is significant when a WEEKLY RRULE has an interval greater than 1, and a BYDAY rule part is specified.

This is also significant when in a YEARLY RRULE when a BYWEEKNO rule is specified. The default value is MO.

Parameters
$weekStart : string

The day on which the workweek starts.

Tags
throws
InvalidArgument
Return values
$this 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results