/**
* Retrieve a list of Phorum users.
*
* @param int $type
* One of:
* - {@link PHORUM_GET_ALL}: retrieve a list of all users (the default)
* - {@link PHORUM_GET_ACTIVE}: retrieve a list of all active users
* - {@link PHORUM_GET_INACTIVE}: retrieve a list of all inactive users
*
* @return array
* An array of users, indexed by user_id. Each element in the array
* is an array, containing the fields "user_id", "username" and
* "display_name".
*
* @todo Do we really need phorum_api_user_list() or could we use the
* phorum_api_user_search() functionality in combination with
* phorum_api_user_get() instead?
*/
function phorum_api_user_list($type = PHORUM_GET_ALL)
{
// Retrieve a list of users from the database.
$list = phorum_db_user_get_list($type);
/**
* [hook]
* user_list
*
* [description]
*
* This hook can be used for reformatting the list of users that
* is returned by the phorum_api_user_list() function. Reformatting
* could mean things like changing the sort order or modifying the
* fields in the user arrays.
*
* [category]
* User data handling
*
* [when]
* Each time the phorum_api_user_list() function is called. The core
* Phorum code calls the function for creating user drop down lists
* (if those are enabled in the Phorum general settings) for the
* group moderation interface in the control center and for sending
* private messages.
*
* [input]
* An array of user info arrays. Each user info array contains the
* fields "user_id", "username" and "display_name". The hook function
* is allowed to update the "username" and "display_name" fields.
*
* [output]
* The same array as was used for the hook call argument,
* possibly with some updated fields in it.
*
* [example]
* <hookcode>
* function phorum_mod_foo_user_list($users)
* {
* // Only run this hook code for authenticated users.
* if (empty($PHORUM["user"]["user_id"])) return $users;
*
* // Retrieve a list of buddies for the active user.
* // If there are no buddies, then no work is needed.
* $buddies = phorum_db_pm_buddy_list();
* if (empty($buddies)) return $users;
*
* // Flag buddies in the user list.
* $langstr = $GLOBALS["PHORUM"]["DATA"]["LANG"]["Buddy"];
* foreach ($buddies as $user_id => $info) {
* $users[$user_id]["display_name"] .= " ($langstr)";
* }
*
* return $users;
* }
* </hookcode>
*/
if (isset($GLOBALS['PHORUM']['hooks']['user_list'])) {
$list = phorum_hook('user_list', $list);
}
return $list;
}
/**
* This function gets a list of all the active users.
* @return array of users (same format as phorum_user_get)
*/
function phorum_user_get_list()
{
return phorum_hook("user_list", phorum_db_user_get_list());
}
