XenForo Reference Guide for Developer
Back to top  

Model for conversations.

Models don't share that much, so most implementations will be adding methods onto this class. This class simply provides helper methods for common actions.

package XenForo_Conversation

 Methods

Constructor.

__construct() 
Inherited

Use create() statically unless you know what you're doing.

inherited_from \XenForo_Model::__construct()

Add the details of a new conversation reply to conversation recipients.

addConversationReplyToRecipients(array $conversation, array $replyUser, array $messageInfo) : array

Parameters

$conversation

array

Conversation info

$replyUser

arraynull

Information about the user who replied

$messageInfo

arraynull

Array containing 'message', which is the text the message being sent

Returns

array$recipients

Adds a join to the set of fetch options.

addFetchOptionJoin(array $fetchOptions, integer $join) 
Inherited

Join should be one of the constants.

inherited_from \XenForo_Model::addFetchOptionJoin()

Parameters

$fetchOptions

array

$join

integer

Adds the equivalent of a limit clause using position-based limits.

addPositionLimit(string $table, integer $limit, integer $offset, string $column) : string
Inherited

It no limit value is specified, nothing will be returned.

This must be added within a WHERE clause. If a clause is required, it will begin with "AND", so ensure there is a condition before it.

inherited_from \XenForo_Model::addPositionLimit()

Parameters

$table

string

Name of the table alias to prefix. May be blank for no table reference.

$limit

integer

Number of records to limit to; ignored if <= 0

$offset

integer

Offset from the start of the records. 0+

$column

string

Name of the column that is storing the position

Returns

stringPosition limit clause if needed

Calculates the allowed number of additional conversation receiptions the viewing user can add to the given conversation.

allowedAdditionalConversationRecipients(array $conversation, array $viewingUser) : integer

Parameters

$conversation

array

Conversation; if empty array, assumes new conversation

$viewingUser

arraynull

Returns

integer-1 means unlimited; 0 is no more invites; other is remaining count

Ensures that a valid cut-off operator is passed.

assertValidCutOffOperator(string $operator) 
Inherited
inherited_from \XenForo_Model::assertValidCutOffOperator()

Parameters

$operator

string

Determines if the specified user can edit the conversation.

canEditConversation(array $conversation, string $errorPhraseKey, array $viewingUser) : boolean

Does not check conversation viewing permissions.

Parameters

$conversation

array

$errorPhraseKey

string

Returned phrase key for a specific error

$viewingUser

arraynull

Returns

boolean

Determines if the specified user can edit the specified message within a conversation

canEditMessage(array $message, array $conversation, string $errorPhraseKey, array $viewingUser) : boolean

Parameters

$message

array

$conversation

array

$errorPhraseKey

string

$viewingUser

arraynull

Returns

boolean

Determines if the specified user can invite users the conversation.

canInviteUsersToConversation(array $conversation, string $errorPhraseKey, array $viewingUser) : boolean

Does not check conversation viewing permissions.

Parameters

$conversation

array

$errorPhraseKey

string

Returned phrase key for a specific error

$viewingUser

arraynull

Returns

boolean

Check permission to view a reported conversation

canManageReportedMessage(array $message, array $conversation, string $errorPhraseKey, array $viewingUser) : boolean

Parameters

$message

array

$conversation

array

$errorPhraseKey

string

$viewingUser

arraynull

Returns

boolean

Determines if the specified user can reply to the conversation.

canReplyToConversation(array $conversation, string $errorPhraseKey, array $viewingUser) : boolean

Does not check conversation viewing permissions.

Parameters

$conversation

array

$errorPhraseKey

string

Returned phrase key for a specific error

$viewingUser

arraynull

Returns

boolean

Checks that the viewing user may report the specified conversation message

canReportMessage(array $message, array $conversation, string | boolean $errorPhraseKey, array $viewingUser) : boolean

Parameters

$message

array

$conversation

array

$errorPhraseKey

stringboolean

$viewingUser

arraynull

Returns

