Documentation

Msg
in package

SMF

implements ArrayAccess Uses BackwardCompatibility, ArrayAccessHelper

Class for a single posted message.

This class's static methods pertain to posting, and other such operations, including sending emails, pms, blocking spam, preparsing posts, spell checking, and the post box.

Interfaces

ArrayAccess

Properties

$approved : int
$body : string
$formatted : array<string|int, mixed>
$getter : object|array<string|int, mixed>
$icon : string
$id : int
$id_board : int
$id_member : int
$id_msg_modified : int
$id_topic : int
$is_read : bool
$likes : int
$loaded : array<string|int, mixed>
$modified_name : string
$modified_reason : string
$modified_time : int
$poster_email : string
$poster_ip : string
$poster_name : string
$poster_time : int
$smileys_enabled : bool
$subject : string
$keep_all : bool
$messages_request : object
$messages_to_get : array<string|int, mixed>
$prop_aliases : array<string|int, mixed>
$backcompat : array<string|int, mixed>

Methods

__construct() : mixed: Constructor.
__set() : void: Sets custom properties.
approve() : bool: Approve (or not) some posts... without permission checks.
clearApprovalAlerts() : void: Upon approval, clear unread alerts.
create() : bool: Create a post, either as new topic (id_topic = 0) or in an existing one.
exportStatic() : void: Provides a way to export a class's public static properties and methods to global namespace.
fixTag() : void: Fix a specific class of tag - ie. url with =.
fixTags() : void: Fix any URLs posted - ie. remove 'javascript:'.
format() : array<string|int, mixed>: Sets the formatted versions of message data for use in templates.
get() : Generator<string|int, array<string|int, mixed>>: Generator that yields instances of this class.
load() : array<string|int, mixed>: Loads messages by ID number.
modify() : bool: Modifying a post.
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.
preparsecode() : void: Takes a message and parses it, returning nothing.
remove() : bool: Remove a specific message (including permission checks).
spell_check() : bool: spell_check()
spell_init() : resource|bool: spell_init()
spell_suggest() : array<string|int, mixed>: spell_suggest()
spellCheck() : void: Spell checks the post for typos ;).
un_preparsecode() : string: This is very simple, and just removes things done by preparsecode.
updateLastMessages() : void|false: Takes an array of board IDs and updates their last messages.
queryData() : Generator<string|int, array<string|int, mixed>>: Generator that runs queries about message data and yields the result rows.

$approved


    public
        int
    $approved
     = 1

The approval status of this message.

$body


    public
        string
    $body
     = ''

The content of this message.

$formatted


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

Formatted versions of this message's properties, suitable for display.

$getter


    public
    static    object|array<string|int, mixed>
    $getter

Variable to hold the Msg::get() generator. If there are no messages, will be an empty array.

$icon


    public
        string
    $icon
     = ''

The icon assigned to this message.

$id


    public
        int
    $id

This message's ID number.

$id_board


    public
        int
    $id_board

ID number of the board that this message is in.

$id_member


    public
        int
    $id_member
     = 0

ID number of the author of this message. Will be 0 for messages authored by guests.

$id_msg_modified


    public
        int
    $id_msg_modified
     = 0

The ID number of whatever the latest message was when this message was last modified.

$id_topic


    public
        int
    $id_topic

ID number of the topic that this message is in.

$is_read


    public
        bool
    $is_read

Whether the current user has read this message.

$likes


    public
        int
    $likes
     = 0

The number of likes this message has received.

$loaded


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

All loaded instances of this class.

$modified_name


    public
        string
    $modified_name
     = ''

Name of the member who last modified this message. Will be an empty string if the message has never been modified.

$modified_reason


    public
        string
    $modified_reason
     = ''

User-supplied explanation of why this message was modified.

$modified_time


    public
        int
    $modified_time
     = 0

Unix timestamp when this message was modified. Will be 0 if message has never been modifed.

$poster_email


    public
        string
    $poster_email
     = ''

E-mail address of the author of this message.

$poster_ip


    public
        string
    $poster_ip
     = ''

IP address of the author of this message.

$poster_name


    public
        string
    $poster_name
     = ''

Name of the author of this message.

$poster_time


    public
        int
    $poster_time

Unix timestamp when this message was created.

$smileys_enabled


    public
        bool
    $smileys_enabled
     = true

Whether smileys should be parsed in this message.

$subject


    public
        string
    $subject
     = ''

The subject line of this message.

$keep_all


    protected
    static    bool
    $keep_all
     = false

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

$messages_request


    protected
    static    object
    $messages_request

Database query used in Msg::queryPMData().

