Documentation

Alert
in package
implements ArrayAccess uses ArrayAccessHelper

Represents an alert and provides methods for working with alerts.

Table of Contents

Interfaces

ArrayAccess

Properties

$content_action  : string
$content_id  : int
$content_type  : string
$extra  : array<string|int, mixed>
$icon  : string
$id  : int
$is_read  : int
$link_formats  : array<string|int, mixed>
$loaded  : array<string|int, mixed>
$member  : int
$member_name  : string
$member_started  : int
$show_links  : bool
$target_href  : string
$text  : string
$time  : string
$timestamp  : int
$formats_finalized  : array<string|int, mixed>
$prop_aliases  : array<string|int, mixed>
$qb  : array<string|int, mixed>

Methods

__construct()  : mixed
Constructor.
__set()  : void
Sets custom properties.
count()  : int
Counts how many alerts a user has, either unread or all.
create()  : object
Creates a new alert, saves it, and updates the alert count.
createBatch()  : array<string|int, mixed>
Creates a batch of new alerts, saves them, and updates the alert counts.
delete()  : void
Deletes alerts by ID.
deleteWhere()  : void
Deletes alerts based on a custom query.
fetch()  : array<string|int, mixed>
Convenience method to load and format the alerts a member currently has.
format()  : void
Prepares this alert for use in the templates.
load()  : array<string|int, mixed>
Loads an arbitrary set of alerts.
loadForMember()  : array<string|int, mixed>
Loads the alerts a member currently has.
mark()  : void
Marks a group of alerts as un/read.
markAll()  : void
Marks all of a member's alerts as un/read.
markWhere()  : void
Marks alerts as un/read based on a custom query.
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.
purge()  : void
Deletes the alerts that a member has already read.
save()  : void
Save this alert to the database.
checkMsgAccess()  : array<string|int, mixed>
Checks whether a member can see the messages that some alerts refer to.
checkTopicAccess()  : array<string|int, mixed>
Checks whether a member can see the topics that some alerts refer to.
deleteInvisible()  : void
Deletes alerts that a user cannot see.
finalizeLinkFormats()  : void
Substitute Config::$scripturl into the link formats.
queryData()  : Generator<string|int, array<string|int, mixed>>
Generator that runs queries about alert data and yields the result rows.
resetLinkFormats()  : void
Resets the link formats to their defaults.
setIcon()  : void
Sets the icon for this alert.
setQb()  : void
Sets the query_see_board values to use when checking access to content.

Properties

$content_action

public string $content_action

The action taken upon the content that this alert is about.

$content_id

public int $content_id

ID of the content that this alert is about.

$content_type

public string $content_type

Type of content that this alert is about.

$extra

public array<string|int, mixed> $extra

More info about this alert. Content varies widely from case to case.

$icon

public string $icon

The icon for this alert.

$id

public int $id

This alert's ID number.

$is_read

public int $is_read

UNIX timestamp when the member read this alert, or zero if unread.

$link_formats

public static array<string|int, mixed> $link_formats = ['msg_msg' => ['required' => ['content_subject', 'topic', 'msg'], 'link' => '<a href="{scripturl}?topic=%2$d.msg%3$d#msg%3$d">%1$s</a>', 'text' => '<strong>%1$s</strong>'], 'topic_msg' => ['required' => ['content_subject', 'topic', 'topic_suffix'], 'link' => '<a href="{scripturl}?topic=%2$d.%3$s">%1$s</a>', 'text' => '<strong>%1$s</strong>'], 'board_msg' => ['required' => ['board_name', 'board'], 'link' => '<a href="{scripturl}?board=%2$d.0">%1$s</a>', 'text' => '<strong>%1$s</strong>'], 'profile_msg' => ['required' => ['user_name', 'user_id'], 'link' => '<a href="{scripturl}?action=profile;u=%2$d">%1$s</a>', 'text' => '<strong>%1$s</strong>']]

Some sprintf formats for generating links/strings.

'required' is an array of keys in $this->extra that should be used to generate the message, ordered to match the sprintf formats.

'link' and 'text' are the sprintf formats that will be used when $this->show_links is true or false, respectively.

$loaded

public static array<string|int, mixed> $loaded = []

All loaded instances of this class.

$member

public int $member

ID of the member this alert is for.

$member_name

public string $member_name

Name of the member that caused this alert to be sent.

$member_started

public int $member_started

ID of the member that caused this alert to be sent.

$show_links

