Core system for managing users, authentication, roles, and capabilities.

Since: 2.0.0
Source: wp-includes/user.php, wp-includes/capabilities.php, wp-includes/class-wp-*.php

Components

Architecture

Database Tables

User Data Flow

wp_insert_user() / wp_create_user()
    ├── Validate & sanitize input
    ├── Apply pre_user_* filters
    ├── Insert into wp_users
    ├── Insert metadata (nickname, first_name, etc.)
    ├── Set role (wp_capabilities meta)
    └── Fire user_register action

get_userdata() / get_user_by()
    ├── Check cache
    ├── Query wp_users
    ├── Create WP_User object
    ├── Load capabilities from meta
    └── Return WP_User instance

Roles & Capabilities Model

Hierarchy

Super Admin (Multisite)
    └── Administrator
            └── Editor
                    └── Author
                            └── Contributor
                                    └── Subscriber

Default Roles

Capability Types

1. Primitive Capabilities – Stored directly in role (e.g., edit_posts, manage_options)
2. Meta Capabilities – Mapped to primitives via map_meta_cap() (e.g., edit_post → edit_others_posts)

Capability Storage

// Stored in wp_usermeta as serialized array
// Key: {prefix}capabilities
// Value: a:1:{s:10:"subscriber";b:1;}

Authentication Flow

wp_signon()
    ├── do_action('wp_authenticate')
    ├── wp_authenticate() - runs authenticate filters
    │       ├── wp_authenticate_username_password()
    │       ├── wp_authenticate_email_password()
    │       ├── wp_authenticate_application_password()
    │       └── wp_authenticate_cookie()
    ├── wp_set_auth_cookie()
    └── do_action('wp_login')

Session Tokens

• Stored in session_tokens user meta
• Managed by WP_Session_Tokens / WP_User_Meta_Session_Tokens
• Contains: expiration, IP, user agent, login time

Multisite Considerations

• Users are global across network
• Capabilities are per-site (stored with blog prefix)
• Super Admins stored in site_admins site option
• is_super_admin() checks network-level access
• switch_to_blog() / for_site() changes capability context

Key Patterns

Getting Current User

// Preferred method
$user = wp_get_current_user();
$user_id = get_current_user_id();

// Check if logged in
if ( is_user_logged_in() ) {
    // ...
}

Checking Capabilities

// Current user
if ( current_user_can( 'edit_posts' ) ) { }
if ( current_user_can( 'edit_post', $post_id ) ) { }

// Specific user
if ( user_can( $user_id, 'manage_options' ) ) { }

// On specific site (multisite)
if ( current_user_can_for_site( $site_id, 'edit_posts' ) ) { }

Querying Users

$users = get_users( array(
    'role'    => 'author',
    'orderby' => 'registered',
    'number'  => 10,
) );

// Advanced query
$query = new WP_User_Query( array(
    'role__in'     => array( 'editor', 'author' ),
    'meta_key'     => 'last_active',
    'meta_compare' => '>',
    'meta_value'   => strtotime( '-30 days' ),
) );

Cache Groups