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.

Call time:

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.

Hook 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.

Hook output:

The same array as was used for the hook call argument, possibly with some updated fields in it.

Example code:

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;
}