public bool $show_links

Whether to show links in the constituent parts of the alert message.

$target_href

public string $target_href

URL that this alert should take the user to.

$text

public string $text

The alert message.

$time

public string $time

Formatted date string based on $this->timestamp.

$timestamp

public int $timestamp

UNIX timestamp when the alert was created.

$formats_finalized

protected static array<string|int, mixed> $formats_finalized = false

Whether self::$link_formats has been finalized.

$prop_aliases

protected array<string|int, mixed> $prop_aliases = ['id_alert' => 'id', 'alert_time' => 'timestamp', 'id_member' => 'member', 'id_member_started' => 'member_started', 'sender_id' => 'member_started', 'sender_name' => 'member_name']

Alternate names for some object properties.

$qb

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

The query_see_board data to use when checking access to content.

Methods

__construct()

Constructor.

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

The ID number of the alert.

$props : array<string|int, mixed> = []

Properties to set for this alert.

__set()

Sets custom properties.

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

The property name.

$value : mixed

The value to set.

count()

Counts how many alerts a user has, either unread or all.

public static count(int $memID[, bool $unread = false ]) : int
Parameters
$memID : int

The user ID.

$unread : bool = false

Whether to only count unread alerts.

Return values
int —

The number of alerts.

create()

Creates a new alert, saves it, and updates the alert count.

public static create([array<string|int, mixed> $props = [] ]) : object
Parameters
$props : array<string|int, mixed> = []

Properties to set for this alert.

Return values
object —

An instance of this class.

createBatch()

Creates a batch of new alerts, saves them, and updates the alert counts.

public static createBatch([array<string|int, mixed> $props_batch = [] ]) : array<string|int, mixed>

This has the same end result as calling Alert::create() for each set of properties in $props_batch, but this is more efficient internally.

Parameters
$props_batch : array<string|int, mixed> = []

Multiple sets of $props.

Return values
array<string|int, mixed> —

An array of instances of this class.

delete()

Deletes alerts by ID.

public static delete(int|array<string|int, mixed> $ids[, int|array<string|int, mixed> $members = [] ]) : void
Parameters
$ids : int|array<string|int, mixed>

The IDs of one or more alerts.

$members : int|array<string|int, mixed> = []

Members whose alert counts should be updated.

deleteWhere()

Deletes alerts based on a custom query.

public static deleteWhere(array<string|int, mixed> $where, array<string|int, mixed> $params) : void
Parameters
$where : array<string|int, mixed>

Conditions for the WHERE clause of the SQL query.

$params : array<string|int, mixed>

Parameters to substitute into the SQL query.

fetch()

Convenience method to load and format the alerts a member currently has.

public static fetch(int $memID[, bool|array<string|int, mixed> $to_fetch = false ][, array<string|int, mixed> $limit = 0 ][, array<string|int, mixed> $offset = 0 ][, bool $with_avatar = false ][, bool $show_links = false ]) : array<string|int, mixed>
Parameters
$memID : int

The ID of the member.

$to_fetch : bool|array<string|int, mixed> = false

Alerts to fetch: true/false for all/unread, or a list of one or more IDs.

$limit : array<string|int, mixed> = 0

Maximum number of alerts to fetch (0 for no limit).

$offset : array<string|int, mixed> = 0

Number of alerts to skip for pagination. Ignored if $to_fetch is a list of IDs.

$with_avatar : bool = false

Whether to load the avatar of the alert sender.

$show_links : bool = false

Whether to show links in the constituent parts of the alert message.

Return values
array<string|int, mixed> —

An array of information about the fetched alerts.

format()

Prepares this alert for use in the templates.

public format([bool $with_avatar = false ][, bool $show_links = false ]) : void
Parameters
$with_avatar : bool = false

Whether to load the avatar of the alert sender.

$show_links : bool = false

Whether to show links in the constituent parts of the alert message.

load()

Loads an arbitrary set of alerts.

public static load([int|array<string|int, mixed> $ids = [] ][, array<string|int, mixed> $query_customizations = [] ][, bool $simple_access_check = false ]) : array<string|int, mixed>
Parameters
$ids : int|array<string|int, mixed> = []

The IDs zero or more alerts.

$query_customizations : array<string|int, mixed> = []

Customizations to the SQL query.

$simple_access_check : bool = false

If true, do the simple access check. If false, also load some additional info during the access check. Default: false;

Return values
array<string|int, mixed> —

An array of instances of this class.

loadForMember()