boolean

Determines if the viewing user can start a conversation with the given user.

canStartConversationWithUser(array $user, string $errorPhraseKey, array $viewingUser) : boolean

Does not check standard conversation permissions.

Parameters

$user

array

$errorPhraseKey

string

$viewingUser

arraynull

Returns

boolean

Determines if the viewing user can start conversations in general.

canStartConversations(string $errorPhraseKey, array $viewingUser) : boolean

Parameters

$errorPhraseKey

string

$viewingUser

arraynull

Returns

boolean

Determines if a new attachment can be posted in the specified conversation, with the given permissions.

canUploadAndManageAttachment(array $conversation, string $errorPhraseKey, array $viewingUser) : boolean

If no permissions are specified, permissions are retrieved from the currently visiting user. This does not check viewing permissions.

Parameters

$conversation

array

Info about the conversation posting in

$errorPhraseKey

string

Returned phrase key for a specific error

$viewingUser

arraynull

Returns

boolean

Determines if the specified user can view attachments in the specified conversation

canViewAttachmentOnConversation(array $conversation, string $errorPhraseKey, array $viewingUser) : boolean

Parameters

$conversation

array

$errorPhraseKey

string

$viewingUser

arraynull

Returns

boolean

Determines if the specified user can view an attachment to the specified message

canViewAttachmentOnConversationMessage(array $message, array $conversation, string $errorPhraseKey, array $viewingUser) : boolean

Parameters

$message

array

$conversation

array

$errorPhraseKey

string

$viewingUser

arraynull

Returns

boolean

Gets the total number of conversations that a user has.

countConversationsForUser(integer $userId, array $conditions) : integer

Parameters

$userId

integer

$conditions

array

Conditions for the WHERE clause

Returns

integer

Count the number of messages before a given date in a conversation.

countMessagesBeforeDateInConversation(integer $conversationId, integer $messageDate) : integer

Parameters

$conversationId

integer

$messageDate

integer

Returns

integer

Gets the count of unread conversations for the specified user.

countUnreadConversationsForUser(integer $userId) : integer

Parameters

$userId

integer

Returns

integer

Factory method to get the named model.

create(string $class) : \XenForo_Model
InheritedStatic

The class must exist or be autoloadable or an exception will be thrown.

inherited_from \XenForo_Model::create()

Parameters

$class

string

Class to load

Returns

\XenForo_Model

Delets a conversation record for a specific user.

deleteConversationForUser(integer $conversationId, integer $userId, string $deleteType) 

If all users have deleted the conversation, it will be completely removed.

Parameters

$conversationId

integer

$userId

integer

$deleteType

string

Type of deletion (either delete, or delete_ignore)

Fetches results from the database with each row keyed according to preference.

fetchAllKeyed(string $sql, string $key, mixed $bind, string $nullPrefix) : array
Inherited

The 'key' parameter provides the column name with which to key the result. For example, calling fetchAllKeyed('SELECT item_id, title, date FROM table', 'item_id') would result in an array keyed by item_id: [$itemId] => array('item_id' => $itemId, 'title' => $title, 'date' => $date)

Note that the specified key must exist in the query result, or it will be ignored.

inherited_from \XenForo_Model::fetchAllKeyed()

Parameters

$sql

string

SQL to execute

$key

string

Column with which to key the results array

$bind

mixed

Parameters for the SQL

$nullPrefix

string

If the key is null, prefix the counter with this

Returns

array

Return a list of users that have received conversations that the specified user has receved, where the recieving user matches the given username search string

findConversationRecipientsForUser(integer $userId, string $searchString) : array

Parameters

$userId

integer

$searchString

string

Returns

array

Return a list of users that have posted in conversations that the specified user has receved, where the recieving user matches the given username search string

findConversationRespondersForUser(integer $userId, string $searchString) : array

Parameters

$userId

integer

$searchString

string

Returns

array

Return a list of users that have started conversations that the specified user has receved, where the starting user matches the given username search string