$messages_to_get


    protected
    static    array<string|int, mixed>
    $messages_to_get

IDs of messages to load in Msg::get(). Stored separately like this in order to allow resetting Msg::get().

$prop_aliases


    protected
        array<string|int, mixed>
    $prop_aliases
     = [
    'id_msg' => 'id',
    'timestamp' => 'poster_time',
    // Initial exclamation mark means inverse of the property.
    'new' => '!is_read',
]

Alternate names for some object properties.

$backcompat


    private
    static    array<string|int, mixed>
    $backcompat
     = ['func_names' => ['preparsecode' => 'preparsecode', 'un_preparsecode' => 'un_preparsecode', 'fixTags' => 'fixTags', 'fixTag' => 'fixTag', 'spellCheck' => 'SpellCheck', 'create' => 'createPost', 'modify' => 'modifyPost', 'approve' => 'approvePosts', 'clearApprovalAlerts' => 'clearApprovalAlerts', 'updateLastMessages' => 'updateLastMessages', 'remove' => 'removeMessage', 'spell_init' => 'spell_init', 'spell_check' => 'spell_check', 'spell_suggest' => 'spell_suggest']]

BackwardCompatibility settings for this class.

__construct()

Constructor.


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

Parameters

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

__set()

Sets custom properties.


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

Parameters

$prop : string: The property name.
$value : mixed: The value to set.

approve()

Approve (or not) some posts... without permission checks.


    public
            static        approve(array<string|int, mixed> $msgs[, bool $approve = true ][, bool $notify = true ]) : bool

Parameters

$msgs : array<string|int, mixed>: Array of message ids
$approve : bool = true: Whether to approve the posts (if false, posts are unapproved)
$notify : bool = true: Whether to notify users

Return values

bool —

Whether the operation was successful

clearApprovalAlerts()

Upon approval, clear unread alerts.


    public
            static        clearApprovalAlerts(array<string|int, int> $content_ids, string $content_action) : void

Parameters

$content_ids : array<string|int, int>: either id_msgs or id_topics
$content_action : string: will be either 'unapproved_post' or 'unapproved_topic'

create()

Create a post, either as new topic (id_topic = 0) or in an existing one.


    public
            static        create(array<string|int, mixed> &$msgOptions, array<string|int, mixed> &$topicOptions, array<string|int, mixed> &$posterOptions) : bool

The input parameters of this function assume:

Strings have been escaped.
Integers have been cast to integer.
Mandatory parameters are set.

Parameters

$msgOptions : array<string|int, mixed>: An array of information/options for the post
$topicOptions : array<string|int, mixed>: An array of information/options for the topic
$posterOptions : array<string|int, mixed>: An array of information/options for the poster

Return values

bool —

Whether the operation was a success

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.

fixTag()

Fix a specific class of tag - ie. url with =.


    public
            static        fixTag(string &$message, string $myTag, array<string|int, mixed> $protocols[, bool $embeddedUrl = false ][, bool $hasEqualSign = false ][, bool $hasExtra = false ]) : void

Used by fixTags, fixes a specific tag's links.

Parameters

$message : string: The message
$myTag : string: The tag
$protocols : array<string|int, mixed>: The protocols
$embeddedUrl : bool = false: Whether it can be set to something
$hasEqualSign : bool = false: Whether it is set to something
$hasExtra : bool = false: Whether it can have extra cruft after the begin tag.

fixTags()

Fix any URLs posted - ie. remove 'javascript:'.


    public
            static        fixTags(string &$message) : void

Used by preparsecode, fixes links in message and returns nothing.

Parameters

$message : string: The message

format()

Sets the formatted versions of message data for use in templates.


    public
                    format([int $counter = 0 ][, array<string|int, mixed> $format_options = [] ]) : array<string|int, mixed>

Parameters

$counter : int = 0: The number of this message in a list of messages.
$format_options : array<string|int, mixed> = []: Options to control output.

Return values

array<string|int, mixed> —

A copy of $this->formatted.

get()

Generator that yields instances of this class.


    public
            static        get(int|array<string|int, mixed> $ids[, array<string|int, mixed> $query_customizations = [] ]) : Generator<string|int, array<string|int, mixed>>

Similar to Msg::load(), except that this method progressively creates and destroys instances of this class for each message, so that only one instance ever exists at a time.

Parameters

$ids : int|array<string|int, mixed>: The ID numbers of the messages to load.
$query_customizations : array<string|int, mixed> = []: Customizations to the SQL query.

Return values

Generator<string|int, array<string|int, mixed>> —

Iterating over result gives Msg instances.

load()

Loads messages by ID number.


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

