Documentation

Event
in package
implements ArrayAccess Uses BackwardCompatibility, ArrayAccessHelper

Represents a calendar event.

Tags
todo

Implement recurring events.

todo

Use this class to represent holidays and birthdays. They're all-day events, after all.

Table of Contents

Interfaces

ArrayAccess

Constants

TYPE_BIRTHDAY  = 2
TYPE_EVENT_RECURRING  = 1
TYPE_EVENT_SIMPLE  = 0
TYPE_HOLIDAY  = 4

Properties

$allday  : bool
$board  : int
$end  : Time
$groups  : array<string|int, mixed>
$id  : int
$loaded  : array<string|int, mixed>
$location  : string
$member  : int
$modified_time  : int
$msg  : int
$name  : string
$start  : Time
$title  : string
$topic  : int
$type  : int
$keep_all  : bool
$prop_aliases  : array<string|int, mixed>
$use_permissions  : bool
$backcompat  : array<string|int, mixed>

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.
create()  : void
Creates a event and saves it to the database.
exportStatic()  : void
Provides a way to export a class's public static properties and methods to global namespace.
fixTimezone()  : void
get()  : Generator<string|int, object>
Generator that yields instances of this class.
getVEvent()  : string
load()  : array<string|int, mixed>
Loads events by ID number or by topic.
loadRange()  : array<string|int, mixed>
Loads events within the given date range.
modify()  : void
Modifies an event.
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 an event.
save()  : void
Saves this event to the database.
fixEndDate()  : void
Ensures that the start and end dates have a sane relationship.
getNumDays()  : int
Gets the number of days across which this event occurs.
queryData()  : Generator<string|int, array<string|int, mixed>>
Generator that runs queries about event data and yields the result rows.
setNumDays()  : void
Adjusts the end date so that the number of days across which this event occurs will be $num_days.
setStartEnd()  : void
Set the start and end dates and times 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_RECURRING

public mixed TYPE_EVENT_RECURRING = 1

TYPE_EVENT_SIMPLE

public mixed TYPE_EVENT_SIMPLE = 0

TYPE_HOLIDAY

public mixed TYPE_HOLIDAY = 4

Properties

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

$end

public Time $end

An SMF\Time object representing the end of the event.

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

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

$start

public Time $start

An SMF\Time object representing the start of the event.

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

This event's type. Value must be one of this class's TYPE_* constants.

$keep_all

protected static bool $keep_all = false

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

$prop_aliases

protected array<string|int, mixed> $prop_aliases = ['id_event' => 'id', 'eventid' => 'id', 'id_board' => 'board', 'id_topic' => 'topic', 'id_first_msg' => 'msg', 'sequence' => 'modified_time', '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.

$use_permissions

protected bool $use_permissions = true

Whether we checked access permissions when loading this event.

$backcompat

private static array<string|int, mixed> $backcompat = ['func_names' => ['create' => 'insertEvent', 'modify' => 'modifyEvent', 'remove' => 'removeEvent']]

BackwardCompatibility settings for this class.

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.

__isset()

Checks whether a custom property has been set.

public __isset(string $prop) : bool
Parameters
$prop : string

The property name.

Return values
bool

__set()

Sets custom properties.

public __set(string $prop, mixed $value) : void
Parameters
$prop : string

The property name.

$value : mixed

The value to set.

create()

Creates a event 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.)

exportStatic()

Provides a way to export a class's public static properties and methods to global namespace.

public static exportStatic() : void

To do so:

  1. Use this trait in the class.
  2. At the END of the class's file, call its exportStatic() method.

Although it might not seem that way at first glance, this approach conforms to section 2.3 of PSR 1, since executing this method is simply a dynamic means of declaring functions when the file is included; it has no other side effects.

Regarding the $backcompat items:

A class's static properties are not exported to global variables unless explicitly included in $backcompat['prop_names']. Likewise, a class's static methods are not exported as global functions unless explicitly included in $backcompat['func_names'].

$backcompat['prop_names'] is a simple array where the keys are the names of one or more of a class's static properties, and the values are the names of global variables. In each case, the global variable will be set to a reference to the static property. Static properties that are not named in this array will not be exported.

$backcompat['func_names'] is a simple array where the keys are the names of one or more of a class's static methods, and the values are the names that should be used for global functions that will encapsulate those methods. Methods that are not named in this array will not be exported.

Adding non-static properties or methods to the $backcompat arrays will produce runtime errors. It is the responsibility of the developer to make sure not to do this.

fixTimezone()

public fixTimezone() : void

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, object>
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.

Tags
todo

SMF does not yet take advantage of this generator very well. Instead of loading all the events in the range via Event::loadRange(), it would be better to call Event::get() directly in order to reduce memory load.

Return values
Generator<string|int, object> —

Iterating over result gives Event instances.

getVEvent()

public getVEvent() : string
Return values
string

load()

Loads events by ID number or by topic.

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 event or topic.

$is_topic : bool = false

If true, $id is the topic ID. Default: false.

$use_permissions : bool = true

Whether to use permissions. Default: true.

Return values
array<string|int, mixed> —

Instances of this class for the loaded events.

loadRange()

Loads events within the given date range.

public static loadRange(string $low_date, string $high_date[, bool $use_permissions = true ][, array<string|int, mixed> $query_customizations = [] ]) : array<string|int, mixed>
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
array<string|int, mixed> —

Instances of this class for the loaded events.

modify()

Modifies an event.

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
bool

offsetGet()

Gets properties when object is accessed as an array.

public offsetGet(mixed $prop) : mixed
Parameters
$prop : mixed

The property name.

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 an event.

public static remove(int $id) : void

Does not check permissions.

Parameters
$id : int

The event's ID.

save()

Saves this event to the database.

public save() : void

fixEndDate()

Ensures that the start and end dates have a sane relationship.

protected fixEndDate() : void

getNumDays()

Gets the number of days across which this event occurs.

protected getNumDays() : int

For example, if the event starts and ends on the same day, span is 1. If the event starts Monday night and ends Wednesday morning, span is 3.

Return values
int —

Number of days that this event spans, or 0 on error.

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.

setNumDays()

Adjusts the end date so that the number of days across which this event occurs will be $num_days.

protected setNumDays(int $num_days) : void
Parameters
$num_days : int

The target number of days the event should span. If $num_days is set to a value less than 1, no change will be made. This method imposes no upper limit on $num_days, but if $num_days exceeds the value of Config::$modSettings['cal_maxspan'], other parts of this class will impose that limit.

setStartEnd()

Set the start and end dates and times for a posted event for insertion into the database.

protected static setStartEnd(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.)

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.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results