Documentation

SearchResult extends PM
in package

SMF

Shows personal message search results.

Properties

$body : string
$deleted_by_sender : bool
$folder : string
$formatted : array<string|int, mixed>
$from_name : string
$getter : object|array<string|int, mixed>
$head : int
$id : int
$loaded : array<string|int, mixed>
$member_from : int
$msgtime : int
$received : array<string|int, mixed>
$subject : string
$subject_getter : object|array<string|int, mixed>
$keep_all : bool
$message_limit_cache : array<string|int, mixed>
$messages_request : object
$prop_aliases : array<string|int, mixed>
$recent : array<string|int, mixed>
$backcompat : array<string|int, mixed>

Methods

__construct() : mixed: Constructor.
canAccess() : bool: Checks whether the current user can see this personal message.
compose() : void: Shows the form for composing a personal message.
compose2() : bool: Validates a composed personal message and then passes it to PM::send() if it is valid. If errors were found, or if the user requested a preview, will return false.
countSent() : int: Counts the personal messages sent by the current user, with optional limits.
delete() : void: Delete the specified personal messages.
exportStatic() : void: Provides a way to export a class's public static properties and methods to global namespace.
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.
getFormatted() : Generator<string|int, array<string|int, mixed>>: Generator that yields formatted PMs for use in a search results list.
getLatest() : int: Gets the ID of the most recent personal message sent by the current user.
getRecent() : array<string|int, mixed>: Gets the IDs of the most recent personal messages sent by the current user.
isAccessible() : bool: Backward compatibilty wrapper around the non-static canAccess() method.
load() : array<string|int, mixed>: Loads personal messages by ID number.
markRead() : void: Mark the specified personal messages as read.
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.
old() : array<string|int, mixed>: Returns the IDs of personal messages sent before a given time.
reportErrors() : void: Informs the user about an error in the message they wrote.
send() : array<string|int, mixed>: Sends an personal message from the specified person to the specified people ($from defaults to the user)
queryData() : Generator<string|int, array<string|int, mixed>>: Generator that runs queries about PM data and yields the result rows.

$body


    public
        string
    $body

Body text of this PM.

$deleted_by_sender


    public
        bool
    $deleted_by_sender

Whether the author of this PM has deleted it.

$folder


    public
        string
    $folder

Name of the folder that holds this PM for the current user. Either 'inbox' or 'sent'.

$formatted


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

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

$from_name


    public
        string
    $from_name

Name of the author of this PM.

$getter


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

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

$head


    public
        int
    $head

ID number of the PM that started the conversation that this is part of.

$id


    public
        int
    $id

This PM's ID number.

$loaded


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

All loaded instances of this class.

$member_from


    public
        int
    $member_from

ID number of the author of this PM.

$msgtime


    public
        int
    $msgtime

UNIX timestamp when this PM was sent.

$received


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

Data about received copies of this PM.

$subject


    public
        string
    $subject

Subject line of this PM.

$subject_getter


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

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

$keep_all


    protected
    static    bool
    $keep_all
     = false

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

$message_limit_cache


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

Membergroup message limits.

$messages_request


    protected
    static    object
    $messages_request

Database query used in PM::queryData().

$prop_aliases


    protected
        array<string|int, mixed>
    $prop_aliases
     = ['id_pm' => 'id', 'id_pm_head' => 'head', 'id_member_from' => 'member_from']

Alternate names for some object properties.

$recent


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

Holds the results of PM::getRecent().

The keys of this array are string representations of the parameters that PM::getRecent() was called with. The values are lists of PM IDs that match those parameters.

$backcompat


    private
    static    array<string|int, mixed>
    $backcompat
     = ['func_names' => ['old' => 'old', 'compose' => 'compose', 'compose2' => 'compose2', 'send' => 'sendpm', 'delete' => 'deleteMessages', 'markRead' => 'markMessages', 'getLatest' => 'getLatest', 'getRecent' => 'getRecent', 'countSent' => 'countSent', 'reportErrors' => 'messagePostError', 'isAccessible' => 'isAccessiblePM']]

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 personal message.
$props : array<string|int, mixed> = []: Properties to set for this message.

canAccess()

Checks whether the current user can see this personal message.


    public
                    canAccess([string $folders = 'both' ]) : bool

Parameters

$folders : string = 'both'

Return values

bool

compose()

Shows the form for composing a personal message.


    public
            static        compose() : void

compose2()

Validates a composed personal message and then passes it to PM::send() if it is valid. If errors were found, or if the user requested a preview, will return false.


    public
            static        compose2() : bool

Return values

bool —

Whether the PM could be sent.

countSent()

Counts the personal messages sent by the current user, with optional limits.


    public
            static        countSent([int $boundary = 0 ][, bool $greater_than = false ]) : int

Parameters

$boundary : int = 0
$greater_than : bool = false

Return values

int

delete()

Delete the specified personal messages.


    public
            static        delete(array<string|int, mixed>|null $personal_messages[, string|null $folder = null ][, array<string|int, mixed>|int|null $owner = null ]) : void

Parameters