Note: if you are loading a group of messages so that you can iterate over them, consider using Msg::get() rather than Msg::load().

Parameters

$ids : array<string|int, mixed>: The ID numbers of one or more messages.
$query_customizations : array<string|int, mixed> = []: Customizations to the SQL query.

Return values

array<string|int, mixed> —

Instances of this class for the loaded messages.

modify()

Modifying a post.


    public
            static        modify(array<string|int, mixed> &$msgOptions, array<string|int, mixed> &$topicOptions, array<string|int, mixed> &$posterOptions) : bool

Parameters

$msgOptions : array<string|int, mixed>: An array of information/options for the post
$topicOptions : array<string|int, mixed>: An array of information/options for the topic
$posterOptions : array<string|int, mixed>: An array of information/options for the poster

Return values

bool —

Whether the post was modified successfully

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.

preparsecode()

Takes a message and parses it, returning nothing.


    public
            static        preparsecode(string &$message[, bool $previewing = false ]) : void

Cleans up links (javascript, etc.) and code/quote sections. Won't convert \n's and a few other things if previewing is true.

Parameters

$message : string: The mesasge
$previewing : bool = false: Whether we're previewing

remove()

Remove a specific message (including permission checks).


    public
            static        remove(int $message[, bool $decreasePostCount = true ]) : bool

Parameters

$message : int: The message id
$decreasePostCount : bool = true: Whether to decrease users' post counts

Return values

bool —

Whether the operation succeeded

spell_check()


    public
            static        spell_check(Dictionary $dict, string $word) : bool

Determines whether or not the specified word is spelled correctly

Parameters

$dict : Dictionary: An enchant or pspell dictionary resource set up by
$word : string: A word to check the spelling of

Return values

bool —

Whether or not the specified word is spelled properly

spell_init()


    public
            static        spell_init() : resource|bool

Sets up a dictionary resource handle. Tries enchant first then falls through to pspell.

Return values

resource|bool —

An enchant or pspell dictionary resource handle or false if the dictionary couldn't be loaded

spell_suggest()


    public
            static        spell_suggest(Dictionary $dict, string $word) : array<string|int, mixed>

Returns an array of suggested replacements for the specified word

Parameters

$dict : Dictionary: An enchant or pspell dictionary resource
$word : string: A misspelled word

Return values

array<string|int, mixed> —

An array of suggested replacements for the misspelled word

spellCheck()

Spell checks the post for typos ;).


    public
            static        spellCheck() : void

It uses the pspell or enchant library, one of which MUST be installed. It has problems with internationalization. It is accessed via ?action=spellcheck.

un_preparsecode()

This is very simple, and just removes things done by preparsecode.


    public
            static        un_preparsecode(string $message) : string

Parameters

$message : string: The message

Return values

string —

The message with preparsecode changes reverted.

updateLastMessages()

Takes an array of board IDs and updates their last messages.


    public
            static        updateLastMessages(array<string|int, mixed> $setboards[, int $id_msg = 0 ]) : void|false

If the board has a parent, that parent board is also automatically updated. The columns updated are id_last_msg and last_updated. Note that id_last_msg should always be updated using this function, and is not automatically updated upon other changes.

Parameters

$setboards : array<string|int, mixed>: An array of board IDs
$id_msg : int = 0: The ID of the message

Return values

void|false —

Returns false if $setboards is empty for some reason

queryData()

Generator that runs queries about message 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.

Msg in package SMF implements ArrayAccess Uses BackwardCompatibility, ArrayAccessHelper

Table of Contents

Interfaces

Properties

Methods

Properties

$approved

$body

$formatted

$getter

$icon

$id

$id_board

$id_member

$id_msg_modified

$id_topic

$is_read

$likes

$loaded

$modified_name

$modified_reason

$modified_time

$poster_email

$poster_ip

$poster_name

$poster_time

$smileys_enabled

$subject

$keep_all

$messages_request

$messages_to_get

$prop_aliases

$backcompat

Methods

__construct()

Parameters

__set()

Parameters

approve()

Parameters

Return values

clearApprovalAlerts()

Parameters

create()

Parameters

Return values

exportStatic()

fixTag()

Parameters

fixTags()

Parameters

format()

Parameters

Return values

get()

Parameters

Return values

load()

Parameters

Return values

modify()

Parameters

Return values

offsetExists()

Parameters

Return values

offsetGet()

Parameters

offsetSet()

Parameters

offsetUnset()

Parameters

preparsecode()

Parameters

remove()

Parameters

Return values

spell_check()

Parameters

Return values

Msg
in package

SMF

implements ArrayAccess Uses BackwardCompatibility, ArrayAccessHelper