Out of the box, WordPress provides a handful of user roles, from Subscriber to Administrator, each with an increasing level of access to manage content and settings on the site. While these roles provide a great starting point for many WordPress sites, they don’t offer the granularity one expects in a large organization with complex editorial workflows. Fortunately, these roles just begin to tap into the power of WordPress’s underlying capabilities API, which provides fine-grained access control for every aspect of the site’s administration, from controlling who can access a settings screen to which users can edit or publish a particular post. This session will focus on the technical aspects of role and capability management in WordPress. How do you create and edit user roles? How do you dynamically filter capabilities? What the heck is a “meta capability”? How can you have more control than the various role editing plugins provide? We’ll take a journey through the code to learn the most effective and efficient ways to manage your users’ editorial and administrative experiences, using some examples from solutions Modern Tribe has implemented at Stanford Law School and Harvard Law School.

10. WP_User::get_role_caps()
$this->allcaps = array();
foreach ( (array) $this->roles as $role ) {
$the_role = $wp_roles->get_role( $role );
$this->allcaps = array_merge( $this->allcaps, $the_role->capabilities );
}

11. populate_roles()

12. current_user_can()

13. current_user_can( 'manage_secret_settings' )
add_options_page(
'Super Secret Settings Page', // Page Title
'Secret Settings', // Menu Title
'manage_secret_settings', // Capability
'secret-settings', // Slug
[ $this, 'render' ] // Callback function
)

14. current_user_can()
return call_user_func_array( array( $current_user, 'has_cap' ), $args );

15. WP_User::has_cap()
$caps = call_user_func_array( 'map_meta_cap', $args );

16. current_user_can( 'edit_post', $post_id )
case 'edit_post':
if ( in_array( $post->post_status, [ 'publish', 'future' ], true ) ) {
$caps[] = $post_type->cap->edit_published_posts;
} elseif ( 'private' == $post->post_status ) {
$caps[] = $post_type->cap->edit_private_posts;
}

17. map_meta_cap()

18. map_meta_cap()
add_filter( 'map_meta_cap', 'add_approval_requirements', 10, 4 );
function add_approval_requirement( $required_caps, $requested_cap, $user_id, $args ) {
if ( $requested_cap == 'publish_post' ) {
if ( ! is_approved( $args[0] ) ) {
$required_caps[] = 'publish_unapproved_posts';
}
}
return $required_caps;
}

19. add_role()
$role = add_role( 'theme_switcher' );
$role->add_cap( 'read' );
$role->add_cap( 'switch_themes' );

20. add_role()
$role = add_role( 'page_author' );
$role->add_cap( 'read' );
$role->add_cap( 'edit_pages' );
$role->add_cap( 'publish_pages' );
$role->add_cap( 'delete_pages' );
$role->add_cap( 'edit_published_pages' );
$role->add_cap( 'delete_published_pages' );
$role->add_cap( 'upload_files' );
$role->add_cap( 'level_1' );

21. WP_User_Query::prepare_query()
if ( isset( $qv['who'] ) && 'authors' == $qv['who'] && $blog_id ) {
$qv['meta_key'] = $wpdb->get_blog_prefix( $blog_id ) . 'user_level';
$qv['meta_value'] = 0;
$qv['meta_compare'] = '!=';
}

22. add_action( 'admin_init', function() {
if ( get_option( 'my_user_roles_version', 0 ) < 1 ) {
my_register_roles_version_1();
update_option( 'my_user_roles_version', 1 );
}
} );

23. get_role()
$role = get_role( 'author' );
$role->add_cap( 'edit_pages' );
$role->add_cap( 'publish_pages' );
$role->add_cap( 'delete_pages' );
$role->remove_cap( 'edit_published_posts' );
$role->remove_cap( 'delete_published_posts' );

24. register_post_type( 'story' )

25. capability_type
current_user_can( 'edit_stories' )
register_post_type( 'story', [
'label' => __( 'Stories' ),
// ... many more args
'capability_type' => [ 'story', 'stories' ],
] );

26. capabilities
current_user_can( 'special_publish_posts' )
register_post_type( 'story', [
'label' => __( 'Stories' ),
// ... many more args
'capabilities' => [
'publish_posts' => 'special_publish_posts',
],
] );

27. map_meta_cap
current_user_can( 'edit_post', $story_id )
register_post_type( 'story', [
'label' => __( 'Stories' ),
// ... many more args
'capability_type' => [ 'story', 'stories' ],
'map_meta_cap' => true,
] );

28. map_meta_cap()

29. map_meta_cap
add_filter( 'map_meta_cap', 'your_mapping_method',
10, 4 )
register_post_type( 'story', [
'label' => __( 'Stories' ),
// ... many more args
'capability_type' => [ 'story', 'stories' ],
'map_meta_cap' => false,
] );

30. $caps = [
'read', 'edit_posts',
'edit_others_posts', 'edit_private_posts',
'edit_published_posts', 'publish_posts',
'read_private_posts', 'delete_posts',
'delete_private_posts', 'delete_published_posts',
'delete_others_posts', 'create_posts',
];
$pto = get_post_type_object( 'story' );
foreach ( [ 'administrator', 'editor' ] as $role_name ) {
$role = get_role( $role_name );
foreach ( $caps as $cap ) {
$role->add_cap( $pto->cap->{ $cap } );
}
}

31. // Multisite super admin has all caps by definition,
// unless specifically denied.
if ( is_multisite() && is_super_admin( $this->ID ) ) {
if ( in_array('do_not_allow', $caps) )
return false;
return true;
}

35. user_has_cap
add_filter( 'user_has_cap', 'filter_user_caps', 10, 4 );
function filter_user_caps( $caps_the_user_has, $caps_the_user_needs, $args, $user ) {
$originally_requested_cap = $args[0];
$user_id = $args[1];
$other_args = array_slice( $args, 2 ); // varies per $arg[0]
}

37. user_has_cap
foreach ( $groups as $group ) {
$access_level = $group->get_permissions( $post_type );
if (
$access_level == Group::PERMISSION_EDITOR
|| $group->is_assigned_to_post( $post_id )
) {
$user_caps[ $post_type_object->cap->edit_others_posts ] = true;
$user_caps[ $post_type_object->cap->read_private_posts ] = true;
$user_caps[ $post_type_object->cap->delete_posts ] = true;
$user_caps[ $post_type_object->cap->delete_private_posts ] = true;
$user_caps[ $post_type_object->cap->delete_published_posts ] = true;
$user_caps[ $post_type_object->cap->delete_others_posts ] = true;
$user_caps[ $post_type_object->cap->edit_private_posts ] = true;
}
}