8.2.x user.module user_roles($membersonly = FALSE, $permission = NULL)
8.0.x user.module user_roles($membersonly = FALSE, $permission = NULL)
8.1.x user.module user_roles($membersonly = FALSE, $permission = NULL)
4.6.x user.module user_roles($membersonly = 0, $permission = 0)
4.7.x user.module user_roles($membersonly = 0, $permission = 0)
5.x user.module user_roles($membersonly = 0, $permission = 0)
6.x user.module user_roles($membersonly = FALSE, $permission = NULL)
7.x user.module user_roles($membersonly = FALSE, $permission = NULL)

Retrieve an array of roles matching specified conditions.


$membersonly: Set this to TRUE to exclude the 'anonymous' role.

$permission: A string containing a permission. If set, only roles containing that permission are returned.

Return value

An associative array with the role id as the key and the role name as value.

14 calls to user_roles()
blogapi_admin_settings in modules/blogapi/blogapi.module
blogapi_metaweblog_new_media_object in modules/blogapi/blogapi.module
Blogging API callback. Inserts a file into Drupal.
filter_admin_format_form in modules/filter/filter.admin.inc
Generate a filter format form.
filter_admin_format_form_submit in modules/filter/filter.admin.inc
Process filter format form submissions.
filter_admin_overview in modules/filter/filter.admin.inc
Menu callback; Displays a list of all input formats and which one is the default.

... See full list


modules/user/user.module, line 1794
Enables the user registration and login system.


function user_roles($membersonly = FALSE, $permission = NULL) {
  // System roles take the first two positions.
  $roles = array(

  if (!empty($permission)) {
    $result = db_query("SELECT r.* FROM {role} r INNER JOIN {permission} p ON r.rid = p.rid WHERE p.perm LIKE '%%%s%%' ORDER BY r.name", $permission);
  else {
    $result = db_query('SELECT * FROM {role} ORDER BY name');

  while ($role = db_fetch_object($result)) {
    switch ($role->rid) {
      // We only translate the built in role names
        if (!$membersonly) {
          $roles[$role->rid] = t($role->name);
        $roles[$role->rid] = t($role->name);
        $roles[$role->rid] = $role->name;

  // Filter to remove unmatched system roles.
  return array_filter($roles);


jdonson’s picture

I am unclear as to why this is not sorted by rid, which would support hierarchies
being crystal clear on the admin/user/roles and admin/user/permissions pages.

*How does alphabetizing role names help us?*

I suggest:

if (!empty($permission)) {
$result = db_query("SELECT r.* FROM {role} r INNER JOIN {permission} p
ON r.rid = p.rid WHERE p.perm LIKE '%%%s%%' ORDER BY
r.rid", $permission);
else {
$result = db_query('SELECT * FROM {role} ORDER BY




Gaelan’s picture

you should file an issue. No one will notice your message here.

Actually, why don't we just add a weight? The RID is a little static…you can't change the order once you've set it with the RID.

bartl’s picture

      // We only translate the built in role names

Why is that? Otherwise you would have a change to show non-English speaking users a more comprehensible name.

So I hacked this function in my copy of Drupal, to translate all role names.

mikey_p’s picture

That is because the base translation system isn't designed for dynamic content, only static. In other words the system built into core (provided by the t() function is only designed to localize the interface of Drupal, not the translation of user generated content (which is what additional roles are.

See the documentation for t() at http://api.drupal.org/api/drupal/includes%21common.inc/function/t/6, especially this section:

Because t() is designed for handling code-based strings, in almost all cases, the actual string and not a variable must be passed through t().

Extraction of translations is done based on the strings contained in t() calls. If a variable is passed through t(), the content of the variable cannot be extracted from the file for translation.

And this is the exception that allows the usage in user_roles:

The only case in which variables can be passed safely through t() is when code-based versions of the same strings will be passed through t() (or otherwise extracted) elsewhere.