Class: WP_User

Core class used to implement the WP_User object.


Properties

Name Type(s) Default Value Summary
data object User data container.
ID integer The user's ID.
caps array The individual capabilities the user has been given.
cap_key string User metadata option name.
roles array The roles the user is part of.
allcaps array All capabilities the user has, including individual and role based.
filter string The filter context applied to user data fields.
site_id integer The site ID the capabilities of this user are initialized for.
back_compat_keys array Static
nickname string
description string
user_description string
first_name string
user_firstname string
last_name string
user_lastname string
user_login string
user_pass string
user_nicename string
user_email string
user_url string
user_registered string
user_activation_key string
user_status string
user_level integer
display_name string
spam string
deleted string
locale string
rich_editing string
syntax_highlighting string

Methods

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

Makes private/protected methods readable for backward compatibility. Since 4.3.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_User:: __construct( integer | string | stdClass | WP_User $id, string $name = '', integer $site_id = '' )

Constructor. Since 2.0.0.

Retrieves the userdata and passes it to WP_User::init().

Arguments

Name Type(s) Default Value Description
$id integer | string | \stdClass | WP_User

User's ID, a WP_User object, or a user object from the DB.

$name string

Optional. User's username

$site_id integer

Optional Site ID, defaults to current site.


WP_User:: __get( string $key )

Magic method for accessing custom fields. Since 3.3.0.

Arguments

Name Type(s) Default Value Description
$key string

User meta key to retrieve.

Returns

mixed

Value of the given user meta key (if set). If $key is 'id', the user ID.


WP_User:: __isset( string $key )

Magic method for checking the existence of a certain custom field. Since 3.3.0.

Arguments

Name Type(s) Default Value Description
$key string

User meta key to check if set.

Returns

boolean

Whether the given user meta key is set.


WP_User:: __set( string $key, mixed $value )

Magic method for setting custom user fields. Since 3.3.0.

This method does not update custom fields in the database. It only stores the value on the WP_User instance.

Arguments

Name Type(s) Default Value Description
$key string

User meta key.

$value mixed

User meta value.


WP_User:: __unset( string $key )

Magic method for unsetting a certain custom field. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$key string

User meta key to unset.


WP_User:: _init_caps( string $cap_key = '' )

This method is deprecated.

Set up capability object properties. Since 2.1.0.

Will set the value for the 'cap_key' property to current database table prefix, followed by 'capabilities'. Will then check to see if the property matching the 'cap_key' exists and is an array. If so, it will be used.

Arguments

Name Type(s) Default Value Description
$cap_key string

Optional capability key


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

Add capability and grant or deny access to capability. Since 2.0.0.

Arguments

Name Type(s) Default Value Description
$cap string

Capability name.

$grant boolean

Whether to grant capability to user.


WP_User:: add_role( string $role )

Add role to user. Since 2.0.0.

Updates the user's meta data option with capabilities and roles.

Arguments

Name Type(s) Default Value Description
$role string

Role name.


WP_User:: exists( )

Determine whether the user exists in the database. Since 3.4.0.

Returns

boolean

True if user exists in the database, false if not.


WP_User:: for_blog( integer $blog_id = '' )

This method is deprecated.

Set the site to operate on. Defaults to the current site. Since 3.0.0.

Arguments

Name Type(s) Default Value Description
$blog_id integer

Optional. Site ID, defaults to current site.


WP_User:: for_site( integer $site_id = '' )

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 user capabilities for. Default is the current site.


WP_User:: get( string $key )

Retrieve the value of a property or meta key. Since 3.3.0.

Retrieves from the users and usermeta table.

Arguments

Name Type(s) Default Value Description
$key string

Property

Returns

mixed


WP_User:: get_caps_data( )

Gets the available user capabilities data. Since 4.9.0.

Returns

array

User capabilities array.


WP_User:: get_data_by( string $field, string | integer $value )

Return only the main user fields Since 3.3.0. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$field string

The field to query against: 'id', 'ID', 'slug', 'email' or 'login'.

$value string | integer

The field value

Returns

object | false

Raw user object


WP_User:: get_role_caps( )

Retrieve all of the role capabilities and merge with individual capabilities. Since 2.0.0.

All of the capabilities of the roles the user belongs to are merged with the users individual roles. This also means that the user can be denied specific roles that their role might have, but the specific user isn't granted permission to.

Returns

array

List of all capabilities for the user.


WP_User:: get_site_id( )

Gets the ID of the site for which the user's capabilities are currently initialized. Since 4.9.0.

Returns

integer

Site ID.


WP_User:: has_cap( string $cap )

Whether the user has a specific capability. Since 2.0.0.

While checking against a role in place of a capability is supported in part, this practice is discouraged as it may produce unreliable results.

Arguments

Name Type(s) Default Value Description
$cap string

Capability name.

Returns

boolean

Whether the user has the given capability, or, if $object_id is passed, whether the user has the given capability for that object.


WP_User:: has_prop( string $key )

Determine whether a property or meta key is set Since 3.3.0.

Consults the users and usermeta tables.

Arguments

Name Type(s) Default Value Description
$key string

Property

Returns

boolean


WP_User:: init( object $data, integer $site_id = '' )

Sets up object properties, including capabilities. Since 3.3.0.

Arguments

Name Type(s) Default Value Description
$data object

User DB row object.

$site_id integer

Optional. The site ID to initialize for.


WP_User:: level_reduction( integer $max, string $item )

Choose the maximum level the user has. Since 2.0.0.

Will compare the level from the $item parameter against the $max parameter. If the item is incorrect, then just the $max parameter value will be returned.

Used to get the max level based on the capabilities the user has. This is also based on roles, so if the user is assigned the Administrator role then the capability 'level_10' will exist and the user will get that value.

Arguments

Name Type(s) Default Value Description
$max integer

Max level of user.

$item string

Level capability name.

Returns

integer

Max Level.


WP_User:: remove_all_caps( )

Remove all of the capabilities of the user. Since 2.1.0.


WP_User:: remove_cap( string $cap )

Remove capability from user. Since 2.0.0.

Arguments

Name Type(s) Default Value Description
$cap string

Capability name.


WP_User:: remove_role( string $role )

Remove role from user. Since 2.0.0.

Arguments

Name Type(s) Default Value Description
$role string

Role name.


WP_User:: set_role( string $role )

Set the role of the user. Since 2.0.0.

This will remove the previous roles of the user and assign the user the new one. You can set the role to an empty string and it will remove all of the roles from the user.

Arguments

Name Type(s) Default Value Description
$role string

Role name.


WP_User:: to_array( )

Return an array representation. Since 3.5.0.

Returns

array

Array representation.


WP_User:: translate_level_to_cap( integer $level )

Convert numeric level to level capability name. Since 2.0.0.

Prepends 'level_' to level number.

Arguments

Name Type(s) Default Value Description
$level integer

Level number, 1 to 10.

Returns

string


WP_User:: update_user_level_from_caps( )

Update the maximum user level for the user. Since 2.0.0.

Updates the 'user_level' user metadata (includes prefix that is the database table prefix) with the maximum user level. Gets the value from the all of the capabilities that the user has.


WordPress Developer Newsletter

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