Documentation

Alert
in package

SMF

implements ArrayAccess Uses BackwardCompatibility, ArrayAccessHelper

Represents an alert and provides methods for working with alerts.

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>
$backcompat : 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.
exportStatic() : void: Provides a way to export a class's public static properties and methods to global namespace.
fetch() : array<string|int, mixed>: Convenience method to load and format the alerts a member currently has.
format() : void: Perpares 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.

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

$backcompat


    private
    static    array<string|int, mixed>
    $backcompat
     = ['func_names' => ['fetch' => 'fetch_alerts', 'count' => 'alert_count', 'mark' => 'alert_mark', 'delete' => 'alert_delete', 'purge' => 'alert_purge']]

BackwardCompatibility settings for this class.

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

exportStatic()

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


    public
            static        exportStatic() : void

To do so:

Use this trait in the class.
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.

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

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

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(mixed $possible_topics, int $memID[, bool $simple = false ]) : array<string|int, mixed>

Parameters

$possible_topics : 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

Alert in package SMF implements ArrayAccess Uses BackwardCompatibility, ArrayAccessHelper

Table of Contents

Interfaces

Properties

Methods

Properties

$content_action

$content_id

$content_type

$extra

$icon

$id

$is_read

$link_formats

$loaded

$member

$member_name

$member_started

$show_links

$target_href

$text

$time

$timestamp

$formats_finalized

$prop_aliases

$qb

$backcompat

Methods

__construct()

Parameters

__set()

Parameters

count()

Parameters

Return values

create()

Parameters

Return values

createBatch()

Parameters

Return values

delete()

Parameters

deleteWhere()

Parameters

exportStatic()

fetch()

Parameters

Return values

format()

Parameters

load()

Parameters

Return values

loadForMember()

Parameters

Return values

mark()

Parameters

markAll()

Parameters

markWhere()

Parameters

offsetExists()

Parameters

Return values

offsetGet()

Parameters

offsetSet()

Parameters

offsetUnset()

Parameters

purge()

Parameters

save()

Parameters

checkMsgAccess()

Parameters

Return values

checkTopicAccess()

Alert
in package

SMF

implements ArrayAccess Uses BackwardCompatibility, ArrayAccessHelper