Holiday
extends Event
in package
Represents a holiday.
Table of Contents
Constants
- TYPE_BIRTHDAY = 2
- TYPE_EVENT = 0
- TYPE_HOLIDAY = 1
Properties
- $adjustments : array<string|int, mixed>
- $allday : bool
- $board : int
- $byday_items : array<string|int, mixed>
- $byday_num_options : array<string|int, mixed>
- $duration : TimeInterval
- $enabled : bool
- $frequency_units : array<string|int, mixed>
- $groups : array<string|int, mixed>
- $id : int
- $id_first : string
- $loaded : array<string|int, mixed>
- $location : string
- $member : int
- $modified_time : int
- $msg : int
- $name : string
- $recurrence_iterator : RecurrenceIterator
- $rrule_presets : array<string|int, mixed>
- $selected_occurrence : EventOccurrence
- $sorted_weekdays : array<string|int, mixed>
- $special_rrule : array<string|int, mixed>
- $special_rrules : array<string|int, mixed>
- $start : Time
- $title : string
- $topic : int
- $type : int
- $uid : string
- $exdates : array<string|int, mixed>
- $prop_aliases : array<string|int, mixed>
- $rdates : array<string|int, mixed>
- $rrule : string
- $sequence : int
- $use_permissions : bool
- $view_end : DateTimeImmutable
- $view_start : DateTimeImmutable
Methods
- __construct() : object
- Constructor.
- __get() : mixed
- Gets custom property values.
- __isset() : bool
- Checks whether a custom property has been set.
- __set() : void
- Sets custom properties.
- __unset() : void
- Unsets custom properties.
- addOccurrence() : void
- Adds an arbitrary date to the recurrence set.
- changeUntil() : void
- Updates the RRule to set a new UNTIL date.
- constructFromICal() : array<string|int, mixed>
- Constructs instances of this class from iCalendar data.
- count() : int
- Gets the total number of holidays recorded in the database.
- create() : void
- Creates a holiday and saves it to the database.
- easter() : array<string|int, mixed>|null
- Computes the Western and Eastern dates of Easter for the given year.
- export() : string
- Builds iCalendar components for events, including recurrence info.
- foldICalLine() : string
- Folds lines of text to fit within the iCalendar line width restraint.
- get() : Generator<string|int, Holiday>
- Generator that yields instances of this class.
- getAllVisibleOccurrences() : Generator<string|int, EventOccurrence>
- Returns a generator that yields all occurrences of the event between $this->view_start and $this->view_end.
- getFirstOccurrence() : EventOccurrence|false
- Gets the first occurrence of the event.
- getLastOccurrence() : EventOccurrence|false
- Gets the last occurrence of the event.
- getOccurrence() : EventOccurrence|false
- Gets an occurrence of the event by its recurrence ID.
- getOccurrencesInRange() : Generator<string|int, EventOccurrence>
- Gets events within the given date range, and returns a generator that yields all occurrences of those events within that range.
- getRecurrenceEnd() : Time
- Gets the date after which no more occurrences happen.
- getUpcomingOccurrence() : EventOccurrence|false
- Gets the next occurrence of the event after the date given by $when.
- import() : array<string|int, mixed>
- Imports holidays from iCalendar data and saves them to the database.
- list() : array<string|int, mixed>
- Returns Holiday instances for the holidays recorded in the database.
- load() : array<string|int, mixed>
- Loads holidays by ID number.
- modify() : void
- Modifies a holiday.
- offsetExists() : bool
- Checks whether a property has been set when object is accessed as an array.
- offsetGet() : mixed
- Gets properties when object is accessed as an array.
- offsetSet() : void
- Sets properties when object is accessed as an array.
- offsetUnset() : void
- Unsets properties when object is accessed as an array.
- remove() : void
- Removes a holiday.
- removeOccurrence() : void
- Removes a date from the recurrence set.
- save() : void
- Saves this event to the database.
- setRequestedStartAndDuration() : void
- Set the start and end dates and times for a posted event for insertion into the database.
- createOccurrence() : EventOccurrence
- Creates an EventOccurrence object for the given start time.
- createRecurrenceIterator() : bool
- Sets $this->recurrence_iterator, but only if all necessary properties have been set.
- handleSpecialRRule() : void
- Some holidays have special values in the 'rrule' field in the database.
- queryData() : Generator<string|int, array<string|int, mixed>>
- Generator that runs queries about event data and yields the result rows.
- setRequestedRDatesAndExDates() : void
- Set the RDates for a posted event for insertion into the database.
- setRequestedRRule() : void
- Set the RRule for a posted event for insertion into the database.
- standardizeEventOptions() : array<string|int, mixed>
- Standardizes various forms of input about start and end times.
Constants
TYPE_BIRTHDAY
public
mixed
TYPE_BIRTHDAY
= 2
TYPE_EVENT
public
mixed
TYPE_EVENT
= 0
TYPE_HOLIDAY
public
mixed
TYPE_HOLIDAY
= 1
Properties
$adjustments
public
array<string|int, mixed>
$adjustments
= []
Info about adjustments to apply to subsets of occurrences of this event.
Keys are the IDs of EventOccurrence objects. Values are EventAdjustment objects.
$allday
public
bool
$allday
= true
Whether this is an all-day event.
$board
public
int
$board
= 0
ID of the board that contains the event's topic.
$byday_items
public
array<string|int, mixed>
$byday_items
= []
Existing values for the BYDAY_* select menus in the UI.
$byday_num_options
public
array<string|int, mixed>
$byday_num_options
= []
Possible values for the BYDAY_num select menu in the UI.
$duration
public
TimeInterval
$duration
A TimeInterval object representing the duration of each occurrence of the event.
$enabled
public
bool
$enabled
= true
Whether this holiday is enabled.
$frequency_units
public
array<string|int, mixed>
$frequency_units
= ['DAILY' => 'day(s)', 'WEEKLY' => 'week(s)', 'MONTHLY' => 'month(s)', 'YEARLY' => 'year(s)']
Maps frequency values to unit strings.
The descriptions will be overwritten using the language strings in Lang::$txt['calendar_repeat_frequency_units']
$groups
public
array<string|int, mixed>
$groups
= []
IDs of member groups that can view this event.
$id
public
int
$id
This event's ID number.
$id_first
public
string
$id_first
The recurrence ID of the first individual occurrence of the event.
See RFC 5545, section 3.8.4.4.
$loaded
public
static array<string|int, mixed>
$loaded
= []
All loaded instances of this class.
$location
public
string
$location
= ''
Location of this event.
$member
public
int
$member
= 0
ID of the member who created this event.
$modified_time
public
int
$modified_time
= 0
Timestamp when the event's message was last modified.
$msg
public
int
$msg
= 0
ID of the first message in the event's topic.
$name
public
string
$name
= ''
Displayed name of the member who created this event.
$recurrence_iterator
public
RecurrenceIterator
$recurrence_iterator
A RecurrenceIterator object to get individual occurrences of the event.
$rrule_presets
public
array<string|int, mixed>
$rrule_presets
= ['never' => 'Never', 'FREQ=DAILY' => 'Every day', 'FREQ=WEEKLY' => 'Every week', 'FREQ=MONTHLY' => 'Every month', 'FREQ=YEARLY' => 'Every year', 'custom' => 'Custom...']
Possible values for the RRule select menu in the UI.
The descriptions will be overwritten using the language strings in Lang::$txt['calendar_repeat_rrule_presets']
$selected_occurrence
public
EventOccurrence
$selected_occurrence
When editing an event, this is the occurrence being edited.
$sorted_weekdays
public
array<string|int, mixed>
$sorted_weekdays
= []
Weekdays sorted according to the WKST value, or the current user's preferences if WKST is not already set.
$special_rrule
public
array<string|int, mixed>
$special_rrule
Used to override the usual handling of RRule values.
Value is an array containing a 'base' and a 'modifier'. The 'base' is one of the keys from self:special_rrules. The 'modifier' is a + or - sign followed by a duration string, or null.
$special_rrules
public
static array<string|int, mixed>
$special_rrules
= [
// Easter (Western)
'EASTER_W' => ['txt_key' => 'calendar_repeat_easter_w', 'group' => ['EASTER_W', 'EASTER_E']],
// Easter (Eastern)
'EASTER_E' => ['txt_key' => 'calendar_repeat_easter_e', 'group' => ['EASTER_W', 'EASTER_E']],
]
Known special values for the 'rrule' field. These are used when dealing with recurring events whose recurrence patterns cannot be expressed using RFC 5545's notation.
Keys are special strings that may be found in the 'rrule' field in the database.
Values are arrays containing the following options:
'txt_key' indicates a Lang::$txt string for this special RRule. If not set, defaults to 'calendar_repeat_special'.
'group' indicates special RRules that should be listed as alternatives to each other. For example, 'group' => ['EASTER_W', 'EASTER_E'] means that the Western and Eastern ways of calculating the date of Easter should be listed as the two options for Easter. If not set, defaults to a list containing only the special string itself.
$start
public
Time
$start
A Time object representing the start of the event's first occurrence.
$title
public
string
$title
= ''
Title of this event.
$topic
public
int
$topic
= 0
ID of the event's topic.
$type
public
int
$type
= self::TYPE_HOLIDAY
This event's type. Value must be one of the parent class's TYPE_* constants.
$uid
public
string
$uid
This event's UID string. (Note: UID is not synonymous with UUID!)
For events that were created by SMF, the UID will in fact be a UUID. But if the event was imported from iCal data, it could be anything.
$exdates
protected
array<string|int, mixed>
$exdates
= []
Arbitrary dates to exclude from the recurrence set.
$prop_aliases
protected
array<string|int, mixed>
$prop_aliases
= ['id_event' => 'id', 'eventid' => 'id', 'id_board' => 'board', 'id_topic' => 'topic', 'id_first_msg' => 'msg', 'id_member' => 'member', 'poster' => 'member', 'real_name' => 'name', 'realname' => 'name', 'member_groups' => 'groups', 'allowed_groups' => 'groups', 'start_object' => 'start', 'end_object' => 'end']
Alternate names for some object properties.
$rdates
protected
array<string|int, mixed>
$rdates
= []
Arbitrary dates to add to the recurrence set.
$rrule
protected
string
$rrule
= ''
The recurrence rule for the RecurrenceIterator.
$sequence
protected
int
$sequence
= 0
Increments every time the event is modified.
$use_permissions
protected
bool
$use_permissions
= true
Whether we checked access permissions when loading this event.
$view_end
protected
DateTimeImmutable
$view_end
Occurrences after this date will be skipped when returning results.
$view_start
protected
DateTimeImmutable
$view_start
Occurrences before this date will be skipped when returning results.
Methods
__construct()
Constructor.
public
__construct([int $id = 0 ][, array<string|int, mixed> $props = [] ]) : object
Parameters
- $id : int = 0
-
The ID number of the event.
- $props : array<string|int, mixed> = []
-
Properties to set for this event.
Return values
object —An instance of this class.
__get()
Gets custom property values.
public
__get(string $prop) : mixed
Parameters
- $prop : string
-
The property name.
Return values
mixed —The property value.
__isset()
Checks whether a custom property has been set.
public
__isset(string $prop) : bool
Parameters
- $prop : string
-
The property name.
Return values
bool —Whether the property has been set.
__set()
Sets custom properties.
public
__set(string $prop, mixed $value) : void
Parameters
- $prop : string
-
The property name.
- $value : mixed
-
The value to set.
__unset()
Unsets custom properties.
public
__unset(string $prop) : void
Parameters
- $prop : string
-
The property name.
addOccurrence()
Adds an arbitrary date to the recurrence set.
public
addOccurrence(DateTimeInterface $date[, DateInterval|null $duration = null ]) : void
Used for making exceptions to the general recurrence rule.
Parameters
- $date : DateTimeInterface
-
The date to add.
- $duration : DateInterval|null = null
-
Optional duration for this occurrence. Only necessary if the duration for this occurrence differs from the usual duration of the event.
changeUntil()
Updates the RRule to set a new UNTIL date.
public
changeUntil(DateTimeInterface $until) : void
This is somewhat complicated because it requires updating the recurrence iterator and its underlying RRule.
Parameters
- $until : DateTimeInterface
constructFromICal()
Constructs instances of this class from iCalendar data.
public
static constructFromICal(string $ics[, int|null $type = null ]) : array<string|int, mixed>
Parameters
- $ics : string
-
Some iCalendar data (e.g. the content of an ICS file).
- $type : int|null = null
-
Forces all events to be imported as the specified type. Values can be one of this class's TYPE_* constants, or null for auto.
Return values
array<string|int, mixed> —An array of instances of this class.
count()
Gets the total number of holidays recorded in the database.
public
static count() : int
Return values
int —The total number of known holidays.
create()
Creates a holiday and saves it to the database.
public
static create(array<string|int, mixed> $eventOptions) : void
Does not check permissions.
Parameters
- $eventOptions : array<string|int, mixed>
-
Event data ('title', 'start_date', etc.)
easter()
Computes the Western and Eastern dates of Easter for the given year.
public
static easter([int|null $year = null ][, string|null $type = null ]) : array<string|int, mixed>|null
In the returned array:
-
'Western' gives the Gregorian calendar date of Easter as observed by Roman Catholic and Protestant Christians. This is computed using the Gregorian algorithm and presented as a Gregorian date.
-
'Eastern' gives the Gregorian calendar date of Easter as observed by Eastern Orthodox Christians. This is computed using the Julian algorithm and then converted to a Gregorian date.
-
'Julian' gives the same date as 'Eastern', except that it is left as a Julian calendar date rather than being converted to a Gregorian date.
For years before 1583, 'Eastern' and 'Western' are the same.
Beware that using 'Julian' to construct a \DateTime object will probably have unexpected results. \DateTime only understands Gregorian calendar dates.
Instead, use 'Julian' to show dates as they were reckoned in a given country prior to that country's adoption of the Gregorian calendar. For example, Greece didn't adopt the Gregorian calendar until 1923, so you can use the Julian date to show the date of Easter in 1920 the way that Greek people would have reckoned it at the time (March 29 rather than March 11).
Caveats:
-
The computation of the date of Easter was not standardized until A.D. 325, and some regional variations persisted until approx. A.D. 664.
-
Western Christians did not all adopt the Gregorian method of computing the date of Easter at the same time, which means that the observed date of Easter varied across regions in Western Europe for several centuries. Moreover, the adoption of the Gregorian calendar by a country as its civil calendar does not necessarily coincide with the adoption of the Gregorian date of Easter in that country. Choosing the correct computation for a particular location in a particular year therefore requires historical knowledge.
Parameters
- $year : int|null = null
-
The year. Must be greater than 30.
- $type : string|null = null
-
One of 'Western', 'Eastern', or 'Julian'. If set to 'Western', 'Eastern', or 'Julian', only that date will be returned. Otherwise all three dates will be returned in an array.
Return values
array<string|int, mixed>|null —Info about the Western and/or Eastern dates for Easter, or null on error.
export()
Builds iCalendar components for events, including recurrence info.
public
export() : string
Return values
string —One or more VEVENT components for an iCalendar document.
foldICalLine()
Folds lines of text to fit within the iCalendar line width restraint.
public
static foldICalLine(string $line) : string
Parameters
- $line : string
-
The line of text to fold.
Return values
string —$line The folded version of $line.
get()
Generator that yields instances of this class.
public
static get(string $low_date, string $high_date[, bool $only_enabled = true ][, array<string|int, mixed> $query_customizations = [] ]) : Generator<string|int, Holiday>
Parameters
- $low_date : string
-
The low end of the range, inclusive, in YYYY-MM-DD format.
- $high_date : string
-
The high end of the range, inclusive, in YYYY-MM-DD format.
- $only_enabled : bool = true
-
If true, only show enabled holidays.
- $query_customizations : array<string|int, mixed> = []
-
Customizations to the SQL query.
Return values
Generator<string|int, Holiday> —Iterating over result gives Holiday instances.
getAllVisibleOccurrences()
Returns a generator that yields all occurrences of the event between $this->view_start and $this->view_end.
public
getAllVisibleOccurrences() : Generator<string|int, EventOccurrence>
Return values
Generator<string|int, EventOccurrence> —Iterating over result gives EventOccurrence instances.
getFirstOccurrence()
Gets the first occurrence of the event.
public
getFirstOccurrence() : EventOccurrence|false
Return values
EventOccurrence|false —EventOccurrence object, or false on error.
getLastOccurrence()
Gets the last occurrence of the event.
public
getLastOccurrence() : EventOccurrence|false
Return values
EventOccurrence|false —EventOccurrence object, or false on error.
getOccurrence()
Gets an occurrence of the event by its recurrence ID.
public
getOccurrence(string $id) : EventOccurrence|false
Parameters
- $id : string
-
The recurrence ID string.
Return values
EventOccurrence|false —EventOccurrence object, or false on error.
getOccurrencesInRange()
Gets events within the given date range, and returns a generator that yields all occurrences of those events within that range.
public
static getOccurrencesInRange(string $low_date, string $high_date[, bool $only_enabled = true ][, array<string|int, mixed> $query_customizations = [] ]) : Generator<string|int, EventOccurrence>
Parameters
- $low_date : string
-
The low end of the range, inclusive, in YYYY-MM-DD format.
- $high_date : string
-
The high end of the range, inclusive, in YYYY-MM-DD format.
- $only_enabled : bool = true
-
If true, only show enabled holidays.
- $query_customizations : array<string|int, mixed> = []
-
Customizations to the SQL query.
Return values
Generator<string|int, EventOccurrence> —Iterating over result gives EventOccurrence instances.
getRecurrenceEnd()
Gets the date after which no more occurrences happen.
public
getRecurrenceEnd() : Time
Return values
Time —When the recurrence ends.
getUpcomingOccurrence()
Gets the next occurrence of the event after the date given by $when.
public
getUpcomingOccurrence([DateTimeInterface|null $when = null ]) : EventOccurrence|false
Parameters
- $when : DateTimeInterface|null = null
-
The moment from which we should start looking for the next occurrence. If null, uses now.
Return values
EventOccurrence|false —An EventOccurrence object, or false if no occurrences happen after $when.
import()
Imports holidays from iCalendar data and saves them to the database.
public
static import(string $ics) : array<string|int, mixed>
Parameters
- $ics : string
-
Some iCalendar data (e.g. the content of an ICS file).
Return values
array<string|int, mixed> —An array of instances of this class.
list()
Returns Holiday instances for the holidays recorded in the database.
public
static list(int $start, int $items_per_page[, string $sort = 'cal.title ASC, cal.start_date ASC' ]) : array<string|int, mixed>
Parameters
- $start : int
-
The item to start with (for pagination purposes)
- $items_per_page : int
-
How many items to show on each page
- $sort : string = 'cal.title ASC, cal.start_date ASC'
-
A string indicating how to sort the results
Return values
array<string|int, mixed> —An array of Holiday instances.
load()
Loads holidays by ID number.
public
static load(int|array<string|int, mixed> $id[, bool $is_topic = false ][, bool $use_permissions = true ]) : array<string|int, mixed>
Parameters
- $id : int|array<string|int, mixed>
-
ID number of the holiday event.
- $is_topic : bool = false
-
Ignored.
- $use_permissions : bool = true
-
Ignored.
Return values
array<string|int, mixed> —Instances of this class for the loaded events.
modify()
Modifies a holiday.
public
static modify(int $id, array<string|int, mixed> &$eventOptions) : void
Does not check permissions.
Parameters
- $id : int
-
The ID of the event.
- $eventOptions : array<string|int, mixed>
-
An array of event information.
offsetExists()
Checks whether a property has been set when object is accessed as an array.
public
offsetExists(mixed $prop) : bool
Parameters
- $prop : mixed
-
The property name.
Return values
booloffsetGet()
Gets properties when object is accessed as an array.
public
& offsetGet(mixed $prop) : mixed
Parameters
- $prop : mixed
-
The property name.
Return values
mixed —A reference to the property.
offsetSet()
Sets properties when object is accessed as an array.
public
offsetSet(mixed $prop, mixed $value) : void
Parameters
- $prop : mixed
-
The property name.
- $value : mixed
-
The value to set.
offsetUnset()
Unsets properties when object is accessed as an array.
public
offsetUnset(mixed $prop) : void
Parameters
- $prop : mixed
-
The property name.
remove()
Removes a holiday.
public
static remove(int $id) : void
Does not check permissions.
Parameters
- $id : int
-
The event's ID.
removeOccurrence()
Removes a date from the recurrence set.
public
removeOccurrence(DateTimeInterface $date) : void
Used for making exceptions to the general recurrence rule.
Parameters
- $date : DateTimeInterface
-
The date to remove.
save()
Saves this event to the database.
public
save() : void
setRequestedStartAndDuration()
Set the start and end dates and times for a posted event for insertion into the database.
public
static setRequestedStartAndDuration(array<string|int, mixed> &$eventOptions) : void
- Validates all date and times given to it.
- Makes sure events do not exceed the maximum allowed duration (if any).
- If passed an array that defines any time or date parameters, they will be used. Otherwise, gets the values from $_POST.
Parameters
- $eventOptions : array<string|int, mixed>
-
An array of optional time and date parameters (span, start_year, end_month, etc., etc.)
createOccurrence()
Creates an EventOccurrence object for the given start time.
protected
createOccurrence(DateTimeInterface $start[, TimeInterval|null $duration = null ]) : EventOccurrence
Parameters
- $start : DateTimeInterface
-
The start time.
- $duration : TimeInterval|null = null
-
Custom duration for this occurrence. If this is left null, the duration of the parent event will be used.
Return values
EventOccurrencecreateRecurrenceIterator()
Sets $this->recurrence_iterator, but only if all necessary properties have been set.
protected
createRecurrenceIterator() : bool
Return values
bool —Whether the recurrence iterator was created successfully.
handleSpecialRRule()
Some holidays have special values in the 'rrule' field in the database.
protected
handleSpecialRRule(mixed $id, mixed &$props) : void
This method detects them and does whatever special handling is necessary.
Parameters
- $id : mixed
- $props : mixed
queryData()
Generator that runs queries about event data and yields the result rows.
protected
static queryData(array<string|int, mixed> $selects[, array<string|int, mixed> $params = [] ][, array<string|int, mixed> $joins = [] ][, array<string|int, mixed> $where = [] ][, array<string|int, mixed> $order = [] ][, array<string|int, mixed> $group = [] ][, int|string $limit = 0 ]) : Generator<string|int, array<string|int, mixed>>
Parameters
- $selects : array<string|int, mixed>
-
Table columns to select.
- $params : array<string|int, mixed> = []
-
Parameters to substitute into query text.
- $joins : array<string|int, mixed> = []
-
Zero or more complete JOIN clauses. E.g.: 'LEFT JOIN {db_prefix}categories AS c ON (c.id_cat = b.id_cat)' Note that 'FROM {db_prefix}boards AS b' is always part of the query.
- $where : array<string|int, mixed> = []
-
Zero or more conditions for the WHERE clause. Conditions will be placed in parentheses and concatenated with AND. If this is left empty, no WHERE clause will be used.
- $order : array<string|int, mixed> = []
-
Zero or more conditions for the ORDER BY clause. If this is left empty, no ORDER BY clause will be used.
- $group : array<string|int, mixed> = []
-
Zero or more conditions for the GROUP BY clause. If this is left empty, no GROUP BY clause will be used.
- $limit : int|string = 0
-
Maximum number of results to retrieve. If this is left empty, all results will be retrieved.
Return values
Generator<string|int, array<string|int, mixed>> —Iterating over the result gives database rows.
setRequestedRDatesAndExDates()
Set the RDates for a posted event for insertion into the database.
protected
static setRequestedRDatesAndExDates(Event $event) : void
Parameters
- $event : Event
-
An event that is being created or modified.
setRequestedRRule()
Set the RRule for a posted event for insertion into the database.
protected
static setRequestedRRule(array<string|int, mixed> &$eventOptions) : void
Parameters
- $eventOptions : array<string|int, mixed>
-
An array of optional time and date parameters (span, start_year, end_month, etc., etc.)
standardizeEventOptions()
Standardizes various forms of input about start and end times.
protected
static standardizeEventOptions(array<string|int, mixed> $input) : array<string|int, mixed>
The $input array can include any combination of the following keys: allday, timezone, year, month, day, hour, minute, second, start_datetime, start_date, start_time, start_year, start_month, start_day, start_hour, start_minute, start_second, end_datetime, end_date, end_time, end_year, end_month, end_day, end_hour, end_minute, end_second.
The returned array will replace all of those with the following: start_date, start_time, end_date, end_time, timezone, allday.
If $input contains keys besides the ones mentioned above, those key-value pairs will remain unchanged in the returned array.
Parameters
- $input : array<string|int, mixed>
-
Array of info about event start and end times.
Return values
array<string|int, mixed> —Standardized version of $input array.