findConversationStartersForUser(integer $userId, string $searchString) : array

Parameters

$userId

integer

$searchString

string

Returns

array

Gets the attachments that belong to the given messages, and merges them in with their parent message (in the attachments key).

getAndMergeAttachmentsIntoConversationMessages(array $messages) : array

The attachments key will not be set if no attachments are found for the message.

Parameters

$messages

array

Returns

arrayMessages, with attachments added where necessary

Gets the set of attachment params required to allow uploading.

getAttachmentParams(array $conversation, array $contentData, array $viewingUser) : array | false

Parameters

$conversation

array

$contentData

array

Information about the content, for URL building

$viewingUser

arraynull

Returns

arrayfalse

Gets a list of SQL conditions in the format for a clause.

getConditionsForClause(array $sqlConditions) : string
Inherited

This always returns a value that can be used in a clause such as WHERE.

inherited_from \XenForo_Model::getConditionsForClause()

Parameters

$sqlConditions

array

Returns

string

Gets the specified field from a content type, if specified for that type.

getContentTypeField(string $contentType, string $fieldName) : string | false
Inherited
inherited_from \XenForo_Model::getContentTypeField()

Parameters

$contentType

string

$fieldName

string

Returns

stringfalse

Gets the value of the specified field for each content type that has that field.

getContentTypesWithField(string $fieldName) : array
Inherited
inherited_from \XenForo_Model::getContentTypesWithField()

Parameters

$fieldName

string

Returns

arrayFormat: [content type] => field value

Gets the specified user conversation.

getConversationForUser(integer $conversationId, integer | array $viewingUser, array $fetchOptions) : array | false

Parameters

$conversationId

integer

$viewingUser

integerarray

Can be a user array, or a user ID (for B.C. purposes)

$fetchOptions

array

Options for extra data to fetch

Returns

arrayfalse

Gets the specified conversation master record.

getConversationMasterById(integer $conversationId) : array | false

Parameters

$conversationId

integer

Returns

arrayfalse

Gets the specified conversation message record.

getConversationMessageById(integer $messageId) : array | false

Parameters

$messageId

integer

Returns

arrayfalse

Get messages within a given conversation.

getConversationMessages(integer $conversationId, array $fetchOptions) : array

Parameters

$conversationId

integer

$fetchOptions

array

Options for extra data to fetch

Returns

arrayFormat [message id] => info

Gets info about a single recipient of a conversation.

getConversationRecipient(integer $conversationId, integer $userId, array $fetchOptions) : array | false

Parameters

$conversationId

integer

$userId

integer

$fetchOptions

array

Options for extra data to fetch

Returns

arrayfalse

Gets information about all recipients of a conversation.

getConversationRecipients(integer $conversationId, array $fetchOptions) : array

Parameters

$conversationId

integer

$fetchOptions

array

Options for extra data to fetch

Returns

arrayFormat: [user id] => info

Get conversations that a user can see, ordered by the latest message first.

getConversationsForUser(integer $userId, array $conditions, array $fetchOptions) : array

Parameters

$userId

integer

$conditions

array

Conditions for the WHERE clause

$fetchOptions

array

Options for extra data to fetch

Returns

arrayFormat: [conversation id] => info

Get the specified conversations that a user can see, ordered by last message first.

getConversationsForUserByIds(integer $userId, array $conversationIds) : array

Parameters

$userId

integer

$conversationIds

array

Returns

arrayFormat: [conversation id] => info

Returns the last few page numbers of a conversation

getLastPageNumbers(integer $replyCount) : array | boolean

Parameters

$replyCount

integer

Returns

arrayboolean

Gets the maximum message date in a list of messages.

getMaximumMessageDate(array $messages) : integer

Parameters

$messages

array

Returns

integerMax message date timestamp; 0 if no messages

Gets the specified model object from the cache.

getModelFromCache(string $class) : \XenForo_Model
Inherited

If it does not exist, it will be instantiated.

