Documentation

Agora_Driver
in package

Agora_Driver:: provides the functions to access both threads and individual messages.

Copyright 2003-2017 Horde LLC (http://www.horde.org/)

See the enclosed file LICENSE for license information (GPL). If you did not receive this file, see http://www.horde.org/licenses/gpl.

Tags
author

Marko Djukic marko@oblo.com

author

Jan Schneider jan@horde.org

author

Duck duck@obala.net

Table of Contents

$_forum  : array<string|int, mixed>
Current forum data
$_forum_id  : string
Current forum ID
$_cache  : Horde_Cache
Cache object
$_charset  : string
Charset
$_db  : Horde_Db_Adapter
The database connection object.
$_forums_table  : string
Scope theads table name
$_scope  : string
The forums scope.
$_threads_table  : string
Scope theads table name
__construct()  : mixed
Constructor
_forumSequence()  : mixed
Increments or decrements a forum's message count.
allowAttachments()  : bool
Checks if attachments are allowed in messages for the current forum.
convertFromDriver()  : mixed
Converts a value from the driver's charset to the default charset.
convertToDriver()  : mixed
Converts a value from the default charset to the driver's charset.
countForums()  : mixed
Returns the number of forums.
countMessages()  : int
Returns the number of all messages (threads and replies) in a forum
countThreads()  : int
Returns the number of replies on a thread, or threads in a forum
dateFormat()  : string
Formats time according to user preferences.
deleteForum()  : bool
Deletes a forum, any subforums that are present and all messages contained in the forum and subforums.
deleteMessage()  : string
Deletes a message and all replies.
deleteThread()  : mixed
Deletes an entire message thread.
formatBody()  : mixed
Formats a message body.
formatSize()  : string
Formats file size.
getAttachmentLink()  : mixed
Constructs message attachments link.
getBanned()  : mixed
Get banned users from the current forum
getBareForums()  : array<string|int, mixed>
Get forums ids and titles
getForm()  : mixed
getForum()  : array<string|int, mixed>
Fetches a forum data.
getForums()  : mixed
Fetches a list of forums.
getMessage()  : mixed
Fetches a message.
getModerateList()  : mixed
Fetches a list of messages awaiting moderation. Selects all messages, irrespective of the thread root, which have the 'moderate' flag set in the attributes.
getThreadActions()  : mixed
getThreadRoot()  : mixed
getThreads()  : mixed
Returns a list of threads.
getThreadsUi()  : string
Returns a table showing the specified message list.
hasPermission()  : bool
Finds out if the user has the specified rights to the messages forum.
isHot()  : mixed
Returns true if the message is hot.
isNew()  : mixed
Returns true, has new posts since user last visit
isThreadLocked()  : bool
logView()  : bool
Logs a message view.
mergeThread()  : mixed
Merges two threads.
moderate()  : mixed
Approves one or more ids.
moveThread()  : mixed
Moves a thread to another forum.
newForum()  : int
Creates a new forum.
replyMessage()  : array<string|int, mixed>
Returns a hash with all information necessary to reply to a message.
saveForum()  : int
Saves a forum, either creating one if no forum ID is given or updating an existing one.
saveMessage()  : mixed
Saves the message.
search()  : array<string|int, mixed>
Searches forums for matching threads or posts.
setThreadLock()  : mixed
splitThread()  : mixed
Splits a thread on message id.
updateBan()  : mixed
Ban user on a specific forum.
updateModerator()  : mixed
Updates forum moderators.
_formatForums()  : array<string|int, mixed>|Traversable
Fetches a list of forums.
_formatThreads()  : mixed
Formats a message body.
_getCache()  : mixed
Get cache value
_getForums()  : mixed
Fetches a list of forums.
_setCache()  : mixed
Set cache value
_getCacheKey()  : mixed
Append namespace to cache key
_lastInForum()  : mixed
Update lastMessage in a Forum
_lastInThread()  : mixed
Update lastMessage in Thread
_sequence()  : mixed
Increments or decrements a thread's message count.
_updateCacheState()  : mixed
Increment namespace

Properties

$_forum

Current forum data

public array<string|int, mixed> $_forum

$_forum_id

Current forum ID

public string $_forum_id

$_cache

Cache object

protected Horde_Cache $_cache

$_charset

Charset

protected string $_charset

$_db

The database connection object.

protected Horde_Db_Adapter $_db

$_forums_table

Scope theads table name

protected string $_forums_table = 'agora_forums'

$_scope

The forums scope.

protected string $_scope

$_threads_table

Scope theads table name

protected string $_threads_table = 'agora_messages'

Methods

__construct()

Constructor

public __construct(mixed $scope, mixed $params) : mixed
Parameters
$scope : mixed
$params : mixed
Return values
mixed

_forumSequence()

Increments or decrements a forum's message count.

public _forumSequence(int $forum_id[, string $type = 'message' ][, int|string $diff = '+' ]) : mixed
Parameters
$forum_id : int

Forum to update

$type : string = 'message'

What to increment message, thread or view.

$diff : int|string = '+'

Incremental or decremental step, either a positive or negative integer, or a plus or minus sign.

Return values
mixed

allowAttachments()

Checks if attachments are allowed in messages for the current forum.

public allowAttachments() : bool
Return values
bool

Whether attachments allowed or not.

convertFromDriver()

Converts a value from the driver's charset to the default charset.

public convertFromDriver(mixed $value) : mixed
Parameters
$value : mixed

A value to convert.

Return values
mixed

The converted value.

convertToDriver()

Converts a value from the default charset to the driver's charset.

public convertToDriver(mixed $value) : mixed
Parameters
$value : mixed

A value to convert.

Return values
mixed

The converted value.

countForums()

Returns the number of forums.

public countForums() : mixed
Return values
mixed

countMessages()

Returns the number of all messages (threads and replies) in a forum

public countMessages() : int
Return values
int

The number of messages in forum or PEAR_Error on failure.

countThreads()

Returns the number of replies on a thread, or threads in a forum

public countThreads(int $thread_root) : int
Parameters
$thread_root : int

Thread to count.

Return values
int

The number of messages in thread or PEAR_Error on failure.

dateFormat()

Formats time according to user preferences.

public dateFormat(int $timestamp) : string
Parameters
$timestamp : int

Message timestamp.

Return values
string

Formatted date.

deleteForum()

Deletes a forum, any subforums that are present and all messages contained in the forum and subforums.

public deleteForum(int $forum_id) : bool
Parameters
$forum_id : int

The ID of the forum to delete.

Tags
throws
Agora_Exception
Return values
bool

True on success.

deleteMessage()

Deletes a message and all replies.

public deleteMessage(int $message_id) : string
Parameters
$message_id : int

The ID of the message to delete.

Tags
todo

Detele all related attachments from VFS.

throws
Agora_Exception
Return values
string

Thread ID on success.

deleteThread()

Deletes an entire message thread.

public deleteThread(int $thread_id) : mixed
Parameters
$thread_id : int

The ID of the thread to delete. If not specified will delete all the threads for the current forum.

Tags
throws
Agora_Exception
Return values
mixed

formatBody()

Formats a message body.

public formatBody(string $body) : mixed
Parameters
$body : string

Text to format.

Return values
mixed

formatSize()

Formats file size.

public formatSize(int $filesize) : string
Parameters
$filesize : int
Return values
string

Formatted filesize.

Constructs message attachments link.

public getAttachmentLink(mixed $message_id) : mixed
Parameters
$message_id : mixed
Tags
throws
Agora_Exception
Return values
mixed

getBanned()

Get banned users from the current forum

public getBanned() : mixed
Return values
mixed

getBareForums()

Get forums ids and titles

public getBareForums() : array<string|int, mixed>
Return values
array<string|int, mixed>

An array of forums and form names.

getForm()

public getForm(mixed $vars, mixed $title[, mixed $editing = false ][, mixed $new_forum = false ]) : mixed
Parameters
$vars : mixed
$title : mixed
$editing : mixed = false
$new_forum : mixed = false
Return values
mixed

getForum()

Fetches a forum data.

public getForum(int $forum_id) : array<string|int, mixed>
Parameters
$forum_id : int

The ID of the forum to fetch.

Tags
throws
Horde_Exception_NotFound
throws
Agora_Exception
Return values
array<string|int, mixed>

The forum hash or a PEAR_Error on failure.

getForums()

Fetches a list of forums.

public getForums(int $root_forum[, bool $formatted = true ][, string $sort_by = 'forum_name' ], int $sort_dir[, bool $add_scope = false ], string $from, string $count) : mixed
Parameters
$root_forum : int

The first level forum.

$formatted : bool = true

Whether to return the list formatted or raw.

$sort_by : string = 'forum_name'

The column to sort by.

$sort_dir : int

Sort direction, 0 = ascending, 1 = descending.

$add_scope : bool = false

Add parent forum if forum for another scopelication.

$from : string

The forum to start listing at.

$count : string

The number of forums to return.

Tags
todo

This function needs refactoring, as it doesn't return consistent results. For example when running with $formatted = false it will return an indexed array, but when running with $formatted = true the result is associative array.

throws
Agora_Exception
Return values
mixed

An array of forums or PEAR_Error on failure.

getMessage()

Fetches a message.

public getMessage(int $message_id) : mixed
Parameters
$message_id : int

The ID of the message to fetch.

Tags
throws
Horde_Exception_NotFound
throws
Agora_Exception
Return values
mixed

getModerateList()

Fetches a list of messages awaiting moderation. Selects all messages, irrespective of the thread root, which have the 'moderate' flag set in the attributes.

public getModerateList(string $sort_by, int $sort_dir) : mixed
Parameters
$sort_by : string

The column by which to sort.

$sort_dir : int

The direction by which to sort: 0 - ascending 1 - descending

Tags
throws
Agora_Exception
Return values
mixed

getThreadActions()

public getThreadActions() : mixed
Return values
mixed

getThreadRoot()

public getThreadRoot(mixed $message_id) : mixed
Parameters
$message_id : mixed
Tags
throws
Agora_Exception
Return values
mixed

getThreads()

Returns a list of threads.

public getThreads(int $thread_root[, bool $all_levels = false ][, string $sort_by = 'message_timestamp' ], int $sort_dir[, bool $message_view = false ][, string $link_back = '' ][, string $base_url = null ][, string $from = null ][, string $count = null ][, bool $nofollow = false ]) : mixed
Parameters
$thread_root : int

Message at which to start the thread. If null get all forum threads

$all_levels : bool = false

Show all child levels or just one level.

$sort_by : string = 'message_timestamp'

The column by which to sort.

$sort_dir : int

The direction by which to sort: 0 - ascending 1 - descending

$message_view : bool = false
$link_back : string = ''

A url to pass to the reply script which will be returned to after an insertion of a post. Useful in cases when this thread view is used in blocks to return to the original page rather than to Agora.

$base_url : string = null

An alternative URL where edit/delete links point to. Mainly for api usage. Takes "%p" as a placeholder for the parent message ID.

$from : string = null

The thread to start listing at.

$count : string = null

The number of threads to return.

$nofollow : bool = false

Whether to set the 'rel="nofollow"' attribute on linked URLs in the messages.

Return values
mixed

getThreadsUi()

Returns a table showing the specified message list.

public getThreadsUi(array<string|int, mixed> $threads, array<string|int, mixed> $col_headers[, bool $bodies = false ][, string $template_file = false ]) : string
Parameters
$threads : array<string|int, mixed>

A hash with the thread messages as returned by .

$col_headers : array<string|int, mixed>

A hash with the column headers.

$bodies : bool = false

Display the message bodies?

$template_file : string = false

Template to use.

Return values
string

The rendered message table.

hasPermission()

Finds out if the user has the specified rights to the messages forum.

public hasPermission([int $perm = Horde_Perms::READ ][, int $forum_id = null ][, string $scope = null ]) : bool
Parameters
$perm : int = Horde_Perms::READ

The permission level needed for access.

$forum_id : int = null

Forum to check permissions for.

$scope : string = null

Application scope to use.

Return values
bool

True if the user has the specified permissions.

isHot()

Returns true if the message is hot.

public isHot(mixed $views, mixed $last_post) : mixed
Parameters
$views : mixed
$last_post : mixed
Return values
mixed

isNew()

Returns true, has new posts since user last visit

public isNew(mixed $thread_id, mixed $last_post) : mixed
Parameters
$thread_id : mixed
$last_post : mixed
Return values
mixed

isThreadLocked()

public isThreadLocked(mixed $message_id) : bool
Parameters
$message_id : mixed
Return values
bool

logView()

Logs a message view.

public logView(mixed $thread_id) : bool
Parameters
$thread_id : mixed
Tags
throws
Agora_Exception
Return values
bool

True, if the view was logged, false if the message was aleredy seen

mergeThread()

Merges two threads.

public mergeThread(mixed $thread_from, int $message_id) : mixed
Parameters
$thread_from : mixed
$message_id : int

The ID of the message to merge to.

Tags
throws
Agora_Exception
Return values
mixed

moderate()

Approves one or more ids.

public moderate(string $action, array<string|int, mixed> $ids) : mixed
Parameters
$action : string

Whether to 'approve' or 'delete' messages.

$ids : array<string|int, mixed>

Array of message IDs.

Tags
throws
Agora_Exception
Return values
mixed

moveThread()

Moves a thread to another forum.

public moveThread(int $thread_id, int $forum_id) : mixed
Parameters
$thread_id : int

The ID of the thread to move.

$forum_id : int

The ID of the destination forum.

Tags
todo

Update the number of messages in the old/new forum

throws
Agora_Exception
Return values
mixed

newForum()

Creates a new forum.

public newForum(string $forum_name, mixed $owner) : int
Parameters
$forum_name : string

Forum name.

$owner : mixed
Tags
throws
Agora_Exception
Return values
int

ID of the new generated forum.

replyMessage()

Returns a hash with all information necessary to reply to a message.

public replyMessage(mixed $message) : array<string|int, mixed>
Parameters
$message : mixed

The ID of the parent message to reply to, or arry of its data.

Tags
throws
Horde_Exception_NotFound
throws
Agora_Exception
Return values
array<string|int, mixed>

A hash with all relevant information.

saveForum()

Saves a forum, either creating one if no forum ID is given or updating an existing one.

public saveForum(array<string|int, mixed> $info) : int
Parameters
$info : array<string|int, mixed>

The forum information to save consisting of: forum_id forum_author forum_parent_id forum_name forum_moderated forum_description forum_attachments

Tags
throws
Agora_Exception
Return values
int

The forum ID on success.

saveMessage()

Saves the message.

public saveMessage(array<string|int, mixed> $info) : mixed
Parameters
$info : array<string|int, mixed>

Array containing all the message data to save.

Tags
throws
Agora_Exception
Return values
mixed

Message ID on success or PEAR_Error on failure.

Searches forums for matching threads or posts.

public search(array<string|int, mixed> $filter[, string $sort_by = 'message_subject' ], int $sort_dir, string $from, string $count) : array<string|int, mixed>
Parameters
$filter : array<string|int, mixed>

Hash of filter criteria: 'forums' => Array of forum IDs to search. If not present, searches all forums. 'keywords' => Array of keywords to search for. If not present, finds all posts/threads. 'allkeywords' => Boolean specifying whether to find all keywords; otherwise, wants any keyword. False if not supplied. 'message_author' => Name of author to find posts by. If not present, any author. 'searchsubjects' => Boolean specifying whether to search subjects. True if not supplied. 'searchcontents' => Boolean specifying whether to search post contents. False if not supplied.

$sort_by : string = 'message_subject'

The column by which to sort.

$sort_dir : int

The direction by which to sort: 0 - ascending 1 - descending

$from : string

The thread to start listing at.

$count : string

The number of threads to return.

Tags
throws
Agora_Exception
Return values
array<string|int, mixed>

A search result hash where: 'results' => Array of messages. 'total => Total message number.

setThreadLock()

public setThreadLock(mixed $message_id, mixed $lock) : mixed
Parameters
$message_id : mixed
$lock : mixed
Return values
mixed

splitThread()

Splits a thread on message id.

public splitThread(int $message_id) : mixed
Parameters
$message_id : int

The ID of the message to split at.

Tags
throws
Agora_Exception
Return values
mixed

updateBan()

Ban user on a specific forum.

public updateBan(string $user[, int $forum_id = null ][, string $action = 'add' ]) : mixed
Parameters
$user : string

Moderator username.

$forum_id : int = null

Forum to add moderator to.

$action : string = 'add'

Action to peform ('add' or 'delete').

Return values
mixed

updateModerator()

Updates forum moderators.

public updateModerator(string $moderator[, int $forum_id = null ][, string $action = 'add' ]) : mixed
Parameters
$moderator : string

Moderator username.

$forum_id : int = null

Forum to add moderator to.

$action : string = 'add'

Action to peform ('add' or 'delete').

Tags
throws
Agora_Exception
Return values
mixed

_formatForums()

Fetches a list of forums.

protected _formatForums(int $forums) : array<string|int, mixed>|Traversable
Parameters
$forums : int

Forums to format

Tags
throws
Agora_Exception
Return values
array<string|int, mixed>|Traversable

An array of forums.

_formatThreads()

Formats a message body.

protected _formatThreads(array<string|int, mixed>|Traversable $messages[, string $sort_by = 'message_modifystamp' ][, bool $format = false ], int $thread_root) : mixed
Parameters
$messages : array<string|int, mixed>|Traversable

Messages to format

$sort_by : string = 'message_modifystamp'

List format order

$format : bool = false

Format messages body

$thread_root : int

Thread root

Return values
mixed

_getCache()

Get cache value

protected _getCache(mixed $key, mixed $thread) : mixed
Parameters
$key : mixed
$thread : mixed
Return values
mixed

_getForums()

Fetches a list of forums.

protected _getForums(int $root_forum[, bool $formatted = true ][, string $sort_by = 'forum_name' ], int $sort_dir[, bool $add_scope = false ], string $from, string $count) : mixed
Parameters
$root_forum : int

The first level forum.

$formatted : bool = true

Whether to return the list formatted or raw.

$sort_by : string = 'forum_name'

The column to sort by.

$sort_dir : int

Sort direction, 0 = ascending, 1 = descending.

$add_scope : bool = false

Add parent forum if forum for another scopelication.

$from : string

The forum to start listing at.

$count : string

The number of forums to return.

Return values
mixed

An array of forums or PEAR_Error on failure.

_setCache()

Set cache value

protected _setCache(mixed $key, mixed $value, mixed $thread) : mixed
Parameters
$key : mixed
$value : mixed
$thread : mixed
Return values
mixed

_getCacheKey()

Append namespace to cache key

private _getCacheKey(mixed $key, mixed $thread) : mixed
Parameters
$key : mixed
$thread : mixed
Return values
mixed

_lastInForum()

Update lastMessage in a Forum

private _lastInForum(int $forum_id, int $message_id[, string $message_author = '' ], int $message_timestamp) : mixed
Parameters
$forum_id : int

Forum to update

$message_id : int

Last message id

$message_author : string = ''

Last message author

$message_timestamp : int

Last message timestamp

Tags
throws
Agora_Exception
Return values
mixed

_lastInThread()

Update lastMessage in Thread

private _lastInThread(int $thread_id, int $message_id[, string $message_author = '' ], int $message_timestamp) : mixed
Parameters
$thread_id : int

Thread to update

$message_id : int

Last message id

$message_author : string = ''

Last message author

$message_timestamp : int

Last message timestamp

Tags
throws
Agora_Exception
Return values
mixed

_sequence()

Increments or decrements a thread's message count.

private _sequence(int $thread_id[, int|string $diff = '+' ]) : mixed
Parameters
$thread_id : int

Thread to update.

$diff : int|string = '+'

Incremental or decremental step, either a positive or negative integer, or a plus or minus sign.

Return values
mixed

_updateCacheState()

Increment namespace

private _updateCacheState(mixed $thread) : mixed
Parameters
$thread : mixed
Return values
mixed

Search results