Documentation

Birthday extends Event
in package

SMF

Represents a member's birthday.

Constants

ID_MODIFIER = 10 ** 6
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
$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
$enabled : bool
$exdates : array<string|int, mixed>
$keep_all : bool
$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() : mixed: 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.
create() : void: Not applicable. Birthday info is updated via the user's profile.
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, Event>: 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 events from iCalendar data and saves them to the database.
load() : array<string|int, mixed>: Loads a member's birthday.
modify() : void: Not applicable. Birthday info is updated via the user's profile.
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: Not applicable. Birthday info is updated via the user's profile.
removeOccurrence() : void: Removes a date from the recurrence set.
save() : void: Not applicable. Birthday info is updated via the user's profile.
setRequestedStartAndDuration() : void: Not applicable. Birthday info is updated via the user's profile.
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: Not applicable. Birthday info is updated via the user's profile.
setRequestedRRule() : void: Not applicable. Birthday info is updated via the user's profile.
standardizeEventOptions() : array<string|int, mixed>: Not applicable. Birthday info is updated via the user's profile.

ID_MODIFIER


    public
        int
    ID_MODIFIER
    = 10 ** 6

A value to add to the ID in order to avoid conflicts with regular events.

TYPE_BIRTHDAY


    public
        mixed
    TYPE_BIRTHDAY
    = 2

TYPE_EVENT


    public
        mixed
    TYPE_EVENT
    = 0

TYPE_HOLIDAY


    public
        mixed
    TYPE_HOLIDAY
    = 1

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

$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_BIRTHDAY

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.

$enabled


    protected
        bool
    $enabled
     = true

Whether this event is enabled. Always true for events and birthdays. May be false for holidays.

$exdates


    protected
        array<string|int, mixed>
    $exdates
     = []

Arbitrary dates to exclude from the recurrence set.

$keep_all


    protected
    static    bool
    $keep_all
     = false

If true, Birthday::get() will not destroy instances after yielding them. This is used internally by Birthday::getOccurrencesInRange().

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

__construct()

Constructor.


    public
                    __construct([int $id = 0 ][, array<string|int, mixed> $props = [] ]) : mixed

Parameters

$id : int = 0: The ID number of the event.
$props : array<string|int, mixed> = []: Properties to set for this event.

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

create()

Not applicable. Birthday info is updated via the user's profile.


    public
            static        create(array<string|int, mixed> $eventOptions) : void

Parameters

$eventOptions : array<string|int, mixed>: Event data ('title', 'start_date', etc.)

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 $use_permissions = true ][, array<string|int, mixed> $query_customizations = [] ]) : Generator<string|int, Event>

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.
$use_permissions : bool = true: Ignored.
$query_customizations : array<string|int, mixed> = []: Customizations to the SQL query.

Return values

Generator<string|int, Event> —

Iterating over result gives Event 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 $use_permissions = 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.
$use_permissions : bool = true: Whether to use permissions. Default: true.
$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 events 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.

load()

Loads a member's birthday.


    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 member.
$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()

Not applicable. Birthday info is updated via the user's profile.


    public
            static        modify(int $id, array<string|int, mixed> &$eventOptions) : void

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

bool

offsetGet()

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

Not applicable. Birthday info is updated via the user's profile.


    public
            static        remove(int $id) : void

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

Not applicable. Birthday info is updated via the user's profile.


    public
                    save() : void

setRequestedStartAndDuration()

Not applicable. Birthday info is updated via the user's profile.


    public
            static        setRequestedStartAndDuration(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.)

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

EventOccurrence

createRecurrenceIterator()

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

Not applicable. Birthday info is updated via the user's profile.


    protected
            static        setRequestedRDatesAndExDates(Event $event) : void

Parameters

$event : Event: An event that is being created or modified.

setRequestedRRule()

Not applicable. Birthday info is updated via the user's profile.


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

Not applicable. Birthday info is updated via the user's profile.


    protected
            static        standardizeEventOptions(array<string|int, mixed> $input) : array<string|int, mixed>

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.

Birthday extends Event in package SMF

Table of Contents

Constants

Properties

Methods

Constants

ID_MODIFIER

TYPE_BIRTHDAY

TYPE_EVENT

TYPE_HOLIDAY

Properties

$adjustments

$allday

$board

$byday_items

$byday_num_options

$duration

$frequency_units

$groups

$id

$id_first

$loaded

$location

$member

$modified_time

$msg

$name

$recurrence_iterator

$rrule_presets

$selected_occurrence

$sorted_weekdays

$special_rrule

$special_rrules

$start

$title

$topic

$type

$uid

$enabled

$exdates

$keep_all

$prop_aliases

$rdates

$rrule

$sequence

$use_permissions

$view_end

$view_start

Methods

__construct()

Parameters

__get()

Parameters

Return values

__isset()

Parameters

Return values

__set()

Parameters

__unset()

Parameters

addOccurrence()

Parameters

changeUntil()

Parameters

constructFromICal()

Parameters

Return values

create()

Parameters

export()

Return values

foldICalLine()

Parameters

Return values

get()

Parameters

Return values

getAllVisibleOccurrences()

Return values

Birthday extends Event
in package

SMF