/mysql.php

Description
Description | Includes | Constants | Functions

This script implements a MySQL Phorum database layer.

The other Phorum code does not care how data is stored. The only requirement is that it is returned from these functions in the right way. This means each database can use as many or as few tables as it likes. It can store the fields anyway it wants.

The only thing to worry about is the table_prefix for the tables. all tables for a Phorum install should be prefixed with the table_prefix that will be entered in include/db/config.php. This will allow multiple Phorum installations to use the same database.

  • copyright: 2010, Phorum Development Team
  • todo: phorum_api_user_check_access() is used in this layer, but the include file for that is not included here. Keep it like that or add the required include? Or is it functionality that doesn't belong here and could better go into the core maybe?
  • license: Phorum
Includes
Description | Includes | Constants | Functions
include ($extfile) (line 7746)
Constants
Description | Includes | Constants | Functions
DB_CLOSE_CONN = 11 (line 175)

Function call parameter $return for phorum_db_interact().

Makes the function close the connection to the database. The function will return no data.

DB_DUPFIELDNAMEOK = 4 (line 182)

Constant for the phorum_db_interact() function call $flags parameter.

DB_DUPKEYNAMEOK = 8 (line 183)

Constant for the phorum_db_interact() function call $flags parameter.

DB_DUPKEYOK = 16 (line 184)

Constant for the phorum_db_interact() function call $flags parameter.

DB_GLOBALQUERY = 64 (line 186)

Constant for the phorum_db_interact() function call $flags parameter.

DB_MASTERQUERY = 128 (line 187)

Constant for the phorum_db_interact() function call $flags parameter.

DB_MISSINGTABLEOK = 2 (line 181)

Constant for the phorum_db_interact() function call $flags parameter.

DB_NOCONNECTOK = 1 (line 180)

Constant for the phorum_db_interact() function call $flags parameter.

DB_RETURN_ASSOC = 5 (line 135)

Function call parameter $return for phorum_db_interact().

Makes the function return a single database row for a SQL query as an associative array

DB_RETURN_ASSOCS = 6 (line 142)

Function call parameter $return for phorum_db_interact().

Makes the function return an array of rows for a SQL query as associative arrays.

DB_RETURN_CONN = 0 (line 104)

Function call parameter $return for phorum_db_interact().

Makes the function return a database connection handle.

DB_RETURN_ERROR = 10 (line 168)

Function call parameter $return for phorum_db_interact().

Makes the function return an error for a SQL query or NULL if there was no error.

DB_RETURN_NEWID = 9 (line 161)

Function call parameter $return for phorum_db_interact().

Makes the function return the new auto_increment id value for an insert SQL query.

DB_RETURN_QUOTED = 1 (line 110)

Function call parameter $return for phorum_db_interact().

Makes the function return a SQL quoted value.

DB_RETURN_RES = 2 (line 116)

Function call parameter $return for phorum_db_interact().

Makes the function return the query statement handle for a SQL query.

DB_RETURN_ROW = 3 (line 122)

Function call parameter $return for phorum_db_interact().

Makes the function return a single database row for a SQL query.

DB_RETURN_ROWCOUNT = 8 (line 154)

Function call parameter $return for phorum_db_interact().

Makes the function return the number of selected rows for a SQL query.

DB_RETURN_ROWS = 4 (line 128)

Function call parameter $return for phorum_db_interact().

Makes the function return an array of rows for a SQL query.

DB_RETURN_VALUE = 7 (line 148)

Function call parameter $return for phorum_db_interact().

Makes the function return a single value for a SQL query.

DB_TABLEEXISTSOK = 32 (line 185)

Constant for the phorum_db_interact() function call $flags parameter.

LIST_RECENT_MESSAGES = 0 (line 194)

Constant for the phorum_db_get_recent_messages() function call $list_type parameter.

LIST_RECENT_THREADS = 1 (line 195)

Constant for the phorum_db_get_recent_messages() function call $list_type parameter.

LIST_UPDATED_THREADS = 2 (line 196)

Constant for the phorum_db_get_recent_messages() function call $list_type parameter.

Functions
Description | Includes | Constants | Functions
phorum_db_add_forum (line 2367)

Create a forum.

  • return: The forum_id that was assigned to the new forum.
integer phorum_db_add_forum (array $forum)
  • array $forum: The forum to create. This is an array, which should contain the following fields: name, active, description, template, folder_flag, parent_id, list_length_flat, list_length_threaded, read_length, moderation, threaded_list, threaded_read, float_to_top, display_ip_address, allow_email_notify, language, email_moderators, display_order, edit_post, pub_perms, reg_perms.
phorum_db_add_group (line 2868)

Add a group. This will merely create the group in the database. For changing settings for the group, the function phorum_db_update_group() has to be used.

  • return: The group id of the newly created group.
integer phorum_db_add_group (string $group_name, [integer $group_id = 0])
  • string $group_name: The name to assign to the group.
  • integer $group_id: The group id to assign to the group or 0 (zero) to assign a new group id. Assigning a specific group id is and should only be used by conversion scripts.
phorum_db_add_message_edit (line 2426)

Add a message-edit item

  • return: The tracking_id that was assigned to that edit
integer phorum_db_add_message_edit (array $edit_data)
  • array $edit_data: The edit_data to add. This is an array, which should contain the following fields: diff_body, diff_subject, time, message_id and user_id.
phorum_db_check_connection (line 292)
  • return: TRUE if a connection can be made, FALSE otherwise.
  • todo:

    we can save a function call by directly calling phorum_db_interact(). I'm also not sure if we need to do this check from common.php. We could take care of this in the db layer error handling too. Have to think about this ...

    Checks if a database connection can be made.

boolean phorum_db_check_connection ()
phorum_db_close_connection (line 306)

Close the database connection.

void phorum_db_close_connection ()
phorum_db_close_thread (line 2307)

Close a thread for posting.

void phorum_db_close_thread (integer $thread_id)
  • integer $thread_id: The id of the thread that has to be closed.
phorum_db_create_tables (line 7210)

Create the tables that are needed in the database. This function will only be called at install time. After installation, changes in the database schema will be handled by the database upgrade system.

  • return: NULL on success or an error message on failure.
  • todo: It might be nice to have some feedback mechanism through a callback. Using that, table create status can be provided to the interface which is creating the tables. This is especially useful in case the create process fails at some point, in which case you currently have no good feedback about the create table progress.
mixed phorum_db_create_tables ()
phorum_db_delete_group (line 2997)

Delete a group.

void phorum_db_delete_group (integer $group_id)
  • integer $group_id: The id of the group to delete.
phorum_db_delete_message (line 1113)

Delete a message or a message tree from the database.

void phorum_db_delete_message (integer $message_id, [integer $mode = PHORUM_DELETE_MESSAGE])
  • integer $message_id: The message_id of the message which should be deleted.
  • integer $mode: The mode of deletion. This is one of:
    • PHORUM_DELETE_MESSAGE: Delete a message and reconnect its reply messages to the parent of the deleted message.
    • PHORUM_DELETE_TREE: Delete a message and all its reply messages.
phorum_db_del_banitem (line 5544)

Delete a single ban item from the ban lists.

void phorum_db_del_banitem (integer $banid)
  • integer $banid: The id of the ban item to delete.
phorum_db_drop_folder (line 2589)

Drop a forum folder. If the folder contains child forums or folders, then the parent_id for those will be updated to point to the parent of the folder that is being dropped.

void phorum_db_drop_folder (integer $forum_id)
  • integer $forum_id: The id of the folder to drop.
