Documentation

Msg
in package
implements ArrayAccess, Routable uses 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.

Table of Contents

Interfaces

ArrayAccess
Routable
Classes implementing this interface can build routes from URL query parameters and parse routes back into URL query parameters.

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
$version  : string
$keep_all  : bool
$messages_request  : object
$messages_to_get  : array<string|int, mixed>
$prop_aliases  : array<string|int, mixed>

Methods

__construct()  : mixed
Constructor.
__set()  : void
Sets custom properties.
approve()  : bool
Approve (or not) some posts... without permission checks.
buildRoute()  : array<string|int, mixed>
Builds a routing path based on URL query parameters.
clearApprovalAlerts()  : void
Upon approval, clear unread alerts.
create()  : bool
Create a post, either as new topic (id_topic = 0) or in an existing one.
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.
parseRoute()  : array<string|int, mixed>
Parses a route to get URL query parameters.
preparsecode()  : void
Takes a message and parses it, returning nothing.
remove()  : bool
Remove a specific message (including permission checks).
un_preparsecode()  : string
This is very simple, and just removes things done by preparsecode.
updateLastMessages()  : 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.

Properties

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

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

$version

public string $version = ''

The SMF version in which this message was written.

Consists of major and minor version only (e.g. "3.0", not "3.0.1")

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

Methods

__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

buildRoute()

Builds a routing path based on URL query parameters.

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

URL query parameters.

Return values
array<string|int, mixed> —

Contains two elements: ['route' => [], 'params' => []]. The 'route' element contains the routing path. The 'params' element contains any $params that weren't incorporated into the route.

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

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(int|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 : int|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.

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.

parseRoute()

Parses a route to get URL query parameters.

public static parseRoute(array<string|int, mixed> $route[, array<string|int, mixed> $params = [] ]) : array<string|int, mixed>
Parameters
$route : array<string|int, mixed>

Array of routing path components.

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

Any existing URL query parameters.

Return values
array<string|int, mixed> —

URL query parameters

preparsecode()

Takes a message and parses it, returning nothing.

public static preparsecode(string &$message[, bool $previewing = false ][, bool $autolink = 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 message.

$previewing : bool = false

Whether we're previewing. Default: false.

$autolink : bool = false

Whether to autolink plain-text URLs. Default: false.

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

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(int|array<string|int, mixed> $setboards[, int $id_msg = 0 ]) : 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 : int|array<string|int, mixed>

An array of board IDs

$id_msg : int = 0

The ID of the message

Return values
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.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results