Class: WP_Roles

Core class used to implement a user roles API.

The role option is simple, the structure is organized by role name that store the name in value of the 'name' key. The capabilities are stored as an array in the value of the 'capability' key.

array (
    'rolename' => array (
        'name' => 'rolename',
        'capabilities' => array()
    )
)


Properties

Name Type(s) Default Value Summary
roles array List of roles and capabilities.
role_objects array List of the role objects.
role_names array List of role names.
role_key string Option name for storing role list.
use_db boolean Whether to use the database for retrieval and storage.
site_id integer The site ID the roles are initialized for.

Methods

WP_Roles:: __call( callable $name, array $arguments )

Make private/protected methods readable for backward compatibility. Since 4.0.0.

Arguments

Name Type(s) Default Value Description
$name callable

Method to call.

$arguments array

Arguments to pass when calling.

Returns

mixed | false

Return value of the callback, false otherwise.


WP_Roles:: __construct( integer $site_id = null )

Constructor Since 2.0.0. Since 4.9.0.

Arguments

Name Type(s) Default Value Description
$site_id integer

Site ID to initialize roles for. Default is the current site.


WP_Roles:: _init( )

This method is deprecated.

Set up the object properties. Since 2.1.0.

The role key is set to the current prefix for the $wpdb object with 'user_roles' appended. If the $wp_user_roles global is set, then it will be used and the role option will not be updated or used.


WP_Roles:: add_cap( string $role, string $cap, boolean $grant = true )

Add capability to role. Since 2.0.0.

Arguments

Name Type(s) Default Value Description
$role string

Role name.

$cap string

Capability name.

$grant boolean

Optional, default is true. Whether role is capable of performing capability.


WP_Roles:: add_role( string $role, string $display_name, array $capabilities = array() )

Add role name with capabilities to list. Since 2.0.0.

Updates the list of roles, if the role doesn't already exist.

The capabilities are defined in the following format array( 'read' => true ); To explicitly deny a role a capability you set the value for that capability to false.

Arguments

Name Type(s) Default Value Description
$role string

Role name.

$display_name string

Role display name.

$capabilities array

List of role capabilities in the above format.

Returns

WP_Role | void

WP_Role object, if role is added.


WP_Roles:: for_site( integer $site_id = null )

Sets the site to operate on. Defaults to the current site. Since 4.9.0.

Arguments

Name Type(s) Default Value Description
$site_id integer

Site ID to initialize roles for. Default is the current site.


WP_Roles:: get_names( )

Retrieve list of role names. Since 2.0.0.

Returns

array

List of role names.


WP_Roles:: get_role( string $role )

Retrieve role object by name. Since 2.0.0.

Arguments

Name Type(s) Default Value Description
$role string

Role name.

Returns

WP_Role | null

WP_Role object if found, null if the role does not exist.


WP_Roles:: get_roles_data( )

Gets the available roles data. Since 4.9.0.

Returns

array

Roles array.


WP_Roles:: get_site_id( )

Gets the ID of the site for which roles are currently initialized. Since 4.9.0.

Returns

integer

Site ID.


WP_Roles:: init_roles( )

Initializes all of the available roles. Since 4.9.0.


WP_Roles:: is_role( string $role )

Whether role name is currently in the list of available roles. Since 2.0.0.

Arguments

Name Type(s) Default Value Description
$role string

Role name to look up.

Returns

boolean


WP_Roles:: reinit( )

This method is deprecated.

Reinitialize the object Since 3.5.0.

Recreates the role objects. This is typically called only by switch_to_blog() after switching wpdb to a new site ID.


WP_Roles:: remove_cap( string $role, string $cap )

Remove capability from role. Since 2.0.0.

Arguments

Name Type(s) Default Value Description
$role string

Role name.

$cap string

Capability name.


WP_Roles:: remove_role( string $role )

Remove role by name. Since 2.0.0.

Arguments

Name Type(s) Default Value Description
$role string

Role name.


WordPress Developer Newsletter

Stay on top of the latest WordPress API changes, developer tool updates, security alerts and more.