phorum_db_drop_forum (line 2521)

Drop a forum and all of its messages.

void phorum_db_drop_forum (integer $forum_id)
  • integer $forum_id: The id of the forum to drop.
phorum_db_file_delete (line 4603)

Delete a file.

  • return: True if the file was deleted successfully. This function will always return TRUE, so we could do without a return value. The return value is here for backward compatibility.
boolean phorum_db_file_delete (integer $file_id)
  • integer $file_id: The id of the file to delete.
phorum_db_file_get (line 4450)

Retrieve a file.

  • return: An array, containing the data for all file table fields. If the file id cannot be found in the database, an empty array will be returned instead.
array phorum_db_file_get (integer $file_id, [boolean $include_file_data = TRUE])
  • integer $file_id: The file id to retrieve from the database.
  • boolean $include_file_data: If this parameter is set to a false value (TRUE is the default), the file data will not be included in the return data.
phorum_db_file_link (line 4640)

Update the message to which a file is linked and/or the link type.

  • return: True if the file link was updated successfully. This function will always return TRUE, so we could do without a return value. The return value is here for backward compatibility.
boolean phorum_db_file_link (integer $file_id, integer $message_id, [string $link = NULL])
  • integer $file_id: The id of the file to update.
  • integer $message_id: The id of the message to link the file to.
  • string $link: A file can be linked to a number of different types of objects. See phorum_db_file_save() for the possible link types.
phorum_db_file_save (line 4531)

Add or updates a file.

  • return: The file_id that was assigned to the new file or the file_id of the existing file if the $file_id parameter was used.
  • todo: Update docs, because it now is based on separate parameters, while the function itself requires an array now.
integer phorum_db_file_save ( $file, integer $user_id, string $filename, integer $filesize, string $file_data, integer $message_id, string $link, integer $file_id)
  • integer $user_id: The id of the user for which to add the file. If this file is linked to a message by an anonymous user, then this value can be 0 (zero).
  • string $filename: The name of the file.
  • integer $filesize: The size of the file in bytes.
  • string $file_data: The file contents. This should be data which is safe to store in a TEXT field in the database. The calling application has to take care of this. The database layer will simply store and retrieve the file data as provided by the caller.
  • integer $message_id: The message_id to link the file to. If this file is not linked to a posted message (the link type PHORUM_LINK_MESSAGE) then this value can be 0 (zero).
  • string $link: A file can be linked to a number of different types of objects. The available link types are:
    • PHORUM_LINK_USER: The file is linked to a user. This means that the file is available from within the files section in the user's Control Center.
    • PHORUM_LINK_MESSAGE: The file is linked to a message. This means that the file is available as an attachment on a posted forum message.
    • PHORUM_LINK_EDITOR The file is linked to the editor. This means that the file was uploaded as part of editing a forum message. This message was not yet posted. As soon as the message is posted for final, the link type for the message will be updated to PHORUM_LINK_MESSAGE. Note: these are the official link types. Calling functions are allowed to provide different custom link types if they need to.
  • integer $file_id: If the $file_id is set, then this will be used for updating the existing file data for the given $file_id.
  • $file
phorum_db_get_banitem (line 5508)

Retrieve a single ban item from the ban lists.

  • return: A ban item array, containing the fields: pcre, string, forum_id, type. If no ban can be found for the $banid, then an empty array is returned instead.
array phorum_db_get_banitem (integer $banid)
  • integer $banid: The id of the ban item to retrieve.
phorum_db_get_banlists (line 5452)

Retrieve the ban lists for the active forum.

  • return: An array of active bans, indexed by the type of ban. For available ban types, see the documentation for the function phorum_db_mod_banlists(). Each value for a ban type is an array of bans. Each ban in those arrays is an array containing the fields: prce, string and forum_id.
array phorum_db_get_banlists ([boolean $ordered = FALSE])
  • boolean $ordered: If this parameter has a true value (default is FALSE), then the results will be ordered by ban type and string.
phorum_db_get_file_list (line 4364)

Retrieve a list of files from the database.

  • return: An array of files, indexed by file_id. The array elements are arrays containing the fields: file_id, filename, filesize and add_datetime.
array phorum_db_get_file_list ([string $link_type = NULL], [integer $user_id = NULL], [integer $message_id = NULL])
  • string $link_type: The type of link to retrieve from the database. Normally this is one of the Phorum built-in link types, but it can also be a custom link type (e.g. if a module uses the file storage on its own). This parameter can be NULL to retrieve any link type.
  • integer $user_id: The user_id to retrieve files for or NULL to retrieve files for any user_id.
  • integer $message_id: The message_id to retrieve files for or NULL to retrieve files for any message_id.
phorum_db_get_forums (line 2000)

Retrieve a list of forums. The forums which are returned can be filtered through the function parameters. Note that only one parameter is effective at a time.

  • return: An array of forums, indexed by forum_id.
array phorum_db_get_forums ([mixed $forum_ids = 0], [mixed $parent_id = NULL], [mixed $vroot = NULL], [mixed $inherit_id = NULL])
  • mixed $forum_ids: A single forum_id or an array of forum_ids for which to retrieve the forum data. If this parameter is 0 (zero), then the $parent_id parameter will be checked.
  • mixed $parent_id: Retrieve the forum data for all forums that have their parent_id set to $parent_id. If this parameter is NULL, then the $vroot parameter will be checked.
  • mixed $vroot: Retrieve the forum data for all forums that are in the given $vroot. If this parameter is NULL, then the $inherit_id parameter will be checked.
  • mixed $inherit_id: Retrieve the forum data for all forums that inherit their settings from the forum with id $inherit_id.
phorum_db_get_groups (line 2722)

Retrieve all groups or one specific group.

  • return: An array of groups, indexed by group_id.
array phorum_db_get_groups ([mixed $group_id = 0], [boolean $sorted = FALSE])
  • mixed $group_id: A single group id or an array of group ids for which to retrieve the group data. If this parameter is 0 (zero), then all groups will be returned.
  • boolean $sorted: If this parameter has a true value, then the list of groups will be sorted by the group name field.
phorum_db_get_group_members (line 2810)

Retrieve a list of members for a group or for a list of groups.

If the member list for a list of groups is requested, any member matching the specified status in any of the groups will be included in the return array. There will be no group info in the return array however, so this function cannot be used to retrieve a full group to member mapping. This specific functionality is used from the Phorum scripts to see if there are unapproved group members in any of the forums for which the active user can moderate the group members.

  • return: An array containing members for the specified group(s). The array contains a simple mapping from user_id to group permission. Note that the permission is only useful in case a single group was requested (see the function description).
array phorum_db_get_group_members (mixed $group_id, [integer $status = NULL])
  • mixed $group_id: A single group_id or an array of group_ids, for which to retrieve the members.
  • integer $status: A specific member status to look for. Defaults to all. Possible statuses are:
    • PHORUM_USER_GROUP_SUSPENDED: (temporarily) deactivated
    • PHORUM_USER_GROUP_UNAPPROVED: on hold, not yet approved
    • PHORUM_USER_GROUP_APPROVED: active in the group
    • PHORUM_USER_GROUP_MODERATOR: active + member moderator
phorum_db_get_max_messageid (line 6666)

Retrieve the maximum message_id in the database.

  • return: The maximum available message_id or 0 (zero) if no message was found at all.
integer phorum_db_get_max_messageid ()
phorum_db_get_message (line 1302)

Retrieve message(s) from the messages table by comparing value(s) for a specified field in that table.