inherited_from \XenForo_Model::getModelFromCache()

Parameters

$class

string

Name of the class to load

Returns

\XenForo_Model

Finds the newest conversation messages after the specified date.

getNewestConversationMessagesAfterDate(integer $conversationId, integer $date, array $fetchOptions) : array

Parameters

$conversationId

integer

$date

integer

$fetchOptions

array

Returns

array[message id] => info

Gets the next message in a conversation, post after the specified date.

getNextMessageInConversation(integer $conversationId, integer $messageDate) : array | false

This is useful for finding the first unread message, for example.

Parameters

$conversationId

integer

$messageDate

integer

Finds first message posted after this

Returns

arrayfalse

Gets the order by clause for an SQL query.

getOrderByClause(array $choices, array $fetchOptions, string $defaultOrderSql) : string
Inherited
inherited_from \XenForo_Model::getOrderByClause()

Parameters

$choices

array

$fetchOptions

array

$defaultOrderSql

string

Returns

stringOrder by clause or empty string

Gets the quote text for the specified conversation message.

getQuoteForConversationMessage(array $message, integer $maxQuoteDepth) : string

Parameters

$message

array

$maxQuoteDepth

integer

Max depth of quotes (-1 for unlimited)

Returns

string

Inserts an alert for this conversation.

insertConversationAlert(array $conversation, array $alertUser, string $action, array $triggerUser, array $extraData, array $messageInfo) 

Parameters

$conversation

array

$alertUser

array

User to notify

$action

string

Action taken out (values: insert, reply, join)

$triggerUser

arraynull

User triggering the alert; defaults to last user to reply

$extraData

arraynull

$messageInfo

arraynull

Array containing the text of the message being sent (if applicable) as 'message'

Insert a new conversation recipient record.

insertConversationRecipient(array $conversation, $userId, array $existingRecipient, string $insertState) : boolean

Parameters

$conversation

array

Conversation info

$userId

$existingRecipient

array

Information about the existing recipient record (if there is one)

$insertState

string

State to insert the conversation for with this user

Returns

booleanTrue if an insert was required (may be false if user is already an active recipient or is ignoring)

Applies a limit clause to the provided query if a limit value is specified.

limitQueryResults(string $query, integer $limit, integer $offset) : string
Inherited

If the limit value is 0 or less, no clause is applied.

inherited_from \XenForo_Model::limitQueryResults()

Parameters

$query

string

SQL query to run

$limit

integer

Number of records to limit to; ignored if <= 0

$offset

integer

Offset from the start of the records. 0+

Returns

stringQuery with limit applied if necessary

Marks the conversation as read to a certain point for a user.

markConversationAsRead(integer $conversationId, integer $userId, integer $newReadDate, integer $lastMessageDate, boolean $updateVisitor) 

Parameters

$conversationId

integer

$userId

integer

$newReadDate

integer

Timestamp to mark as read until

$lastMessageDate

integer

Date of last message; only marks whole conversation read if more than this date

$updateVisitor

boolean

If true, reduces the conversations_unread counter for the visitor; should be false for replies

Marks the conversation as (completely) unread for a user.

markConversationAsUnread(integer $conversationId, integer $userId) 

Parameters

$conversationId

integer

$userId

integer

Prepare a conversation for display or further processing.

prepareConversation(array $conversation) : array

Parameters

$conversation

array

Returns

array

Prepares a set of conditions against which to select conversations.

prepareConversationConditions(array $conditions, array $fetchOptions) : string

Parameters

$conditions

array

List of conditions. --popupMode (boolean) constrains results to unread, or sent within timeframe specified by options->conversationPopupExpiryHours

$fetchOptions

array

The fetch options that have been provided. May be edited if criteria requires.

Returns

stringCriteria as SQL for where clause

prepareConversationFetchOptions() 

prepareConversationFetchOptions(array $fetchOptions) 

Parameters

$fetchOptions

Prepare a collection of conversations for display or further processing.

prepareConversations(array $conversations) : array

