/**
* Retrieve the data for forums and/or folders in various ways. Note that
* only one of the parameters $forum_ids, $parent_id, $vroot and $inherit_id
* will be effective at a time. The parameter $only_inherit_masters can be
* used in conjunction with all of these.
*
* @param mixed $forum_ids
* A single forum_id or an array of forum_ids for which to retrieve the
* forum data. If this parameter is NULL, then the $parent_id
* parameter will be checked.
*
* @param 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.
*
* @param mixed $inherit_id
* Retrieve the forum data for all forums that inherit their settings
* from the forum with id $inherit_id.
*
* @param mixed $vroot
* Retrieve the forum data for all forums that are in the given $vroot.
* If this parameter is NULL, then forums from any vroot will be
* returned. This parameter can be used in combination with
* the $forum_ids, $parent_id and $inherit_id parameters.
*
* @param integer $flags
* If the {@link PHORUM_FLAG_INHERIT_MASTERS} flag is set, then
* only forums that can act as a settings inheritance master will be
* returned (these are the forums that do not inherit their settings
* from either the default settings or from another forum).
* If the {@link PHORUM_FLAG_FOLDERS} flag is set, then only
* folders will be returned.
* If the {@link PHORUM_FLAG_FORUMS} flag is set, then only
* forums will be returned.
* If the {@link PHORUM_FLAG_INCLUDE_INACTIVE} flag is set, then
* inactive forums and folders will be included in the return data.
* This is mainly useful for administrative interfaces that need to
* be able to access all created forums and folders.
*
* @return mixed
* If the $forum_ids parameter is used and if it contains a single
* forum_id, then a single array containing forum data is returned or
* NULL if the forum was not found.
* For all other cases, an array of forum data arrays is returned, indexed
* by the forum_id and sorted by their display order. If the $forum_ids
* parameter is an array containing non-existent forum_ids, then the
* return array will have no entry available in the returned array for
* those forum_ids.
*/
function phorum_api_forums_get($forum_ids = NULL, $parent_id = NULL, $inherit_id = NULL, $vroot = NULL, $flags = 0)
{
global $PHORUM;
// We might get an $inherit_id parameter that is NULL or -1, since we
// present the database value NULL as -1 from this API (because using
// NULL values in a form isn't really an option.
$inherit_id = $inherit_id != -1 && $inherit_id !== NULL ? (int) $inherit_id : NULL;
// Find the return_type parameter for the db call.
// 0 = forums and folders, 1 = folders, 2 = forums.
if ($flags & PHORUM_FLAG_FOLDERS) {
$return_type = $flags & PHORUM_FLAG_FORUMS ? 0 : 1;
} elseif ($flags & PHORUM_FLAG_FORUMS) {
$return_type = 2;
} else {
$return_type = 0;
}
// Retrieve the forums/folders from the database.
$forums = $PHORUM['DB']->get_forums($forum_ids, $parent_id, $vroot, $inherit_id, $flags & PHORUM_FLAG_INHERIT_MASTERS, $return_type, $flags & PHORUM_FLAG_INCLUDE_INACTIVE);
// Process the returned records.
foreach ($forums as $id => $forum) {
$forums[$id]['folder_flag'] = $forum['folder_flag'] ? 1 : 0;
$forums[$id]['forum_path'] = unserialize($forum['forum_path']);
// This is a special one. The database value is NULL or
// a positive integer, but NULL is not an easy value to
// use in HTML forms. Therefore, we provide the value
// -1 to indicate a NULL value here.
$forums[$id]['inherit_id'] = $forum['inherit_id'] === NULL ? -1 : (int) $forum['inherit_id'];
}
// retrieve and apply the custom fields for forums
if (!empty($PHORUM['CUSTOM_FIELDS'][PHORUM_CUSTOM_FIELD_FORUM])) {
$forums = phorum_api_custom_field_apply(PHORUM_CUSTOM_FIELD_FORUM, $forums);
}
// If forum_id 0 (zero) is requested, then we create a fake folder
// record. This is the root folder, which does not correspond to an
// actual record in the database.
if ($forum_ids !== NULL) {
if (is_array($forum_ids) && in_array(0, $forum_ids) || !is_array($forum_ids) && $forum_ids !== NULL && $forum_ids == 0) {
$template = $PHORUM['default_forum_options']['template'];
$language = $PHORUM['default_forum_options']['language'];
$forums[0] = array('forum_id' => 0, 'folder_flag' => 1, 'vroot' => 0, 'parent_id' => NULL, 'inherit_id' => 0, 'active' => 1, 'name' => $PHORUM['title'], 'description' => $PHORUM['description'], 'forum_path' => array(0 => $PHORUM['title']), 'template' => $template, 'language' => $language, 'cache_version' => 0, 'reg_perms' => 0, 'pub_perms' => 0);
}
}
if ($forum_ids === NULL || is_array($forum_ids)) {
return $forums;
} else {
return isset($forums[$forum_ids]) ? $forums[$forum_ids] : NULL;
}
}
/**
* Retrieve data for Phorum users.
*
* @param mixed $user_id
* Either a single user_id or an array of user_ids.
*
* @param boolean $detailed
* If this parameter is TRUE (default is FALSE), then the user's
* groups and permissions are included in the user data.
*
* @param boolean $use_write_server
* This parameter is for internal use only. It is used to flag that
* the database layer has to run the query against the master database
* server (known as the "write server"; only applicable if the database
* system is setup as a replicated master/slave environment). When you
* are using this API call in your own code, then you most probably do
* not need to use this parameter.
*
* @param boolean $raw_data
* This parameter is for internal use only.
* When this parameter is TRUE (default is FALSE), then custom fields
* that are configured with html_disabled will not be HTML encoded in
* the return data.
*
* @return mixed
* If the $user_id parameter is a single user_id, then either an array
* containing user data is returned or NULL if the user was not found.
* If the $user_id parameter is an array of user_ids, then an array
* of user data arrays is returned, indexed by the user_id.
* Users for user_ids that are not found are not included in the
* returned array.
*/
function phorum_api_user_get($user_id, $detailed = FALSE, $use_write_server = FALSE, $raw_data = FALSE)
{
global $PHORUM;
if (!is_array($user_id)) {
$user_ids = array($user_id);
} else {
$user_ids = $user_id;
}
// Prepare the return data array. For each requested user_id,
// a slot is prepared in this array. Also, turn the user id array
// into an array that has the user_id as both the key and value.
$users = array();
$new_user_ids = array();
foreach ($user_ids as $id) {
$users[$id] = NULL;
$new_user_ids[$id] = $id;
}
$user_ids = $new_user_ids;
// First, try to retrieve user data from the user cache,
// if user caching is enabled.
if (!empty($PHORUM['cache_users'])) {
$cached_users = phorum_api_cache_get('user', $user_ids);
if (is_array($cached_users)) {
foreach ($cached_users as $id => $user) {
$users[$user['user_id']] = $user;
unset($user_ids[$id]);
}
// We need to retrieve the data for some dynamic fields
// from the database.
$dynamic_data = $PHORUM['DB']->user_get_fields(array_keys($cached_users), array('date_last_active', 'last_active_forum', 'posts'));
// Store the results in the users array.
foreach ($dynamic_data as $d_user_id => $data) {
$users[$d_user_id] = array_merge($users[$d_user_id], $data);
}
}
}
// Retrieve user data for the users for which no data was
// retrieved from the cache.
if (count($user_ids)) {
$db_users = $PHORUM['DB']->user_get($user_ids, $detailed, $use_write_server);
// Retrieve and apply the custom fields for users.
if (!empty($PHORUM['CUSTOM_FIELDS'][PHORUM_CUSTOM_FIELD_USER])) {
$db_users = phorum_api_custom_field_apply(PHORUM_CUSTOM_FIELD_USER, $db_users, $raw_data);
}
foreach ($db_users as $id => $user) {
// Merge the group and forum permissions into a final
// permission value per forum. Forum permissions that are
// assigned to a user directly override any group based
// permission.
if (!$user['admin']) {
if (!empty($user['group_permissions'])) {
foreach ($user['group_permissions'] as $fid => $perm) {
if (!isset($user['permissions'][$fid])) {
$user['permissions'][$fid] = $perm;
} else {
$user['permissions'][$fid] |= $perm;
}
}
}
if (!empty($user['forum_permissions'])) {
foreach ($user['forum_permissions'] as $fid => $perm) {
$user['permissions'][$fid] = $perm;
}
}
}
// If detailed information was requested, we store the data in
// the cache. For non-detailed information, we do not cache the
// data, because there is not much to gain there by caching.
if ($detailed && !empty($PHORUM['cache_users'])) {
phorum_api_cache_put('user', $id, $user);
}
// Store the results in the users array.
$users[$id] = $user;
}
}
// Remove the users for which we did not find data from the array.
foreach ($users as $id => $user) {
if ($user === NULL) {
unset($users[$id]);
}
}
/**
* [hook]
* user_get
*
* [description]
* This hook can be used to handle the data that was retrieved
* from the database for a user. Modules can add and modify the
* user data.<sbr/>
* <sbr/>
* In combination with the <hook>user_save</hook> hook, this hook
* could also be used to store and retrieve some of the Phorum
* user fields in some external system
*
* [category]
* User data handling
*
* [when]
* Just after user data has been retrieved from the database.
*
* [input]
* This hook receives two arguments.<sbr/>
* The first argument contains an array of users.
* Each item in this array is an array containing data for
* a single user, which can be updated.<sbr/>
* The second argument contains a boolean that indicates whether
* detailed information (i.e. including group info) is retrieved.
*
* [output]
* The array that was used as the first argument for the hook call,
* possibly with some updated users in it.
*
* [example]
* <hookcode>
* function phorum_mod_foo_user_get($user, $detailed)
* {
* // Let's asume that our usernames are based on the
* // system users on a UNIX system. We could merge some
* // info from the password file with the Phorum info here.
*
* // First try to lookup the password file entry.
* // Return if this lookup fails.
* $pw = posix_getpwnam($user['username']);
* if (empty($pw)) return $user;
*
* // On a lot of systems, the "gecos" field contains
* // the real name for the user.
* $user['real_name'] = $pw["gecos"] != ''
* ? $pw["gecos"]
* : $user["real_name"];
*
* // If a custom profile field "shell" was created, then
* // we could also put the user's shell in the data.
* $user['shell'] = $pw['shell'];
*
* return $user;
* }
* </hookcode>
*/
if (isset($PHORUM['hooks']['user_get'])) {
$users = phorum_api_hook('user_get', $users, $detailed);
}
// A backward compatibility hook. The advised hook for modifying
// loaded user data is "user_get" from above.
if (isset($PHORUM["hooks"]["read_user_info"])) {
$users = phorum_api_hook("read_user_info", $users);
}
// Return the results.
if (is_array($user_id)) {
return $users;
} else {
return isset($users[$user_id]) ? $users[$user_id] : NULL;
}
}
