In WordPress development, controlling what a user can see or do based on their assigned role is a fundamental requirement. Whether you are building a membership site, a multi-author blog, or a custom dashboard, you often need to verify if the current user is an "Author," an "Editor," or a custom role you've created.

While WordPress provides several built-in functions for permission management, choosing the right method depends on whether you are checking the current logged-in user or a specific user by their ID. In this guide, we will explore the most reliable ways to check user roles, including the caveats of the standard API and how to build your own helper functions for cleaner code.

Using current_user_can() for Role Checks

The most common way to check permissions in WordPress is the current_user_can() function. Historically, this function has accepted both capabilities (like edit_posts) and role names (like administrator).

if ( current_user_can( 'administrator' ) ) {
    // The user is an administrator
    echo "Welcome, Admin!";
}

However, there is a significant technical caveat you should be aware of. According to official WordPress core discussions (see Trac ticket #22624), passing a role name to current_user_can() is not always guaranteed to work correctly in all configurations, especially in complex multisite environments or when roles have been heavily customized.

The "WordPress Way" generally recommends checking for capabilities rather than roles. For example, instead of checking if someone is an "author," you would check if they can publish_posts. But if your logic specifically depends on the role name itself—such as changing a UI label specifically for authors—you should use the methods below.

The Reliable Method: Checking the Roles Array

Every WordPress user object contains a roles property, which is an array of all roles assigned to that user. Since a user can technically have multiple roles, checking this array is the most precise way to verify a specific role membership.

To check the current user, you can use wp_get_current_user() to retrieve the user object and then use in_array() to look for the role.

$user = wp_get_current_user();

if ( in_array( 'author', (array) $user->roles ) ) {
    // The user has the "author" role
    echo "Custom label for Authors";
}

In this snippet, we cast $user->roles to an array to prevent errors if the property is empty or null. This approach bypasses the logic of current_user_can() and looks directly at the database-stored roles for that account.

How to Check Roles by User ID

There are many scenarios where you need to check the role of a user who is not the one currently logged in. For instance, you might be looping through a list of users in the admin panel or processing a background job.

You can create a reusable helper function to handle this by fetching user data by ID:

/**
 * Check if a specific user has a specific role.
 * 
 * @param int    $user_id The ID of the user to check.
 * @param string $role    The role name (e.g., 'editor').
 * @return bool
 */
function is_user_in_role( $user_id, $role ) {
    $user = get_userdata( $user_id );

    if ( ! $user ) {
        return false;
    }

    return in_array( $role, (array) $user->roles );
}

// Usage example
if ( is_user_in_role( 123, 'contributor' ) ) {
    // User 123 is a contributor
}

Alternatively, you can instantiate the WP_User class directly. This is particularly useful if you want to perform multiple checks on the same user object without repeatedly calling get_userdata().

$user = new WP_User( $user_id );

if ( ! empty( $user->roles ) && is_array( $user->roles ) && in_array( 'subscriber', $user->roles ) ) {
    // Logic for subscribers
}

Advanced Approach: Using get_role_caps()

If you are working on a complex plugin where roles and capabilities are frequently modified, you might find that simple array checking isn't enough. The WP_User object provides a method called get_role_caps() which fetches all roles and capabilities assigned to the user, ensuring that WordPress has fully processed the user's permission map.

/**
 * Returns true if a user_id has a given role or capability using mapped caps
 * 
 * @param int $user_id
 * @param string $role_or_cap Role or Capability
 * @return boolean
 */
function my_has_role( $user_id, $role_or_cap ) {
    $u = new \WP_User( $user_id );
    $roles_and_caps = $u->get_role_caps(); 

    if ( isset( $roles_and_caps[$role_or_cap] ) && $roles_and_caps[$role_or_cap] === true ) {
        return true;
    }

    return false;
}

This method is highly robust because it accounts for the internal way WordPress stores the relationship between roles and their underlying capabilities.

WooCommerce Specific Role Checking

If you are developing for a store powered by WooCommerce, the platform provides its own helper functions to simplify this process. WooCommerce often handles custom roles like "Customer" or "Shop Manager," and using their native functions ensures compatibility with their specific session handling.

To check the current user's role in WooCommerce:

if ( wc_current_user_has_role( 'customer' ) ) {
    // Logic for customers
}

If you want to replicate the clean logic WooCommerce uses for your own non-WooCommerce site, you can use a pattern like this:

function mysite_current_user_has_role( $role ) {
    $user = wp_get_current_user();

    if ( ! is_object( $user ) || ! $user->exists() ) {
        return false;
    }

    return in_array( $role, (array) $user->roles, true );
}

Frequently Asked Questions

Can a user have more than one role in WordPress?

Yes. While the default WordPress admin interface only allows you to select one role for a user, the underlying architecture supports multiple roles. This is why $user->roles is an array. If you use plugins like User Role Editor, users can easily be assigned multiple roles simultaneously.

Why should I check for capabilities instead of roles?

Checking for capabilities (e.g., current_user_can('edit_posts')) is more flexible. If you later decide that "Contributors" should also be able to edit posts, you only need to change the role's permissions, not your code. If you hardcode a check for the "Author" role, your code remains locked to that specific role name.

How do I check if a user is logged in before checking their role?

It is best practice to wrap your role checks in an is_user_logged_in() check to avoid unnecessary processing or potential errors when dealing with guest visitors.

if ( is_user_logged_in() ) {
    $user = wp_get_current_user();
    if ( in_array( 'editor', (array) $user->roles ) ) {
        // User is logged in and is an editor
    }
}

Wrapping Up

Checking user roles in WordPress is a straightforward task once you understand the relationship between the WP_User object and the roles array. While current_user_can() is the standard for capability checks, direct array inspection via wp_get_current_user() or get_userdata() provides the most reliable results when you need to target specific role names.

Key Takeaways:

  • Use current_user_can() for capability-based permissions.
  • Use in_array( 'role_name', $user->roles ) for explicit role-based logic.
  • Always cast $user->roles to an array to ensure compatibility.
  • Use get_userdata( $user_id ) when checking roles for users other than the current visitor.
  • Consider WooCommerce's wc_current_user_has_role() if you are working within an e-commerce context.