Parameters

$conversations

array

Returns

array

Prepares the limit-related fetching options that can be applied to various queries.

prepareLimitFetchOptions(array $fetchOptions) : array
Inherited

Includes: limit, offset, page, and perPage.

inherited_from \XenForo_Model::prepareLimitFetchOptions()

Parameters

$fetchOptions

array

Unprepared options

Returns

arrayLimit options; keys: limit, offset

Prepare a message for display or further processing.

prepareMessage(array $message, array $conversation) : array

Parameters

$message

array

$conversation

array

Returns

arrayPrepared message

Prepare a collection of messages (in the same conversation) for display or further processing.

prepareMessages(array $messages, array $conversation) : array

Parameters

$messages

array

$conversation

array

Returns

arrayPrepared messages

Prepares state related fetch limits, based on the list of conditions.

prepareStateLimitFromConditions(array $fetchOptions, string $table, string $stateField, string $userField) : string
Inherited

Looks for keys "deleted" and "moderated".

inherited_from \XenForo_Model::prepareStateLimitFromConditions()

Parameters

$fetchOptions

array

$table

string

Name of the table to prefix the state and user fields with

$stateField

string

Name of the field that holds the state

$userField

string

Name of the field that holds the user ID

Returns

stringSQL condition to limit state

Recalculates the unread conversation count for the specified user.

rebuildUnreadConversationCountForUser(integer $userId) 

Parameters

$userId

integer

Reset an entry or the entire local cache.

resetLocalCacheData($name) 
Inherited

This can be used if you know when some cached data has expired.

inherited_from \XenForo_Model::resetLocalCacheData()

Parameters

$name

Sets whether we're allowed to read values from the cache on a model-level.

setAllowCachedRead(boolean $allowCachedRead) 
Inherited

This may be controllable on an individual level basis, if the implementation allows it.

inherited_from \XenForo_Model::setAllowCachedRead()

Parameters

$allowCachedRead

boolean

Injects a local cache value.

setLocalCacheData(string $name, $value) 
Inherited

This should only be used if you know what you're doing or for testing purposes!

Note that you cannot get the existing data via the public interface. If you think you need the set data, use a new object. It defaults to empty. :)

inherited_from \XenForo_Model::setLocalCacheData()

Parameters

$name

string

$value

Standardizes a set of node permissions and a user ID to always have appropriate data.

standardizeNodePermissionsAndUserId(integer $nodeId, array | null $permissions, integer | null $userId) 
Inherited

If an invalid permission set or user ID is provided, the current visitor's will be used.

inherited_from \XenForo_Model::standardizeNodePermissionsAndUserId()

Parameters

$nodeId

integer

Node permissions are for

$permissions

arraynull

Permissions for node or null to use current visitor's permissions

$userId

integernull

User permissions belong to or null to use current visitor

Standardizes a permission combination and user ID to always have appropriate data.

standardizePermissionCombinationIdAndUserId(integer | null $permissionCombinationId, integer | null $userId) 
Inherited

If null, users current visitor's values.

inherited_from \XenForo_Model::standardizePermissionCombinationIdAndUserId()

Parameters

$permissionCombinationId

integernull

Permission combination ID or null to use current visitor

$userId

integernull

User permissions belong to or null to use current visitor

Standardizes a set of permissions and a user ID to always have appropriate data.

standardizePermissionsAndUserId(array | null $permissions, integer | null $userId) 
Inherited

If an invalid permission set or user ID is provided, the current visitor's will be used.

inherited_from \XenForo_Model::standardizePermissionsAndUserId()

Parameters

$permissions

arraynull

Global pPermissions or null to use current visitor's permissions

$userId

integernull

User permissions belong to or null to use current visitor

Standardizes a viewing user reference array.

standardizeViewingUserReference(array $viewingUser) 
Inherited

This array must contain all basic user info (preferably all user info) and include global permissions in a "permissions" key. If not an array or missing a user_id, the visitor's values will be used.

