Tutorial - Developing WordPress User Roles and Capabilities

[jonathanbossenger]

Topic Description

A primer on how to develop with the built-in WordPress Roles and Capabilities system to manage user access across a WordPress site. How to create and apply user roles, How to add/remove capabilities from a user role, How to check user capabilities

Related Resources

Links to related content on Learn, HelpHub, DevHub, GitHub Gutenberg Issues, DevNotes, etc.

• Roles and Capabilities support doc
• Roles and Capabilities developer doc

Guidelines

Review the team guidelines

Tutorial Development Checklist

• Vetted by instructional designers for content idea
• Provide feedback of the idea
• Gather links to Support and Developer Docs
• Review any related material on Learn
• Define several SEO keywords to use in the article and where they should be prominently used
• Description and Objectives finalized
• Tutorial created and announced to the team for Q/A review
• Tutorial reviewed and ready to publish
• Tutorial submitted and published to WPTV
• Tutorial published on WPTV
• Tutorial captioned
• Tutorial created on Learn.WordPress.org
• Tutorial post reviewed for grammar, spelling, etc.
• Tutorial published on Learn.WordPress.org
• Tutorial announced to Marketing Team for promotion

[jonathanbossenger]

Introduction

• User Roles introduced in WordPress 2.0
• wp-admin/includes/schema.php
• populate_roles function
• Creates roles and adds caps on install
• When creating roles, it's best to do so on plugin activation
• Role updates should happen in an upgrade step
  • calling add_role again and again has no effect
• Creating a role with add_role
  • role name
  • display name
  • array of capabilities
    • read, edit_posts, delete_posts
  • can only use existing capabilities
  • setting the read role to true allows dashboard access
  • setting the read role to false, but the edit_posts to true allows WP REST API post access.
  • there is no add_posts capability

Show an example role/capability snippet, and how it works

	add_role(
		'guest_author',
		'Guest Author',
		array(
			'read'         => true,  // true allows this capability
			'edit_posts'   => true,
			'delete_posts' => false, // Use false to explicitly deny
		)
	);

Simple code to remove role

/**
 * Create an admin page to remove the user role
 */
add_action( 'admin_menu', 'wp_learn_remove_user_role', 11 );
function wp_learn_remove_user_role() {
	add_submenu_page(
		'tools.php',
		esc_html__( 'WP Learn Reset User Role', 'wp_learn' ),
		esc_html__( 'WP Learn Reset User Role', 'wp_learn' ),
		'manage_options',
		'wp_learn_remove_user_role',
		'wp_learn_remove_user_role_callback'
	);
}

function wp_learn_remove_user_role_callback() {
	remove_role( 'guest_author' );
	add_role(
		'guest_author',
		'Guest Author',
		array(
			'read'                 => true,  // true allows this capability
			'edit_posts'           => true,
			'edit_others_posts'    => true,
			'edit_published_posts' => true,
			'delete_posts'         => true,
		)
	);
	?>
	<div class="wrap">
		<p>Guest Author role reset </p>
	</div>
	<?php
}

[jonathanbossenger]

Script: https://github.com/jonathanbossenger/wp-content/blob/main/tutorials/wordpress-roles-capabilities-01-development.md

[jonathanbossenger]

developing-roles-capabilities.mp4

Video ready for review

[jonathanbossenger]

https://learn.wordpress.org/tutorial/developing-with-user-roles-and-capabilities/