User Functions
Core functions for user management, authentication, metadata, and utilities.
Source: wp-includes/user.php, wp-includes/capabilities.php, wp-includes/pluggable.php
User Retrieval
get_user()
Retrieves user by ID.
get_user( int $user_id ): WP_User|falseSince: 6.7.0
| Parameter | Type | Description |
|---|---|---|
$user_id | int | User ID |
Returns: WP_User on success, false on failure.
get_userdata()
Retrieves user by ID. Alias for get_user_by('id', $id).
get_userdata( int $user_id ): WP_User|falseSince: 0.71
get_user_by()
Retrieves user by field.
get_user_by( string $field, int|string $value ): WP_User|false| Parameter | Type | Description |
|---|---|---|
$field | string | 'id', 'ID', 'slug', 'email', 'login' |
$value | int|string | Field value |
Example:
$user = get_user_by( 'email', '[email protected]' );
$user = get_user_by( 'login', 'johndoe' );get_users()
Retrieves list of users matching criteria.
get_users( array $args = array() ): arraySee: WP_User_Query::prepare_query() for all arguments.
Example:
$editors = get_users( array(
'role' => 'editor',
'orderby' => 'display_name',
'number' => 20,
) );wp_get_current_user()
Retrieves current logged-in user.
wp_get_current_user(): WP_UserReturns: WP_User with ID 0 if not logged in.
get_current_user_id()
Gets current user’s ID.
get_current_user_id(): intReturns: User ID, or 0 if not logged in.
User Creation & Updates
wp_insert_user()
Inserts or updates a user.
wp_insert_user( array|object|WP_User $userdata ): int|WP_ErrorSince: 2.0.0
| Userdata Key | Type | Description |
|---|---|---|
ID | int | User ID (for updates) |
user_login | string | Username (required for new users) |
user_pass | string | Password (plaintext for new, hashed for existing) |
user_nicename | string | URL-friendly name |
user_url | string | User’s website |
user_email | string | Email address |
display_name | string | Display name |
nickname | string | Nickname |
first_name | string | First name |
last_name | string | Last name |
description | string | Bio |
rich_editing | string | 'true' or 'false' |
syntax_highlighting | string | 'true' or 'false' |
comment_shortcuts | string | 'true' or 'false' |
admin_color | string | Admin color scheme |
use_ssl | bool | Force SSL in admin |
user_registered | string | Registration date (Y-m-d H:i:s) |
user_activation_key | string | Password reset key |
spam | bool | Marked as spam (multisite) |
show_admin_bar_front | string | 'true' or 'false' |
role | string | User role |
locale | string | User locale |
meta_input | array | Custom meta values |
Returns: User ID on success, WP_Error on failure.
Example:
$user_id = wp_insert_user( array(
'user_login' => 'newuser',
'user_pass' => wp_generate_password(),
'user_email' => '[email protected]',
'role' => 'author',
'meta_input' => array(
'phone' => '555-1234',
),
) );wp_update_user()
Updates existing user.
wp_update_user( array|object|WP_User $userdata ): int|WP_ErrorMerges with existing data. Sends password/email change notifications.
wp_create_user()
Simple user creation with username, password, and email.
wp_create_user( string $username, string $password, string $email = '' ): int|WP_ErrorExample:
$user_id = wp_create_user( 'johndoe', 'securepass123', '[email protected]' );wp_delete_user()
Deletes a user.
wp_delete_user( int $id, int $reassign = null ): bool| Parameter | Type | Description |
|---|---|---|
$id | int | User ID to delete |
$reassign | int | User ID to reassign content to |
Authentication
wp_signon()
Authenticates and logs in a user.
wp_signon( array $credentials = array(), bool $secure_cookie = '' ): WP_User|WP_Error| Credentials Key | Type | Description |
|---|---|---|
user_login | string | Username |
user_password | string | Password |
remember | bool | Remember login |
Example:
$user = wp_signon( array(
'user_login' => $_POST['username'],
'user_password' => $_POST['password'],
'remember' => true,
) );
if ( is_wp_error( $user ) ) {
echo $user->get_error_message();
}wp_authenticate()
Authenticates a user (does not log in).
wp_authenticate( string $username, string $password ): WP_User|WP_ErrorRuns through authenticate filter chain.
wp_authenticate_username_password()
Authenticates via username and password.
wp_authenticate_username_password(
WP_User|WP_Error|null $user,
string $username,
string $password
): WP_User|WP_ErrorHooked to: authenticate filter at priority 20.
wp_authenticate_email_password()
Authenticates via email and password.
wp_authenticate_email_password(
WP_User|WP_Error|null $user,
string $email,
string $password
): WP_User|WP_ErrorSince: 4.5.0
Hooked to: authenticate filter at priority 20.
wp_authenticate_application_password()
Authenticates via application password (REST API, XML-RPC).
wp_authenticate_application_password(
WP_User|WP_Error|null $input_user,
string $username,
string $password
): WP_User|WP_Error|nullSince: 5.6.0
wp_logout()
Logs out current user and destroys session.
wp_logout(): voidis_user_logged_in()
Checks if current user is logged in.
is_user_logged_in(): boolwp_set_current_user()
Sets current user by ID or name.
wp_set_current_user( int $id, string $name = '' ): WP_UserPassword Functions
wp_set_password()
Sets user password (hashes and stores).
wp_set_password( string $password, int $user_id ): voidwp_check_password()
Checks plaintext against hashed password.
wp_check_password( string $password, string $hash, int $user_id = 0 ): boolwp_hash_password()
Hashes a password.
wp_hash_password( string $password ): stringSince 6.8.0: Uses bcrypt by default instead of phpass.
get_password_reset_key()
Creates and stores a password reset key.
get_password_reset_key( WP_User $user ): string|WP_Errorcheck_password_reset_key()
Validates a password reset key.
check_password_reset_key( string $key, string $login ): WP_User|WP_Errorreset_password()
Resets user password.
reset_password( WP_User $user, string $new_pass ): voidretrieve_password()
Sends password retrieval email.
retrieve_password( string $user_login = '' ): true|WP_ErrorUser Meta
get_user_meta()
Retrieves user meta field.
get_user_meta( int $user_id, string $key = '', bool $single = false ): mixed| Parameter | Type | Description |
|---|---|---|
$user_id | int | User ID |
$key | string | Meta key (empty for all) |
$single | bool | Return single value |
Example:
$phone = get_user_meta( $user_id, 'phone', true );
$all_meta = get_user_meta( $user_id );add_user_meta()
Adds user meta.
add_user_meta( int $user_id, string $meta_key, mixed $meta_value, bool $unique = false ): int|falseupdate_user_meta()
Updates user meta.
update_user_meta( int $user_id, string $meta_key, mixed $meta_value, mixed $prev_value = '' ): int|booldelete_user_meta()
Deletes user meta.
delete_user_meta( int $user_id, string $meta_key, mixed $meta_value = '' ): boolUser Options
get_user_option()
Gets user option (site or network scoped).
get_user_option( string $option, int $user = 0, string $deprecated = '' ): mixedChecks for {prefix}{option} first, then {option}.
update_user_option()
Updates user option.
update_user_option( int $user_id, string $option_name, mixed $newvalue, bool $is_global = false ): int|bool| Parameter | Type | Description |
|---|---|---|
$is_global | bool | false = site-specific (prefixed), true = network-wide |
delete_user_option()
Deletes user option.
delete_user_option( int $user_id, string $option_name, bool $is_global = false ): boolCapabilities
current_user_can()
Checks if current user has capability.
current_user_can( string $capability, mixed ...$args ): boolExample:
if ( current_user_can( 'edit_posts' ) ) { }
if ( current_user_can( 'edit_post', $post_id ) ) { }
if ( current_user_can( 'edit_post_meta', $post_id, $meta_key ) ) { }current_user_can_for_site()
Checks capability for specific site.
current_user_can_for_site( int $site_id, string $capability, mixed ...$args ): boolSince: 6.7.0
user_can()
Checks if specific user has capability.
user_can( int|WP_User $user, string $capability, mixed ...$args ): booluser_can_for_site()
Checks user capability for specific site.
user_can_for_site( int|WP_User $user, int $site_id, string $capability, mixed ...$args ): boolSince: 6.7.0
author_can()
Checks if post author has capability.
author_can( int|WP_Post $post, string $capability, mixed ...$args ): boolmap_meta_cap()
Maps meta capability to primitive capabilities.
map_meta_cap( string $cap, int $user_id, mixed ...$args ): string[]Example:
// edit_post for post 123 might return:
// ['edit_others_posts', 'edit_published_posts']
$caps = map_meta_cap( 'edit_post', $user_id, 123 );Roles
wp_roles()
Gets global WP_Roles instance.
wp_roles(): WP_Rolesget_role()
Gets role object by name.
get_role( string $role ): WP_Role|nulladd_role()
Adds a new role.
add_role( string $role, string $display_name, array $capabilities = array() ): WP_Role|voidExample:
add_role( 'custom_editor', 'Custom Editor', array(
'read' => true,
'edit_posts' => true,
'delete_posts' => false,
) );remove_role()
Removes a role.
remove_role( string $role ): voidSuper Admin (Multisite)
is_super_admin()
Checks if user is super admin.
is_super_admin( int|false $user_id = false ): boolget_super_admins()
Gets list of super admin logins.
get_super_admins(): string[]grant_super_admin()
Grants super admin privileges.
grant_super_admin( int $user_id ): boolrevoke_super_admin()
Revokes super admin privileges.
revoke_super_admin( int $user_id ): boolValidation & Checking
username_exists()
Checks if username exists.
username_exists( string $username ): int|falseReturns: User ID if exists, false otherwise.
email_exists()
Checks if email exists.
email_exists( string $email ): int|falseReturns: User ID if exists, false otherwise.
validate_username()
Validates username format.
validate_username( string $username ): boolSession Management
wp_get_session_token()
Gets current session token from cookie.
wp_get_session_token(): stringwp_get_all_sessions()
Gets all sessions for current user.
wp_get_all_sessions(): arraywp_destroy_current_session()
Destroys current session.
wp_destroy_current_session(): voidwp_destroy_other_sessions()
Destroys all sessions except current.
wp_destroy_other_sessions(): voidwp_destroy_all_sessions()
Destroys all sessions for current user.
wp_destroy_all_sessions(): voidCounting
count_users()
Counts users by role.
count_users( string $strategy = 'time', int|null $site_id = null ): arrayReturns:
array(
'total_users' => 150,
'avail_roles' => array(
'administrator' => 2,
'editor' => 10,
'author' => 25,
'subscriber' => 113,
'none' => 0,
),
)count_user_posts()
Counts posts by user.
count_user_posts( int $userid, array|string $post_type = 'post', bool $public_only = false ): stringcount_many_users_posts()
Counts posts for multiple users.
count_many_users_posts( int[] $users, string|string[] $post_type = 'post', bool $public_only = false ): arrayget_user_count()
Gets total active users count.
get_user_count( int|null $network_id = null ): intMultisite
get_blogs_of_user()
Gets sites a user belongs to.
get_blogs_of_user( int $user_id, bool $all = false ): object[]is_user_member_of_blog()
Checks if user is member of site.
is_user_member_of_blog( int $user_id = 0, int $blog_id = 0 ): boolwp_get_users_with_no_role()
Gets users with no role on site.
wp_get_users_with_no_role( int|null $site_id = null ): string[]Display Functions
wp_dropdown_users()
Creates user dropdown HTML.
wp_dropdown_users( array|string $args = '' ): string| Arg | Type | Default | Description |
|---|---|---|---|
show_option_all | string | '' | Text for "all" option |
show_option_none | string | '' | Text for "none" option |
orderby | string | 'display_name' | Field to order by |
order | string | 'ASC' | Sort order |
include | array|string | '' | User IDs to include |
exclude | array|string | '' | User IDs to exclude |
show | string | 'display_name' | Field to display |
echo | bool | true | Echo or return |
selected | int | 0 | Selected user ID |
name | string | 'user' | Select name attribute |
class | string | '' | Select class attribute |
role | string|array | '' | Filter by role |
wp_list_users()
Lists users as HTML.
wp_list_users( string|array $args = array() ): string|nullSince: 5.9.0
Application Passwords
wp_is_application_passwords_available()
Checks if app passwords are available.
wp_is_application_passwords_available(): boolwp_is_application_passwords_available_for_user()
Checks if app passwords are available for user.
wp_is_application_passwords_available_for_user( int|WP_User $user ): boolCache Functions
update_user_caches()
Updates all user caches.
update_user_caches( object|WP_User $user ): void|falseclean_user_cache()
Clears all user caches.
clean_user_cache( WP_User|int $user ): voidwp_cache_set_users_last_changed()
Sets last changed time for users cache.
wp_cache_set_users_last_changed(): voidUtility Functions
sanitize_user_field()
Sanitizes user field by context.
sanitize_user_field( string $field, mixed $value, int $user_id, string $context ): mixed| Context | Description |
|---|---|
'raw' | No sanitization |
'edit' | For editing (esc_attr) |
'db' | For database |
'display' | For display (default) |
'attribute' | For HTML attributes |
'js' | For JavaScript |
wp_get_user_contact_methods()
Gets registered contact methods.
wp_get_user_contact_methods( WP_User|null $user = null ): string[]wp_get_password_hint()
Gets password strength hint text.
wp_get_password_hint(): stringregister_new_user()
Registers new user and sends notification.
register_new_user( string $user_login, string $user_email ): int|WP_Errorwp_send_new_user_notifications()
Sends new user notification emails.
wp_send_new_user_notifications( int $user_id, string $notify = 'both' ): void| Notify | Description |
|---|---|
'admin' | Admin only |
'user' | User only |
'both' | Admin and user |