inherited_from \XenForo_Model::standardizeViewingUserReference()

Parameters

$viewingUser

arraynull

Standardizes the viewing user reference for the specific node.

standardizeViewingUserReferenceForNode(integer $nodeId, array $viewingUser, array $nodePermissions) 
Inherited
inherited_from \XenForo_Model::standardizeViewingUserReferenceForNode()

Parameters

$nodeId

integer

$viewingUser

arraynull

Viewing user; if null, use visitor

$nodePermissions

arraynull

Permissions for this node; if null, use visitor's

Helper to unserialize permissions in a list of items.

unserializePermissionsInList(array $items, string $serializedKey, string $targetKey) : array
Inherited
inherited_from \XenForo_Model::unserializePermissionsInList()

Parameters

$items

array

List of items

$serializedKey

string

Key where serialized permissions are

$targetKey

string

Key where unserialized permissions will go

Returns

arrayList of items with permissions unserialized

_getAlertModel() 

_getAlertModel() : \XenForo_Model_Alert

Returns

\XenForo_Model_Alert

_getAttachmentModel() 

_getAttachmentModel() : \XenForo_Model_Attachment.

Returns

\XenForo_Model_Attachment.

Helper method to get the cache object.

_getCache(boolean $forceCachedRead) : \Zend_Cache_Core | \Zend_Cache_Frontend | false
Inherited

If cache reads are disabled, this will return false.

inherited_from \XenForo_Model::_getCache()

Parameters

$forceCachedRead

boolean

If true, the global "allow cached read" value is ignored

Returns

\Zend_Cache_Core\Zend_Cache_Frontendfalse

Gets the data registry model.

_getDataRegistryModel() : \XenForo_Model_DataRegistry
Inherited
inherited_from \XenForo_Model::_getDataRegistryModel()

Returns

\XenForo_Model_DataRegistry

Helper method to get the database object.

_getDb() : \Zend_Db_Adapter_Abstract
Inherited
inherited_from \XenForo_Model::_getDb()

Returns

\Zend_Db_Adapter_Abstract

Gets the named entry from the local cache.

_getLocalCacheData(string $name) : mixed
Inherited
inherited_from \XenForo_Model::_getLocalCacheData()

Parameters

$name

string

Returns

mixed

_getUserModel() 

_getUserModel() : \XenForo_Model_User

Returns

\XenForo_Model_User

Fetches a list of users matching the user ID and user name search criteria.

_getUsersMatchingCriteria(array $userIds, string $searchString) : array

Used in conjunction with this class's findConversation[x]ForUser() methods.

Parameters

$userIds

array

$searchString

string

Returns

array

Update the read date record for a conversation

_updateConversationReadDate(integer $conversationId, integer $userId, integer $newReadDate, \Zend_Db_Adapter_Abstract $db) : integer

Parameters

$conversationId

integer

$userId

integer

$newReadDate

integer

$db

\Zend_Db_Adapter_Abstract

Returns

integer$newReadDate

 Properties

 

$_allowCachedRead : boolean
Inherited

If not, it should be retrieved from the source.

inherited_from \XenForo_Model::$$_allowCachedRead
 

$_cache : \Zend_Cache_Core | \Zend_Cache_Frontend
Inherited
inherited_from \XenForo_Model::$$_cache
 

$_db : \Zend_Db_Adapter_Abstract
Inherited
inherited_from \XenForo_Model::$$_db
 

$_localCacheData : array
Inherited

This data is generally treated as canonical, even if {$_allowCachedRead} is false.

inherited_from \XenForo_Model::$$_localCacheData
 

$_modelCache : array
Inherited
inherited_from \XenForo_Model::$$_modelCache

 Constants

 

FETCH_FIRST_MESSAGE

FETCH_FIRST_MESSAGE 
 

FETCH_LAST_MESSAGE_AVATAR

FETCH_LAST_MESSAGE_AVATAR 
 

FETCH_RECEIVED_BY

FETCH_RECEIVED_BY