Getting started on user roles
In simple terms, user roles define the types of users in a system. WordPress offers built-in functions for working with every aspect of user roles. In this section, we are going to look at how we can manage these tasks by implementing the user roles for our application. We can create a new user role by calling the add_role function. The following code illustrates the basic form of user role creation:
$result = add_role( 'role_name', 'Display Name', array( 'read' => true, 'edit_posts' => true, 'delete_posts' => false, ) );
The first parameter takes the role name, which is a unique key to identify the role. The second parameter will be the display name, which will be shown in the admin area. The final parameter will take the necessary capabilities of the user role. In this scenario, read, edit_posts, and delete_posts will be the capabilities, while true and false are used to enable and disable status.
Creating user roles for a application
As planned earlier, we will need three types of user roles for our application to handle subscribers, developers, and members. So, we will update our plugin by adding a specific function to create the user roles as shown in the following code:
public function add_application_user_roles() {
add_role( 'follower', 'Follower', array( 'read' => true ) );
add_role( 'developer', 'Developer', array( 'read' => true ) );
add_role( 'member', 'Member', array( 'read' => true ) );
}
User roles for applications are created with the default capability of read, which is used by all user roles in WordPress. Initialization of this function should be done inside the constructor of our plugin.
What is the best action for adding user roles?
As these user roles will be saved in a database as settings, only a single call to this function is required throughout the life cycle of an application. Plugin activation is the most suitable option to call these kinds of functions for eliminating duplicate executions. So, we need to include the call to the add_application_users function inside the constructor as shown in the following code:
register_activation_hook( __FILE__ , array( $this, 'add_application_user_roles' ) );
The register_activation_hook function will be called when the plugin is activated, and hence avoids the duplicate calls to the database.
Tip
A good rule of thumb is to prevent the inclusion of such settings inside the init action as it will get executed in each request, making unnecessary performance overhead.
You might have noticed that all three user roles of the application are created with the read capability. WordPress is built for creating websites, and hence most of the default capabilities will be related to CMS features. In web applications, we need custom capabilities more often than not. Therefore, we can keep the basic read capability and add new custom capabilities as we move on. All the users will get a very basic admin area containing the dashboard and profile information as shown in the following screenshot:
Knowing the default roles
WordPress comes with six built-in user roles, including superadmin, which will not be displayed in the user creation screen by default. As a developer, it's important to know the functionality of each of these types in order to use them in web applications. First, we'll take a look at the default user roles and their functionalities:
- Superadmin: A user with this role has the administration permission in WordPress multisite implementation
- Admin: A user with this role has the permission to all administration activities inside a single site
- Editor: A user with this role can create, publish, and manage posts, including the posts of other users
- Author: A user with this role can create and publish his/her own posts
- Contributor: A user with this role can create posts but cannot publish on his/her own
- Subscriber: A user with this role can read posts and manage profiles
As you can see, most of the existing user types are used for blogging and content management functionality. Therefore, we might need to create our own user roles for web applications apart from the default superadmin and admin user roles.
How to choose between default and custom roles?
This is an interesting question which doesn't have a correct answer. Choosing between these two types of roles naturally comes with experience. First, you need to figure out how these built-in roles relate to your application. Let's consider two scenarios to help demonstrate the practical usage of these user roles.
Scenario 1
Usually, the roles such as editor, author, and contributor are mainly focused on publishing and managing blog posts. If you are developing an online shopping cart, these roles will not have any relation to the roles of such applications.
Scenario 2
Now think of a scenario where we have a job posting site with three access levels called admin, companies, and individuals. Here, individuals can create job posts, while approvals are given by the admin. So, they are similar to contributors. Similar to authors, companies can create and publish their own job posts. Admin can play the role of the editor as well in the default system.
Even though we can match certain aspects of our portfolio application roles with the existing roles, we are going to work with custom roles to keep things simple and clear. All application users will be created as custom roles with read capability by default and necessary capabilities will be added as we move on.
It doesn't matter whether you choose existing ones or new ones as long as you are comfortable and the roles have a specific meaning within your application. Since we choose custom roles, it's not necessary to keep the unused default roles. Let's see how we can remove roles when necessary.
Removing existing user roles
We should have the ability to remove existing or custom user roles when necessary. WordPress offers the remove_role function for deleting both custom and existing user roles. In this case, we want to get rid of existing user roles. Also, there can be situations where you use a plugin with specific user roles and suddenly you want to disable the functionality of the plugin. In both cases, we need to remove the user roles from the database. Let's create a function that removes unnecessary user roles from the system as described in the following code:
public function remove_application_user_roles(){
remove_role( 'author' );
remove_role( 'editor' );
remove_role( 'contributor' );
remove_role( 'subscriber' );
}
As mentioned earlier, the remove_role function involves database operations, and hence it's wise to use it with the register_activation_hook function as shown in the following code:
register_activation_hook( __FILE__, array($this, 'remove_application_user_roles') );
In this section, we looked at how user roles work in WordPress. Now we need to see how we can associate capabilities with these user roles.