Create Custom User Roles in WordPress

Create Custom User Roles in WordPress

Create custom user roles with specific capabilities tailored to your site's needs, from content creators to moderators.

// Add custom user role on theme activation
function add_custom_user_roles() {
    // Content Manager role
    add_role(
        'content_manager',
        __('Content Manager'),
        array(
            'read'                   => true,
            'edit_posts'             => true,
            'edit_published_posts'   => true,
            'publish_posts'          => true,
            'delete_posts'           => true,
            'delete_published_posts' => true,
            'upload_files'           => true,
            'edit_pages'             => true,
            'edit_published_pages'   => true,
            'publish_pages'          => true,
            'delete_pages'           => true,
            'delete_published_pages' => true,
            'manage_categories'      => true,
            'moderate_comments'      => true,
        )
    );

    // Shop Manager role (for WooCommerce)
    add_role(
        'shop_manager',
        __('Shop Manager'),
        array(
            'read'                      => true,
            'edit_posts'                => false,
            'edit_products'             => true,
            'edit_published_products'   => true,
            'edit_private_products'     => true,
            'edit_others_products'      => true,
            'publish_products'          => true,
            'read_product'              => true,
            'delete_products'           => true,
            'delete_published_products' => true,
            'manage_product_terms'      => true,
            'edit_product_terms'        => true,
            'delete_product_terms'      => true,
            'assign_product_terms'      => true,
            'view_woocommerce_reports'  => true,
        )
    );

    // Support Agent role
    add_role(
        'support_agent',
        __('Support Agent'),
        array(
            'read'              => true,
            'moderate_comments' => true,
            'read_private_posts' => true,
        )
    );

    // SEO Manager role
    add_role(
        'seo_manager',
        __('SEO Manager'),
        array(
            'read'                   => true,
            'edit_posts'             => true,
            'edit_published_posts'   => true,
            'edit_pages'             => true,
            'edit_published_pages'   => true,
            'manage_categories'      => true,
            'wpseo_manage_options'   => true, // Yoast SEO
        )
    );
}
add_action('after_switch_theme', 'add_custom_user_roles');

// Remove custom roles on theme deactivation
function remove_custom_user_roles() {
    remove_role('content_manager');
    remove_role('shop_manager');
    remove_role('support_agent');
    remove_role('seo_manager');
}
register_deactivation_hook(__FILE__, 'remove_custom_user_roles');

Add Capabilities to Existing Roles

// Add custom capability to editor role
function add_capabilities_to_editor() {
    $role = get_role('editor');

    if ($role) {
        $role->add_cap('edit_theme_options');
        $role->add_cap('delete_users');
        $role->add_cap('create_users');
        $role->add_cap('list_users');
        $role->add_cap('promote_users');
        $role->add_cap('remove_users');
    }
}
add_action('admin_init', 'add_capabilities_to_editor');

// Remove capability from a role
function remove_capabilities_from_author() {
    $role = get_role('author');

    if ($role) {
        $role->remove_cap('delete_published_posts');
    }
}
add_action('admin_init', 'remove_capabilities_from_author');

Check User Capabilities

// Check if current user has specific capability
if (current_user_can('edit_products')) {
    // User can edit products
    echo 'You can edit products';
}

// Check if user has role
function user_has_role($user_id, $role_name) {
    $user = get_userdata($user_id);
    return in_array($role_name, (array) $user->roles);
}

// Usage
if (user_has_role(get_current_user_id(), 'content_manager')) {
    // User is a content manager
}

Custom Capabilities

// Create custom capabilities
function add_custom_capabilities() {
    $role = get_role('administrator');

    $custom_caps = array(
        'manage_team_members',
        'view_analytics',
        'export_data',
        'manage_integrations',
    );

    foreach ($custom_caps as $cap) {
        $role->add_cap($cap);
    }
}
add_action('admin_init', 'add_custom_capabilities');

// Check custom capability
if (current_user_can('manage_team_members')) {
    // Show team management interface
}

Role Management Functions

// Get all user roles
function get_all_user_roles() {
    global $wp_roles;

    if (!isset($wp_roles)) {
        $wp_roles = new WP_Roles();
    }

    return $wp_roles->get_names();
}

// Get capabilities for a role
function get_role_capabilities($role_name) {
    $role = get_role($role_name);

    if (!$role) {
        return array();
    }

    return $role->capabilities;
}

// Clone a role
function clone_user_role($source_role, $new_role_slug, $new_role_name) {
    $role = get_role($source_role);

    if (!$role) {
        return false;
    }

    add_role($new_role_slug, $new_role_name, $role->capabilities);

    return true;
}

// Usage: Clone editor role to create "Senior Editor"
// clone_user_role('editor', 'senior_editor', 'Senior Editor');

Programmatically Change User Role

// Change user role
function change_user_role($user_id, $new_role) {
    $user = new WP_User($user_id);

    if ($user) {
        $user->set_role($new_role);
        return true;
    }

    return false;
}

// Usage
change_user_role(5, 'content_manager');

// Add additional role (don't remove existing)
function add_additional_role($user_id, $role) {
    $user = new WP_User($user_id);

    if ($user) {
        $user->add_role($role);
        return true;
    }

    return false;
}

Hide Admin Menu Items by Role

// Remove admin menu items for specific roles
function customize_admin_menu_by_role() {
    $user = wp_get_current_user();

    if (in_array('content_manager', (array) $user->roles)) {
        // Remove menu items for content managers
        remove_menu_page('tools.php');           // Tools
        remove_menu_page('options-general.php'); // Settings
        remove_menu_page('plugins.php');         // Plugins
        remove_menu_page('themes.php');          // Appearance
        remove_menu_page('users.php');           // Users
    }

    if (in_array('support_agent', (array) $user->roles)) {
        // Support agents only see comments and profile
        remove_menu_page('index.php');           // Dashboard
        remove_menu_page('edit.php');            // Posts
        remove_menu_page('upload.php');          // Media
        remove_menu_page('edit.php?post_type=page'); // Pages
    }
}
add_action('admin_menu', 'customize_admin_menu_by_role', 999);

Default Role for New Users

// Set custom default role for new user registrations
function set_default_user_role($default) {
    return 'content_manager'; // Change to your custom role
}
add_filter('pre_option_default_role', 'set_default_user_role');

Features

• Custom Roles: Create unlimited user roles
• Granular Permissions: Fine-tune capabilities
• Role Cloning: Duplicate existing roles
• Dynamic Management: Add/remove capabilities programmatically
• Access Control: Hide admin sections by role
• Flexible: Supports custom post types and plugins