Loads the alerts a member currently has.

public static loadForMember(int $memID[, bool|array<string|int, mixed> $to_fetch = false ][, array<string|int, mixed> $limit = 0 ][, array<string|int, mixed> $offset = 0 ][, bool $simple_access_check = false ]) : array<string|int, mixed>
Parameters
$memID : int

The ID of the member.

$to_fetch : bool|array<string|int, mixed> = false

Alerts to fetch: true/false for all/unread, or a list of one or more alert IDs.

$limit : array<string|int, mixed> = 0

Maximum number of alerts to fetch (0 for no limit).

$offset : array<string|int, mixed> = 0

Number of alerts to skip for pagination. Ignored if $to_fetch is a list of IDs.

$simple_access_check : bool = false
Return values
array<string|int, mixed> —

An array of instances of this class.

mark()

Marks a group of alerts as un/read.

public static mark(int|array<string|int, mixed> $members, array<string|int, mixed>|int $to_mark, bool $read) : void
Parameters
$members : int|array<string|int, mixed>

Members whose alerts should be updated.

$to_mark : array<string|int, mixed>|int

The IDs of one or more alerts.

$read : bool

To mark as read or unread. True = read, false = unread.

markAll()

Marks all of a member's alerts as un/read.

public static markAll(int|array<string|int, mixed> $members, bool $read) : void
Parameters
$members : int|array<string|int, mixed>

Members whose alerts should be updated.

$read : bool

To mark as read or unread. True = read, false = unread.

markWhere()

Marks alerts as un/read based on a custom query.

public static markWhere(array<string|int, mixed> $where, array<string|int, mixed> $params, bool $read) : void
Parameters
$where : array<string|int, mixed>

Conditions for the WHERE clause of the SQL query.

$params : array<string|int, mixed>

Parameters to substitute into the SQL query.

$read : bool

To mark as read or unread. True = read, false = unread.

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.

purge()

Deletes the alerts that a member has already read.

public static purge([int $memID = 0 ][, int $before = 0 ]) : void
Parameters
$memID : int = 0

The member ID. Defaults to the current user's ID. If set to -1, will purge read alerts for all members.

$before : int = 0

Only purge alerts read before this UNIX timestamp. If zero or negative, current time will be used. Default: zero.

save()

Save this alert to the database.

public save([bool $update_count = true ]) : void
Parameters
$update_count : bool = true

Whether to update the member's alert count. Default: true.

checkMsgAccess()

Checks whether a member can see the messages that some alerts refer to.

protected static checkMsgAccess(array<string|int, mixed> $possible_msgs, int $memID[, bool $simple = false ]) : array<string|int, mixed>
Parameters
$possible_msgs : array<string|int, mixed>

Key-value pairs of alert IDs and message IDs.

$memID : int

ID of the member.

$simple : bool = false

If true, do nothing beyond checking the access. If false, also get some info about the message in question. Default: false.

Return values
array<string|int, mixed> —

Key-value pairs of alert IDs and visibility status.

checkTopicAccess()

Checks whether a member can see the topics that some alerts refer to.

protected static checkTopicAccess(array<string|int, mixed> $possible_topics, int $memID[, bool $simple = false ]) : array<string|int, mixed>
Parameters
$possible_topics : array<string|int, mixed>
$memID : int

ID of the member.

$simple : bool = false

If true, do nothing beyond checking the access. If false, also get some info about the topic in question. Default: false.

Return values
array<string|int, mixed> —

Key-value pairs of alert IDs and visibility status.

deleteInvisible()

Deletes alerts that a user cannot see.

protected static deleteInvisible(array<string|int, mixed> &$alerts, int $memID) : void
Parameters
$alerts : array<string|int, mixed>

An array of instances of this class.

$memID : int

The ID of the user whose alerts we should check. Any alerts belonging to other users will be ignored.

finalizeLinkFormats()

Substitute Config::$scripturl into the link formats.

protected static finalizeLinkFormats() : void

queryData()

Generator that runs queries about alert 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}members AS mem ON (a.id_member_started = mem.id_member)' Note that 'FROM {db_prefix}user_alerts AS a' 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.

resetLinkFormats()

Resets the link formats to their defaults.

protected static resetLinkFormats() : void

setIcon()

Sets the icon for this alert.

protected setIcon() : void

setQb()

Sets the query_see_board values to use when checking access to content.

protected static setQb(int $memID) : void
Parameters
$memID : int 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results