You can provide either a single value or an array of values to search for. If a single value is provided, then the function will return the first matching message in the table. If an array of values is provided, the function will return all matching messages in an array.

  • return: Either a single message or an array of messages (indexed by message_id), depending on the $value parameter. If no message is found at all, then either an empty array or NULL is returned (also depending on the $value parameter).
mixed phorum_db_get_message (mixed $value, [string $field = 'message_id'], [boolean $ignore_forum_id = FALSE], [boolean $write_server = FALSE])
  • mixed $value: The value that you want to search on in the messages table. This can be either a single value or an array of values.
  • string $field: The message field (database column) to search on.
  • boolean $ignore_forum_id: By default, this function will only search for messages within the active forum (as defined by $PHORUM["forum_id"). By setting this parameter to a true value, the function will search in any forum.
  • boolean $write_server: This value can be set to true to specify that the message should be retrieved from the master (aka write-server) in case replication is used.
phorum_db_get_messages (line 1388)

Retrieve messages from a specific thread.

  • return: An array of messages, indexed by message_id. One special key "users" is set too. This one contains an array of all involved user_ids.
array phorum_db_get_messages (integer $thread, [integer $page = 0], [boolean $ignore_mod_perms = FALSE], [boolean $write_server = FALSE])
  • integer $thread: The id of the thread.
  • integer $page: A page offset (based on the configured read_length) starting with 1. All messages are returned in case $page is 0.
  • boolean $ignore_mod_perms: If this parameter is set to a true value, then the function will return hidden messages, even if the active Phorum user is not a moderator.
  • boolean $write_server: This value can be set to true to specify that the message should be retrieved from the master (aka write-server) in case replication is used
phorum_db_get_messagetree (line 1243)

Build a tree of all child (reply) messages below a message_id.

  • return: A string containing a comma separated list of child message_ids for the given message_id.
string phorum_db_get_messagetree (integer $message_id, integer $forum_id)
  • integer $message_id: The message_id for which to build the message tree.
  • integer $forum_id: The forum_id for the message.
phorum_db_get_message_edits (line 2476)

Retrieve a list of message-edits for a message

  • return: An array of message edits, indexed by track_id. The array elements are arrays containing the fields: user_id, time, diff_body and diff_subject.
array phorum_db_get_message_edits (integer $message_id)
  • integer $message_id: The message id for which to retrieve the edits.
phorum_db_get_message_file_list (line 4428)

Retrieve a list of files for a message (a.k.a. attachments).

  • return: An array of message files, indexed by file_id. The array elements are arrays containing the fields: file_id, filename, filesize and add_datetime.
array phorum_db_get_message_file_list (integer $message_id)
  • integer $message_id: The message id for which to retrieve the file list.
phorum_db_get_message_index (line 1502)

Retrieve the index of a message (the offset from the thread starter message) within a thread.

  • return: The index of the message, starting with 0.
integer phorum_db_get_message_index ([integer $thread = 0], [integer $message_id = 0])
  • integer $thread: The thread id.
  • integer $message_id: The message id for which to determine the index.
phorum_db_get_neighbour_thread (line 1929)

Retrieve the closest neighbour thread. What "neighbour" is, depends on the

float to top setting. If float to top is enabled, then the modifystamp is used for comparison (so the time at which the last message was posted to a thread). Otherwise, the thread id is used (so the time at which a thread was started).

  • return: The thread id for the requested neigbour thread or 0 (zero) if there is no neighbour available.
integer phorum_db_get_neighbour_thread (integer $key, string $direction)
  • integer $key: The key value of the message for which the neighbour must be returned. The key value is either the modifystamp (if float to top is enabled) or the thread id.
  • string $direction: Either "older" or "newer".
phorum_db_get_recent_messages (line 636)

Retrieve a list of recent messages for all forums for which the user has read permission, for a particular forum, for a list of forums or for a particular thread. Optionally, only top level thread messages can be retrieved.

The original version of this function came from Jim Winstead of mysql.com

  • return: An array of recent messages, indexed by message_id. One special key "users" is set too. This one contains an array of all involved user_ids.
array phorum_db_get_recent_messages (integer $length, [integer $offset = 0], [integer $forum_id = 0], [integer $thread = 0], [integer $list_type = LIST_RECENT_MESSAGES])
  • integer $length: Limit the number of returned messages to this number.
  • integer $offset: When using the $length parameter to limit the number of returned messages, this parameter can be used to specify the retrieval offset.
  • integer $forum_id: A forum_id, an array of forum_ids or 0 (zero) to retrieve messages from any forum.
  • integer $thread: A thread id or 0 (zero) to retrieve messages from any thread.
  • integer $list_type: This parameter determines the type of list that has to be returned. Options for this parameter are:
    • LIST_RECENT_MESSAGES: return a list of recent messages
    • LIST_RECENT_THREADS: return a list of recent threads
    • LIST_UPDATED_THREADS: return a list of recently updated threads
phorum_db_get_thread_list (line 472)

Retrieve a list of visible messages for a given page offset.

By default, the message body is not included in the fetch queries. To retrieve bodies as well, a true value has to be passed for the $include_bodies parameter.

NOTE: ALL dates must be returned as Unix timestamps

  • return: An array of messages, indexed by message id.
array phorum_db_get_thread_list (integer $page, [boolean $include_bodies = FALSE])
  • integer $page: The index of the page to return, starting with 0.
  • boolean $include_bodies: Whether to include the message bodies in the return data or not.
phorum_db_get_unapproved_list (line 799)

Retrieve a list of messages which have not yet been approved by a moderator.

NOTE: ALL dates must be returned as Unix timestamps

  • return: An array of messages, indexed by message id.
- phorum_db_get_unapproved_list ([$forum_id $forum_id = NULL], [$on_hold_only $on_hold_only = FALSE], [$moddays $moddays = 0], [ $countonly = FALSE])
  • $forum_id $forum_id: - The forum id to work with or NULL in case all forums have to be searched. You can also pass an array of forum ids.
  • $on_hold_only $on_hold_only: - Only take into account messages which have to be approved directly after posting. Do not include messages which were hidden by a moderator.
  • $moddays $moddays: - Limit the search to the last $moddays number of days.
  • $countonly
phorum_db_get_user_filesize_total (line 4675)

Retrieve the total size for all personal files for a user.

  • return: The total size in bytes.
integer phorum_db_get_user_filesize_total (integer $user_id)
  • integer $user_id: The user to compute the total size for.
phorum_db_get_user_file_list (line 4410)

Retrieve a list of personal files for a user.

  • return: An array of personal user files, indexed by file_id. The array elements are arrays containing the fields: file_id, filename, filesize and add_datetime.
array phorum_db_get_user_file_list (integer $user_id)
  • integer $user_id: The user id for which to retrieve the file list.
phorum_db_increment_viewcount (line 6691)

Increment the viewcount field for a post.

void phorum_db_increment_viewcount (integer $message_id, [boolean $thread_id = NULL])
  • integer $message_id: The id of the message for which to increment the viewcount.
  • boolean $thread_id: If this parameter is set to a thread_id, then the threadviewcount for that thread will be incremented as well.
phorum_db_list_stale_files (line 4711)

Retrieve a list of stale files from the database.

Stale files are files that are not linked to anything anymore.' These can for example be caused by users that are writing a message with attachments, but never post it.

  • return: An array of stale Phorum files, indexed by file_id. Every item in this array is an array on its own, containing the fields:
    • file_id: the file id of the stale file
    • filename: the name of the stale file
    • filesize: the size of the file
    • add_datetime: the time at which the file was added
    • reason: the reason why it's a stale file
array phorum_db_list_stale_files ()
phorum_db_load_settings (line 362)

Load the Phorum settings in the $PHORUM array.

These settings are key/value pairs that are read from the settings table. In the settings table, a data type is provided for each setting. The supported types are:

  • V = Value: the value of this field is used as is.
  • S = Serialized: the value of this field is a serialzed PHP variable, which will be unserialized before storing it in $PHORUM

void phorum_db_load_settings ()
phorum_db_maxpacketsize (line 7552)

This function is used by the sanity checking system in the admin interface to determine how much data can be transferred in one query.

This is used to detect problems with uploads that are larger than the database server can handle. The function returns the size in bytes. For database implementations which do not have this kind of limit, NULL can be returned.

  • return: The maximum packet size in bytes.
integer phorum_db_maxpacketsize ()
phorum_db_metaquery_compile (line 7015)

Translates a message searching meta query into a real SQL WHERE statement for this database backend. The meta query can be used to define extended SQL queries, based on a meta description of the search that has to be performed on the database.

The meta query is an array, containing:

  • query conditions
  • grouping using "(" and ")"
  • AND/OR specifications using "AND" and "OR".
The query conditions are arrays, containing the following elements:
  • condition

    A description of a condition. The syntax for this is: <field name to query> <operator> <match specification>

    The <field name to query> is a field in the message query that we are running in this function.

    The <operator> can be one of "=", "!=", "<", "<=", ">", ">=". Note that there is nothing like "LIKE" or "NOT LIKE". If a "LIKE" query has to be done, then that is setup through the <match specification> (see below).

    The <match specification> tells us with what the field should be matched. The string "QUERY" inside the specification is preserved to specify at which spot in the query the "query" element from the condition array should be inserted. If "QUERY" is not available in the specification, then a match is made on the exact value in the specification. To perform "LIKE" searches (case insensitive wildcard searches), you can use the "*" wildcard character in the specification to do so.

  • query

    The data to use in the query, in case the condition element has a <match specification> that uses "QUERY" in it.
Example:
  1.  $metaquery = array(
  2.      array(
  3.          "condition"  =>  "field1 = *QUERY*",
  4.          "query"      =>  "test data"
  5.      ),
  6.      "AND",
  7.      "(",
  8.      array("condition"  => "field2 = whatever"),
  9.      "OR",
  10.      array("condition"  => "field2 = something else"),
  11.      ")"
  12.  );

For MySQL, this would be turned into the MySQL WHERE statement:

  1.  ... WHERE field1 LIKE '%test data%'
  2.      AND (field2 = 'whatever' OR field2 = 'something else')

  • return: An array containing two elements. The first element is either TRUE or FALSE, based on the success state of the function call (FALSE means that there was an error). The second argument contains either a WHERE statement or an error message.
array phorum_db_metaquery_compile (array $metaquery)
  • array $metaquery: A meta query description array.
phorum_db_metaquery_messagesearch (line 7154)

Run a search on the messages, using a metaquery. See the documentation for the phorum_db_metaquery_compile() function for more info on the metaquery syntax.

The query that is run here, does create a view on the messages, which includes some thread and user info. This is used so these can also be taken into account when selecting messages. For the condition elements in the meta query, you can use fully qualified field names for the <field name to query>. You can use message.*, user.* and thread.* for this.

The primary goal for this function is to provide a backend for the message pruning interface.

  • return: An array of message records.
array phorum_db_metaquery_messagesearch (array $metaquery)
phorum_db_mod_banlists (line 5596)

Add or modify a single ban list item.

  • return: True if the ban item was created or updated successfully.
boolean phorum_db_mod_banlists ($type $type, boolean $pcre, string $string, integer $forum_id, string $comments, [integer $banid = 0])
  • boolean $pcre: Whether the ban string has to be handled as a standard match string or as a pcre (Perl Compatible Regular Expression).
  • string $string: The ban string for performing the match.
  • integer $forum_id: The forum_id to link the ban to. This can be a real forum_id, a vroot id or 0 (zero) to indicate a GLOBAL ban item.
  • string $comments: Comments to add to the ban item. This can be used for documenting the ban item (why was the ban created, when was this done or generally any info that an administrator finds useful).
  • integer $banid: This parameter can be set to the id of a ban item to let the function update an existing ban. If set to 0 (zero), a new ban item will be created.
  • $type $type: The type of ban list item. Available ban types are:
    • PHORUM_BAD_IPS: Match IP address or hostname.
    • PHORUM_BAD_NAMES: Mach name or username.
    • PHORUM_BAD_EMAILS: Match the email address.
    • PHORUM_BAD_USERID: Match the user_id.
    • PHORUM_BAD_SPAM_WORDS: Match for spam words.
phorum_db_move_thread (line 2180)

Move a thread to another forum.

void phorum_db_move_thread (integer $thread_id, integer $toforum)
  • integer $thread_id: The id of the thread that has to be moved.
  • integer $toforum: The id of the destination forum.
phorum_db_mysql_connect (line 217)

A wrapper function for connecting to the database.

This function should not be used from the db layer code. Instead the phorum_db_interact() function should be used in combination with the DB_RETURN_CONN return type. This function is only implemented for module writers that use this function in their code.

  • return: - A database connection resource handle.
  • deprecated:
$conn phorum_db_mysql_connect ()
phorum_db_newflag_add_read (line 5074)

Mark a message as read for the active Phorum user.

void phorum_db_newflag_add_read (mixed $message_ids)
  • mixed $message_ids: The message_id of the message to mark read in the active forum or an array description of messages to mark read. Elements in this array can be:
    • Simple message_id values, to mark messages read in the active forum.
    • An array containing two fields: "forum" containing a forum_id and "id" containing a message_id. This notation can be used to mark messages read in other forums than te active one.
phorum_db_newflag_allread (line 4744)

Mark all messages for a forum read for the active Phorum user.

void phorum_db_newflag_allread ([integer $forum_id = 0])
  • integer $forum_id: The forum to mark read or 0 (zero) to mark the current forum read.
phorum_db_newflag_check (line 4830)

Checks if there are new messages in the forums given in forum_ids

  • return: An array containing forum_ids as the key and a boolean for the values.
array phorum_db_newflag_check (array $forum_ids)
  • array $forum_ids: The forums to check for new messages
phorum_db_newflag_count (line 4890)

Gets a count of new messages and threads for the forum ids given

  • return: An array containing forum_ids as the key and a two element array for each entry with messages and threads counts.
array phorum_db_newflag_count (array $forum_ids)
  • array $forum_ids: The forums to check for new messages.
phorum_db_newflag_delete (line 5187)

Remove newflags for a forum for the active Phorum user.

void phorum_db_newflag_delete ([integer $numdelete = 0], [integer $forum_id = 0])
  • integer $numdelete: The number of newflags to delete or 0 (zero) to delete them all.
  • integer $forum_id: The forum for which to delete the newflags or 0 (zero) to delete them for the current forum.
phorum_db_newflag_get_count (line 5157)

Retrieve the total number of newflags for a forum for the active Phorum user.

  • return: The total number of newflags.
integer phorum_db_newflag_get_count ([integer $forum_id = 0])
  • integer $forum_id: The forum to retrieve the count for or 0 (zero) to retrieve it for the current forum.
phorum_db_newflag_get_flags (line 4788)

Retrieve the read messages for a forum for the active Phorum user.

  • return: An array containing the message_ids that have been read for the forum (key and value are both the message_id). Also an element for the key "min_id", which holds the minimum read message_id. All message_ids lower than the min_id are also considered to be read.
array phorum_db_newflag_get_flags ([integer $forum_id = NULL])
  • integer $forum_id: The forum to retrieve the read messages for or 0 (zero) to retrieve them for the current forum.
phorum_db_newflag_get_unread_count (line 5000)

Retrieve the number of new threads and messages for a forum for the active Phorum user.

  • return: An array containing two elements. The first element is the number of new messages. The second one is the number of new threads.
array phorum_db_newflag_get_unread_count ([integer $forum_id = NULL])
  • integer $forum_id: The forum to retrieve the new counts for or
    1. (zero) to retrieve them for the current forum.
phorum_db_newflag_update_forum (line 5218)

Update the forum_id for the newflags. The newsflags are updated by setting their forum_ids to the forum_ids of the referenced message table records.

void phorum_db_newflag_update_forum (array $message_ids)
  • array $message_ids: An array of message_ids which should be updated.
phorum_db_pm_buddy_add (line 6486)

Add a buddy for a user.

  • return: The id that was assigned to the new buddy or the existing id if the buddy already existed. If no user can be found for the $buddy_user_id parameter, then NULL will be returned.
mixed phorum_db_pm_buddy_add (integer $buddy_user_id, [mixed $user_id = NULL])
  • integer $buddy_user_id: The user_id that has to be added as a buddy.
  • mixed $user_id: The user_id the buddy has to be added for or NULL to use the active Phorum user (default).
phorum_db_pm_buddy_delete (line 6529)

Delete a buddy for a user.

void phorum_db_pm_buddy_delete (integer $buddy_user_id, [mixed $user_id = NULL])
  • integer $buddy_user_id: The user_id that has to be deleted as a buddy.
  • mixed $user_id: The user_id the buddy has to be delete for or NULL to use the active Phorum user (default).
phorum_db_pm_buddy_list (line 6566)

Retrieve a list of buddies for a user.

  • return: An array of buddies. The keys in this array are user_ids. The values are arrays, which contain the field "user_id" and possibly the boolean field "mutual" if the $find_mutual parameter was set to a true value.
array phorum_db_pm_buddy_list ([mixed $user_id = NULL], [boolean $find_mutual = FALSE])
  • mixed $user_id: The user_id for which to retrieve the buddies or NULL to user the active Phorum user (default).
  • boolean $find_mutual: Whether to find mutual buddies or not (default FALSE).
phorum_db_pm_checknew (line 6059)

Check if the user has any new private messages. This is useful in case you only want to know whether the user has new messages or not and when you are not interested in the exact amount of new messages.

  • return: TRUE in case there are new messages, FALSE otherwise.
boolean phorum_db_pm_checknew ([mixed $user_id = NULL])
  • mixed $user_id: The user to check for or NULL to use the active Phorum user (default).
phorum_db_pm_create_folder (line 5798)

Create a new private messages folder for a user.

  • return: The id that was assigned to the new folder.
integer phorum_db_pm_create_folder (string $foldername, [mixed $user_id = NULL])
  • string $foldername: The name of the folder to create.
  • mixed $user_id: The id of the user to create the folder for or NULL to use the active Phorum user (default).
phorum_db_pm_delete (line 6260)

Delete a private message from a folder.

void phorum_db_pm_delete (integer $pm_id, mixed $folder, [integer $user_id = NULL])
  • integer $pm_id: The id of the private message to delete
  • mixed $folder: The folder from which to delete the message
  • integer $user_id: The id of the user to delete the message for or NULL to use the active Phorum user (default).
phorum_db_pm_delete_folder (line 5866)

Delete a private message folder for a user. Along with the folder, all contained messages are deleted as well.

void phorum_db_pm_delete_folder (integer $folder_id, [mixed $user_id = NULL])
  • integer $folder_id: The id of the folder to delete.
  • mixed $user_id: The user to delete the folder for or NULL to use the active Phorum user (default).
phorum_db_pm_get (line 5725)

Retrieve a private message from the database.

  • return: Return the private message on success or NULL if the message could not be found.
array phorum_db_pm_get (integer $pm_id, [mixed $folder = NULL], [integer $user_id = NULL])
  • integer $pm_id: The id for the private message to retrieve.
  • mixed $folder: The folder to retrieve the message from or NULL if the folder does not matter.
  • integer $user_id: The user to retrieve the message for or NULL to use the active Phorum user (default).
phorum_db_pm_getfolders (line 5911)

Retrieve a list of private message folders for a user.

  • return: An array of private message folders, indexed by the folder id. The values are arrays, containing the fields "id" and "name". If $count is enabled, the keys "total" and "new" will be added to the forum info.
array phorum_db_pm_getfolders ([mixed $user_id = NULL], [boolean $count = FALSE])
  • mixed $user_id: The user to retrieve folders for or NULL to use the active Phorum user (default).
  • boolean $count: If this parameter is set to a true value, the number of messages for each folder is included in the return data. By default, this is not done.
phorum_db_pm_is_buddy (line 6449)

Check if a user is buddy of another user.

  • return: If the user is a buddy, then the pm_buddy_id for the buddy will be returned. If not, then NULL will be returned.
mixed phorum_db_pm_is_buddy (integer $buddy_user_id, [mixed $user_id = NULL])
  • integer $buddy_user_id: The user_id for which to check if the user is a buddy.
  • mixed $user_id: The user_id for which the buddy list must be checked or NULL to use the active Phorum user (default).
phorum_db_pm_list (line 5660)

Retrieve all private messages for a user in a folder.

  • return: An array of private messages for the folder.
array phorum_db_pm_list (mixed $folder, [integer $user_id = NULL], [boolean $reverse = TRUE])
  • mixed $folder: The folder to use. Either a special folder (PHORUM_PM_INBOX or PHORUM_PM_OUTBOX) or the id of a custom user folder.
  • integer $user_id: The user to retrieve messages for or NULL to use the active Phorum user (default).
  • boolean $reverse: If set to a true value (default), sorting of messages is done in reverse (newest first).
phorum_db_pm_messagecount (line 6010)

Compute the total number of private messages a user has and return both the total number of messages and the number of unread messages.

  • return: An array containing the elements "total" and "new".
array phorum_db_pm_messagecount (mixed $folder, [mixed $user_id = NULL])
  • mixed $folder: The id of the folder to use. Either a special folder (PHORUM_PM_INBOX or PHORUM_PM_OUTBOX), the id of a user's custom folder or PHORUM_PM_ALLFOLDERS for looking at all folders.
  • mixed $user_id: The user to retrieve messages for or NULL to use the active Phorum user (default).
phorum_db_pm_move (line 6311)

Move a private message to a different folder.

void phorum_db_pm_move (integer $pm_id, mixed $from, mixed $to, [mixed $user_id = NULL])
  • integer $pm_id: The id of the private message to move.
  • mixed $from: The folder to move the message from.
  • mixed $to: The folder to move the message to.
  • mixed $user_id: The id or the user to move the message for or NULL to use the active Phorum user (default).
phorum_db_pm_rename_folder (line 5833)

Rename a private message folder for a user.

void phorum_db_pm_rename_folder (integer $folder_id, string $newname, [mixed $user_id = NULL])
  • integer $folder_id: The id of the folder to rename.
  • string $newname: The new name for the folder.
  • mixed $user_id: The user to rename the folder for or NULL to use the active Phorum user (default).
phorum_db_pm_send (line 6103)

Send a private message.

  • return: The id that was assigned to the new message.
integer phorum_db_pm_send (string $subject, string $message, mixed $to, [mixed $from = NULL], [$keepcopy $keepcopy = FALSE])
  • string $subject: The subject for the private message.
  • string $message: The message text for the private message.
  • mixed $to: A single user_id or an array of user_ids for specifying the recipient(s).
  • mixed $from: The id of the sending user or NULL to use the active Phorum user (default).
  • $keepcopy $keepcopy: If set to a true value, a copy of the mail will be kept in the outbox of the user. Default value is FALSE.
phorum_db_pm_setflag (line 6210)

Update a flag for a private message.

void phorum_db_pm_setflag (integer $pm_id, integer $flag, boolean $value, [$user_id $user_id = NULL])
  • integer $pm_id: The id of the message to update.
  • integer $flag: The flag to update. Possible flags are: PHORUM_PM_READ_FLAG and PHORUM_PM_REPLY_FLAG.
  • boolean $value: The value for the flag (either TRUE or FALSE).
  • $user_id $user_id: The user to set a flag for or NULL to use the active Phorum user (default).
phorum_db_pm_update_message_info (line 6367)

Update the meta information for a message.

This function will update the meta information using the information from the xrefs table. If we find that no xrefs are available for the message anymore, the message will be deleted from the database.

void phorum_db_pm_update_message_info (integer $pm_id)
  • integer $pm_id: The id of the private message for which to update the meta information.
phorum_db_post_message (line 886)

Store a new message in the database.

The message will not be posted if it is a duplicate and if $PHORUM['check_duplicate'] is set.

The $message is passed by reference and in case the function completes successfully, the "message_id" index will be set to the new value. If the "thread" index is set to zero, a new thread will be started and the "thread" index will be filled with the new thread id upon return.

  • return: The message_id that was assigned to the new message.
integer phorum_db_post_message (array &$message, [boolean $convert = FALSE])
  • array &$message: The message to post. This is an array, which should contain the following fields: forum_id, thread, parent_id, author, subject, email, ip, user_id, moderator_post, status, sort, msgid, body, closed. Additionally, the following optional fields can be set: meta, modifystamp, viewcount, threadviewcount.
  • boolean $convert: True in case the message is being inserted by a database conversion script. This will let you set the datestamp and message_id of the message from the $message data. Also, the duplicate message check will be fully skipped.
phorum_db_rebuild_search_data (line 6730)

Rebuild the search table data from scratch.

void phorum_db_rebuild_search_data ()
phorum_db_rebuild_user_posts (line 6761)

Rebuild the user post counts from scratch.

void phorum_db_rebuild_user_posts ()
phorum_db_reopen_thread (line 2333)

(Re)open a thread for posting.

void phorum_db_reopen_thread (integer $thread_id)
  • integer $thread_id: The id of the thread that has to be opened.
phorum_db_run_queries (line 323)

Execute an array of queries.

  • return: NULL if all queries were executed successfully or an error message on failure.
mixed phorum_db_run_queries (array $queries)
  • array $queries: An array of SQL queries to execute.
phorum_db_sanitize_mixed (line 235)

This function will sanitize a mixed variable based on a given type for safe use in SQL queries.

void phorum_db_sanitize_mixed (mixed &$var, string $type)
  • mixed &$var: The variable to be sanitized. Passed by reference, so the original variable will be updated. It can be either a single variable or an array containing multiple variables.
  • string $type: Either "int" or "string" (the default).
phorum_db_sanitychecks (line 7582)

This function is used by the sanity checking system to let the database layer do sanity checks of its own. This function can be used by every database layer to implement specific checks.

The return value for this function should be exactly the same as the return value expected for regular sanity checking function (see include/admin/sanity_checks.php for information).

There's no need to load the sanity_check.php file for the needed constants, because this function should only be called from the sanity checking system.

  • return: A return value as expected by Phorum's sanity checking system.
array phorum_db_sanitychecks ()
phorum_db_search (line 1583)

Search the database using the provided search criteria and return an array containing the total count of matches and the visible messages based on the page $offset and $length.

  • return: An array containing two fields:
    • "count" contains the total number of matching messages.
    • "rows" contains the messages that are visible, based on the page $offset and page $length. The messages are indexed by message_id.
array phorum_db_search (string $search, mixed $author, boolean $return_threads, integer $offset, integer $length, string $match_type, integer $days, string $match_forum)
  • string $search: The query to search on in messages and subjects.
  • mixed $author: The query to search on in the message authors or a numerical user_id if searching for all messages for a certain user_id.
  • boolean $return_threads: Whether to return the results as threads (TRUE) or messages (FALSE). When searching for a user ($match_type = USER_ID), then only the thread starter messages that were posted by the user are returned.
  • integer $offset: The result page offset starting with 0.
  • integer $length: The result page length (nr. of results per page).
  • string $match_type: The type of search. This can be one of:
    • ALL: search on all of the words (uses $search)
    • ANY: search on any of the words (uses $search)
    • PHRASE: search for an exact phrase (uses $search)
    • USER_ID: search for an author id (uses $author)
  • integer $days: The number of days to go back in the database for searching (last [x] days) or zero to search within all dates.
  • string $match_forum: The forum restriction. This can be either the string "ALL" to search in any of the readable forums or a comma separated list of forum_ids.
phorum_db_sort_groups (line 2775)
void phorum_db_sort_groups ( $a,  $b)
  • $a
  • $b
phorum_db_split_thread (line 6622)

Split a thread.

void phorum_db_split_thread (integer $message_id, integer $forum_id)
  • integer $message_id: The id of the message at which to split a thread.
  • integer $forum_id: The id of the forum in which the message can be found.
phorum_db_update_forum (line 2647)

Update the settings for one or more forums.

  • return: True if all settings were stored successfully. This function will always return TRUE, so we could do without a return value. The return value is here for backward compatibility.
boolean phorum_db_update_forum (array $forum)
  • array $forum: The forum to update. This is an array, which should contain at least the field "forum_id" to indicate what forum to update. Next to that, one or more of the other fields from phorum_db_add_forum() can be used to describe changed values. The "forum_id" field can also contain an array of forum_ids. By using that, the settings can be updated for all the forum_ids at once.
phorum_db_update_forum_stats (line 2077)

Update the forums stats. This function will update the thread count, message count, sticky message count and last post timestamp for a forum.

The function can either process delta values for the stats (this is the most friendly way of updating) or fill the stats from scratch by querying the database for the correct value.

When the forum stats are updated, the cache_version for the forum will be raised by one. This will flag the cache system that cached data for the forum has to be refreshed.

void phorum_db_update_forum_stats ([boolean $refresh = FALSE], [integer $msg_count_change = 0], [integer $timestamp = 0], [integer $thread_count_change = 0], [integer $sticky_count_change = 0])
  • boolean $refresh: If TRUE, the all stats will be filled from scratch by querying the database.
  • integer $msg_count_change: Delta for the message count or zero to query the value from the database.
  • integer $timestamp: The post time of the last message or zero to query the value from the database.
  • integer $thread_count_change: Delta for the thread count or zero to query the value from the database.
  • integer $sticky_count_change: Delta for the sticky message count or zero to query the value from the database.
phorum_db_update_group (line 2922)

Update the settings for a group.

  • return: True if all settings were stored successfully. This function will always return TRUE, so we could do without a return value. The return value is here for backward compatibility.
boolean phorum_db_update_group (array $group)
  • array $group: The group to update. This is an array, which should contain at least the field "group_id" to indicate what group to update. Next to that, one or more of the following fields can be used:
    • name: The name for the group.
    • PHORUM_GROUP_CLOSED: Only the administrator can add users to this group.
    • PHORUM_GROUP_OPEN: The group is open for membership requests by users and membership is assigned on request immediately.
    • permissions: An array containing forum permissions for the group (key = forum_id and value = permission value).
phorum_db_update_message (line 1036)

Update a message in the database.

Note: an update of the full text searching database is only handled if all fields that we incorporate in full text searching (author, subject and body) are in the update fields. If one of the fields is provided, without providing the other two, then changes in the field will not reflect in the full text searching info.

void phorum_db_update_message ($message_id $message_id, $message $message)
  • $message_id $message_id: - The message_id of the message to update.
  • $message $message: - An array containing the data for the message fields that have to be updated. You can pass as many or as few message fields as you wish to update.
phorum_db_update_settings (line 401)

Store or update Phorum settings.

  • return: TRUE if all settings were stored successfully. This function will always return TRUE, so we could do without a return value. The return value is here for backward compatibility.
boolean phorum_db_update_settings (array $settings)
  • array $settings: An array containing key/value pairs that have to be stored in the settings table. Values can be either scalars or arrays. This function will automatically serialize the arrays before storing them.
phorum_db_user_add (line 3697)

Add a user.

  • return: The user_id that was assigned to the new user.
integer phorum_db_user_add (array $userdata)
  • array $userdata: An array containing the fields to insert into the user table. This array should contain at least a "username" field. See phorum_db_user_save() for some more info on the other data in this array.
phorum_db_user_check_login (line 3469)

Check if a user's authentication credentials are correct.

  • return: The user_id if the password is correct or 0 (zero) if the password is wrong.
integer phorum_db_user_check_login (string $username, string $password, [boolean $temp_password = FALSE])
  • string $username: The username for the user.
  • string $password: The password for the user.
  • boolean $temp_password: If this parameter has a true value, the password_temp field will be checked instead of the password field.
phorum_db_user_count (line 3121)

Count the total number of users in the Phorum system.

  • return: The number of users.
integer phorum_db_user_count ()
phorum_db_user_delete (line 4254)

Delete a user completely. Messages that were posted by the user in the

forums, will be changed into anonymous messages (user_id = 0). If the constant PHORUM_DELETE_CHANGE_AUTHOR is set to a true value, then the author name of all postings will be set to {LANG->AnonymousUser}. If it is set to a false value, then the original author name will be kept.

  • return: True if the user was deleted successfully.
boolean phorum_db_user_delete (integer $user_id)
  • integer $user_id: The id of the user to delete.
phorum_db_user_display_name_updates (line 3916)

Run the updates that are needed after changing the display_name for a user.

The display_name for users is stored redundant at several places in the database (this improves the speed of the system, because joins with the user table do not have to be made). This function will update that redundant information to match the active display_name field in the user data.

void phorum_db_user_display_name_updates (array $userdata)
  • array $userdata: A userdata array containing at least the fields "user_id" and "display_name".
phorum_db_user_get (line 3195)

Retrieve one or more users.

  • return: If $user_id is a single user_id, then either a single user or NULL (in case the user_id was not found in the database) is returned. If $user_id is an array of user_ids, then an array of users is returned, indexed by user_id. For user_ids that cannot be found, there will be no array element at all.
mixed phorum_db_user_get (mixed $user_id, [boolean $detailed = FALSE], [boolean $write_server = FALSE], [ $raw_data = FALSE])
  • mixed $user_id: The user_id or an array of user_ids for which to retrieve the user data.
  • boolean $detailed: If this parameter has a true value, then the user's permissions and groups are included in the return data.
  • boolean $write_server: This value can be set to true to specify that the user should be retrieved from the master (aka write-server) in case replication is used
  • $raw_data
phorum_db_user_get_all (line 3150)

Retrieve all users from the database.

This function returns a query resource handle. This handle can be used to retrieve the users from the database one-by-one, by calling the phorum_db_fetch_row() function.

  • return: A query resource handle is returned. This handle can be used to retrieve the users from the database one-by-one, by calling the phorum_db_fetch_row() function.
  • todo: This function might be as well replaced with user search and get functionality from the user API, if search is extended with an option to return a resource handle.
resource phorum_db_user_get_all ([ $offset = 0], [ $length = 0])
  • $offset
  • $length
phorum_db_user_get_fields (line 3372)

Retrieve the data for a couple of user table fields for one or more users.

  • return: An array of users (no matter what type of variable $user_id is), indexed by user_id. For user_ids that cannot be found, there will be no array element at all.
array phorum_db_user_get_fields (mixed $user_id, mixed $fields)
  • mixed $user_id: The user_id or an array of user_ids for which to retrieve the field data.
  • mixed $fields: The field or an array of fields for which to retrieve the data.
phorum_db_user_get_groups (line 4184)

Retrieve a list of group memberships and their statuses for a user.

  • return: An array of groups for the user. The keys are group_ids and the values are the membership statuses.
array phorum_db_user_get_groups (integer $user_id)
  • integer $user_id: The user id for which to retrieve the groups.
phorum_db_user_get_list (line 3426)

Retrieve a list of all users for a given type.

  • return: An array of users, indexed by user_id. The values are arrays containing the fields "user_id", "username" and "display_name".
  • todo: This function might be as well replaced with user search and get functionality from the user API,
array phorum_db_user_get_list ([integer $type = 0])
  • integer $type: The type of users to retrieve. Available options are:
    • 0 = all users
    • 1 = all active users
    • 2 = all inactive users
phorum_db_user_get_moderators (line 3044)

Retrieve a list of moderators for a particular forum.

  • return: An array of moderators. The keys are user_ids and the values are email addresses.
array phorum_db_user_get_moderators (integer $forum_id, [boolean $exclude_admin = FALSE], [boolean $for_email = FALSE])
  • integer $forum_id: The forum for which to retrieve the moderators.
  • boolean $exclude_admin: If this parameter has a true value, then the admin users are kept out of the list.
  • boolean $for_email: If this parameter has a true value, then a list of moderators is created for sending moderator mail messages. Moderators which have disabled the moderation_email option will be excluded from the list in this case.
phorum_db_user_get_subscription (line 5415)

Retrieve the subscription of a user for a thread.

  • return: The type of subscription if there is a subscription available or NULL in case no subscription was found. For a list of available subscription types see the documentation for function phorum_db_user_subscribe().
integer phorum_db_user_get_subscription (integer $user_id, integer $forum_id, integer $thread)
  • integer $user_id: The user_id to retrieve the subscription for.
  • integer $forum_id: The forum_id to retrieve the subscription for.
  • integer $thread: The thread id to retrieve the subscription for.
phorum_db_user_get_unapproved (line 4220)

Retrieve the users that await signup approval.

  • return: An array or users, indexed by user_id, that await approval. The elements of the array are arrays containing the fields: user_id, username and email.
  • todo: This function might be as well replaced with user search and get functionality from the user API.
$users phorum_db_user_get_unapproved ()
phorum_db_user_increment_posts (line 4156)

Increment the posts counter for a user.

void phorum_db_user_increment_posts (integer $user_id)
  • integer $user_id: The user_id for which to increment the posts counter.
phorum_db_user_list_subscribers (line 5262)

Retrieve the email addresses of the active users that are subscribed to a forum/thread, grouped by the preferred language for these users.

  • return: An array containing the subscriber email addresses. The keys in the result array are language names. The values are arrays. Each array contains a list of email addresses of users which are using the language from the key field.
array phorum_db_user_list_subscribers (integer $forum_id, integer $thread, integer $type, [boolean $ignore_active_user = TRUE])
  • integer $forum_id: The forum_id to check on.
  • integer $thread: The thread id to check on.
  • integer $type: The type of subscription to check on. See the documentation for the function phorum_db_user_subscribe() for available subscription types.
  • boolean $ignore_active_user: If this parameter is set to FALSE (it is TRUE by default), then the active Phorum user will be excluded from the list.
phorum_db_user_list_subscriptions (line 5334)

Retrieve a list of threads to which a user is subscribed. The list can be limited to those threads which did receive contributions recently.

  • return: An array of matching threads, indexed by thread id. One special key "forum_ids" is set too. This one contains an array of all involved forum_ids.
array phorum_db_user_list_subscriptions (integer $user_id, [integer $days = 0], [integer $forum_ids = NULL])
  • integer $user_id: The id of the user for which to retrieve the subscribed threads.
  • integer $days: If set to 0 (zero), then all subscriptions will be returned. If set to a different value, then only threads which have received contributions within the last $days days will be included in the list.
  • integer $forum_ids: If this parameter is NULL, then subscriptions from all forums will be included. This parameter can also be an array of forum_ids, in which case the search will be limited to the forums in this array.
phorum_db_user_save (line 3758)

Update a user.

  • return: True if all settings were stored successfully. This function will always return TRUE, so we could do without a return value. The return value is here for backward compatibility.
boolean phorum_db_user_save (array $userdata)
  • array $userdata: An array containing the fields to update in the user table. The array should contain at least the user_id field to identify the user for which to update the data. The array can contain two special fields:
    • forum_permissions: This field can contain an array with forum permissions for the user. The keys are forum_ids and the values are permission values.
    • user_data: This field can contain an array of key/value pairs which will be inserted in the database as custom profile fields. The keys are profile type ids (as defined by $PHORUM["PROFILE_FIELDS"]).
phorum_db_user_save_groups (line 4007)

Save the group memberships for a user.

  • return: True if all settings were stored successfully. This function will always return TRUE, so we could do without a return value. The return value is here for backward compatibility.
boolean phorum_db_user_save_groups (integer $user_id, array $groups)
  • integer $user_id: The user_id for which to save the group memberships.
  • array $groups: The group memberships to save. This is an array in which the keys are group_ids and the values are group statuses.
phorum_db_user_search (line 3547)

Search for users, based on a simple search condition, which can be used to search on any field in the user table.

The parameters $field, $value and $operator (which are used for defining the search condition) can be arrays or single values. If arrays are used, then all three parameter arrays must contain the same number of elements and the key values in the arrays must be the same.

  • return: An array of matching user_ids or a single user_id (based on the $return_array parameter) or a count of results (based on $count_only). If no user_ids can be found at all, then 0 (zero) will be returned.
mixed phorum_db_user_search (mixed $field, mixed $value, [mixed $operator = '='], [boolean $return_array = FALSE], [string $type = 'AND'], [mixed $sort = NULL], [integer $offset = 0], [integer $length = 0], [boolean $count_only = false])
  • mixed $field: The user table field (string) or fields (array) to search on.
  • mixed $value: The value (string) or values (array) to search for.
  • mixed $operator: The operator (string) or operators (array) to use. Valid operators are "=", "!=", "<>", "<", ">", ">=" and "<=", "*", "?*", "*?", "()". The "*" operator is for executing a "LIKE '%value%'" matching query. The "?*" and "*?" operators are for executing a "LIKE 'value%'" or a "LIKE '%value' matching query. The "()" operator is for executing a "IN ('value[0]',value[1]')" matching query. The "()" operator requires its $value to be an array.
  • boolean $return_array: If this parameter has a true value, then an array of all matching user_ids will be returned. Else, a single user_id will be returned.
  • string $type: The type of search to perform. This can be one of:
    • AND match against all fields
    • OR match against any of the fields
  • mixed $sort: The field (string) or fields (array) to sort the results by. For ascending sort, "fieldname" or "+fieldname" can be used. For descending sort, "-fieldname" can be used. By default, the results will be sorted by user_id.
  • integer $offset: The result page offset starting with 0.
  • integer $length: The result page length (nr. of results per page) or 0 (zero, the default) to return all results.
  • boolean $count_only: Tells the function to just return the count of results for this search query.
phorum_db_user_search_custom_profile_field (line 6842)

Search for users, based on a simple search condition, which can be used to search on custom profile fields.

The parameters $field_id, $value and $operator (which are used for defining the search condition) can be arrays or single values. If arrays are used, then all three parameter arrays must contain the same number of elements and the key values in the arrays must be the same.

  • return: An array of matching user_ids or a single user_id (based on the $return_array parameter). If no user_ids can be found at all, then 0 (zero) will be returned.
mixed phorum_db_user_search_custom_profile_field (mixed $field_id, mixed $value, [mixed $operator = '='], [boolean $return_array = FALSE], [string $type = 'AND'], [integer $offset = 0], [integer $length = 0])
  • mixed $field_id: The custom profile field id (integer) or ids (array) to search on.
  • mixed $value: The value (string) or values (array) to search for.
  • mixed $operator: The operator (string) or operators (array) to use. Valid operators are "=", "!=", "<>", "<", ">", ">=" and "<=", "*", '?*', '*?'. The "*" operator is for executing a "LIKE '%value%'" matching query. The "?*" and "*?" operators are for executing a "LIKE 'value%'" or a "LIKE '%value' matching query.
  • boolean $return_array: If this parameter has a true value, then an array of all matching user_ids will be returned. Else, a single user_id will be returned.
  • string $type: The type of search to perform. This can be one of:
    • AND match against all fields
    • OR match against any of the fields
  • integer $offset: The result page offset starting with 0.
  • integer $length: The result page length (nr. of results per page) or 0 (zero, the default) to return all results.
phorum_db_user_subscribe (line 4070)

Subscribe a user to a forum or thread.

Remark: Currently, there is no active support for subscription type PHORUM_SUBSCRIPTION_DIGEST in the Phorum core.

  • return: True if the subscription was stored successfully.
boolean phorum_db_user_subscribe (integer $user_id, integer $thread, integer $forum_id, integer $type)
  • integer $user_id: The id of the user to create the subscription for.
  • integer $thread: The id of the thread to describe to.
  • integer $forum_id: The if of the forum to subscribe to.
  • integer $type: The type of subscription. Available types are:
    • PHORUM_SUBSCRIPTION_NONE Explicitly note that the user has no subscription at all.
    • PHORUM_SUBSCRIPTION_MESSAGE Send a mail message for every new message.
    • PHORUM_SUBSCRIPTION_BOOKMARK Make new messages visible from the followed threads interface.
    • PHORUM_SUBSCRIPTION_DIGEST Periodically, send a mail message containing a list of new messages.
phorum_db_user_unsubscribe (line 4125)

Unsubscribe a user from a forum/thread.

  • return: True if the subscription was stored successfully.
boolean phorum_db_user_unsubscribe (integer $user_id, integer $thread, [integer $forum_id = 0])
  • integer $user_id: The id of the user to remove a suscription for.
  • integer $thread: The id of the thread to unsubscribe from.
  • integer $forum_id: The id of the forum to unsubscribe from (or 0 (zero) to simply unsubscribe by the thread id alone).
phorum_db_validate_field (line 266)

Check if a value that will be used as a field name in a SQL query contains only characters that would appear in a field name.

  • return: Whether the field name is valid or not (TRUE or FALSE).
boolean phorum_db_validate_field (string $field_name)
  • string $field_name: The field name to check.

Documentation generated on Sat, 11 Jan 2014 01:45:58 -0600 by phpDocumentor 1.4.3