$personal_messages : array<string|int, mixed>|null: An array containing the IDs of PMs to delete or null to delete all of them
$folder : string|null = null: Which "folder" to delete PMs from - 'sent' to delete them from the outbox, null or anything else to delete from the inbox
$owner : array<string|int, mixed>|int|null = null: An array of IDs of users whose PMs are being deleted, the ID of a single user or null to use the current user's ID

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.

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 PM::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 one or more personal messages.
$query_customizations : array<string|int, mixed> = []: Customizations to the SQL query.

Return values

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

Iterating over result gives PM instances.

getFormatted()

Generator that yields formatted PMs for use in a search results list.


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

Parameters

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

Return values

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

Iterating over result gives SearchResult instances.

getLatest()

Gets the ID of the most recent personal message sent by the current user.


    public
            static        getLatest() : int

Return values

int —

The ID of the mostly sent recent PM.

getRecent()

Gets the IDs of the most recent personal messages sent by the current user.


    public
            static        getRecent([string $sort = 'pm.id_pm' ][, bool $descending = true ][, int $limit = 0 ][, int $offset = 0 ]) : array<string|int, mixed>

Parameters

$sort : string = 'pm.id_pm': The column to sort by in the SQL query. Default: pmr.id_pm
$descending : bool = true: Whether to sort descending or ascending. Default: true.
$limit : int = 0: How many results to get. Zero for no limit. Default: 0.
$offset : int = 0: How many results to skip before retrieving the rest. Default: 0.

Return values

array<string|int, mixed> —

The IDs of the most recently sent PMs.

isAccessible()

Backward compatibilty wrapper around the non-static canAccess() method.


    public
            static        isAccessible(int $pmID[, string $folders = 'both' ]) : bool

Check if the PM is available to the current user.

Parameters

$pmID : int: The ID of the PM
$folders : string = 'both': Which folders this is valid for - can be 'inbox', 'outbox' or 'in_or_outbox'

Return values

bool —

Whether the PM is accessible in that folder for the current user

load()

Loads personal 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 PM::get() rather than PM::load().

Parameters

$ids : int|array<string|int, mixed>: The ID numbers of one or more personal 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.

markRead()

Mark the specified personal messages as read.


    public
            static        markRead([array<string|int, mixed>|null $personal_messages = null ][, int|null $label = null ][, int|null $owner = null ]) : void

Parameters

$personal_messages : array<string|int, mixed>|null = null: An array of PM IDs to mark or null to mark all.
$label : int|null = null: The ID of a label. If set, only messages with this label will be marked.
$owner : int|null = null: If owner is set, marks messages owned by that member id.

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.

old()

Returns the IDs of personal messages sent before a given time.


    public
            static        old(int $time) : array<string|int, mixed>

Parameters

$time : int: A Unix timestamp.

Return values

array<string|int, mixed> —

The IDs of personal messages sent before $time.

reportErrors()

Informs the user about an error in the message they wrote.


    public
            static        reportErrors(array<string|int, mixed> $error_types, array<string|int, mixed> $named_recipients[, array<string|int, mixed> $recipient_ids = [] ]) : void

Parameters

$error_types : array<string|int, mixed>: An array of strings indicating which type of errors occurred.
$named_recipients : array<string|int, mixed>: Names of recipients.
$recipient_ids : array<string|int, mixed> = []: IDs of recipients.

send()

Sends an personal message from the specified person to the specified people ($from defaults to the user)


    public
            static        send(array<string|int, mixed> $recipients, string $subject, string $message[, bool $store_outbox = false ][, array<string|int, mixed> $from = null ][, int $pm_head = 0 ]) : array<string|int, mixed>

Parameters

$recipients : array<string|int, mixed>: An array containing the arrays 'to' and 'bcc', both containing id_member's.
$subject : string: Should have no slashes and no html entities
$message : string: Should have no slashes and no html entities
$store_outbox : bool = false: Whether to store it in the sender's outbox
$from : array<string|int, mixed> = null: An array with the id, name, and username of the member.
$pm_head : int = 0: The ID of the chain being replied to - if any.

Return values

array<string|int, mixed> —

An array with log entries telling how many recipients were successful and which recipients it failed to send to.

queryData()

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

SearchResult extends PM in package SMF

Table of Contents

Properties

Methods

Properties

$body

$deleted_by_sender

$folder

$formatted

$from_name

$getter

$head

$id

$loaded

$member_from

$msgtime

$received

$subject

$subject_getter

$keep_all

$message_limit_cache

$messages_request

$prop_aliases

$recent

$backcompat

Methods

__construct()

Parameters

canAccess()

Parameters

Return values

compose()

compose2()

Return values

countSent()

Parameters

Return values

delete()

Parameters

exportStatic()

format()

Parameters

Return values

get()

Parameters

Return values

getFormatted()

Parameters

Return values

getLatest()

Return values

getRecent()

Parameters

Return values

isAccessible()

Parameters

Return values

load()

Parameters

Return values

markRead()

Parameters

offsetExists()

Parameters

Return values

offsetGet()

Parameters

offsetSet()

Parameters

offsetUnset()

Parameters

old()

Parameters

Return values

reportErrors()

Parameters

send()

Parameters

Return values

queryData()

SearchResult extends PM
in package

SMF