 Hey there, and welcome to Learn WordPress. In this tutorial, you'll be learning how to leverage the WordPress user roles and capability system. After a brief introduction to the default WordPress roles and capabilities, how they are created and managed, and how to assign them to users, you will learn how to add capabilities to an existing role, and also how to create a new user role and add capabilities to it. The WordPress user roles and capabilities system is a powerful tool for managing access to your site. It allows for user roles with specific capabilities, and you can then assign those roles to users. This allows you to create a hierarchy of users, with some users having more access than others. WordPress comes with several default user roles, namely administrator, editor, author, contributor, and subscriber. There is one additional role, but this is only available in multi-site installations, and that's the super admin role. Each of these roles has a default set of capabilities, which are the things that the user can do in a WordPress site. For example, the administrator role has the capability to activate plugins, while the subscriber role does not. When a new user is created in the WordPress dashboard, they are assigned the subscriber role by default. You can change this by assigning a different role. Once assigned to that role, the user will have the capabilities that are associated with that role. You can read up on the full list of default user roles and capabilities in the official WordPress documentation. The WordPress user roles and capabilities system is stored in the database during the WordPress installation process. The roles and capabilities are stored as a serializer array, as site options in the options table, in the user roles option. The prefix for this option will depend on the table prefix configured in WPconfig, or if this is a multi-site installation. By default, on a single-site installation, this prefix will be WPunderscore, so the option will be WPunderscoreUserUnscoreRoles. If you extract the value of the user roles option and unserialize the array, you will see that the array keys are the role names, and the values are arrays of capabilities. Whenever an authenticated user is attempting to do something, this action is checked against the user's role capabilities, using the current userCAN function. If the user has the capability to perform the action, they will be allowed to do so. If they do not have the capability, they will be denied access. If you take a look at line 270 of the wp-admin slash include slash post.php file, you will see that the editPost capability is checked before a post is edited or updated. If the user does not have the editPost capability for this post, they will be informed that they do not have the required access to edit it. Let's say that you want to allow your editors to be able to do something that only admins can do, maybe install and update plugins. By default, the editor role does not have the activate plugins or update plugins capability. You can add this capability to the editor role by using the ADCAT method of the wp-roll class. However, doing so will add this capability to the user role stored in the database. So it's recommended to run this on something like plugin activation using the register activation hook function. The register activation hook requires the path to the file that contains the hook callback and the hook callback function name. You can then add the capabilities to the editor role by using the get role function to get the role object and then using the ADCAT method to add the capabilities. So what that would look like is we could say editor get role editor, so that's the role that exists in the database. And then we could say editor add cap and we want to allow the editors to activate plugins and we want to allow the editor to update plugins. Adding this code to a plugin and activating the plugin will trigger the activation hook and will update the editor role with the new plugin capabilities. So let us activate this plugin which will now add those capabilities to the editor role. Let's create a new editor user and I'll just give it some random details for now. Keep the password simple for testing purposes and make it an editor. And if we log out and log in as the editor user, we are able to install activate and update plugins. Note that because adding capabilities to a role is a permanent change, you should only do this when the plugin is activated and not on every page load. Additionally, if you want to remove a custom role, it's a good idea to do so on plugin deactivation using the register deactivation hook function. So let's look at what that could look like. So the activation deactivation hook function on callback could look like that. And then we would say get the role and then we would remove capabilities by saying remove cap and the same capability and then copy paste the update plugins capability. And there's our plugin deactivation. This is useful for two reasons. Firstly, you can add and remove capabilities when the plugin is activated and deactivated, which is useful when testing whether the capabilities you've set are what you need. Secondly, if the user deactivates your plugin, the capabilities will be removed, cleaning up any changes your plugin has made. Just as it is possible to assign existing capabilities to roles, you can also create your own custom roles and assign capabilities to them. This is useful if you want to create a role that has a specific set of capabilities and you don't want to use an existing role. For example, let's say you want to use a role which can only activate and update plugins, say an assistant to the administrator. You can create a new role using the add role function and assign the activate plugins and update plugins capabilities to it. So what that would look like in the code, let's grab the activation hook registration update the callback to custom role, let's create the function. And then we will use the add role function, which requires the role name, all lower case, a human readable string, which should be translated, but we won't worry about that now. And then an array of capabilities, which are passed in as key value pairs, the key being the capability being set and the value being true or false. So set that, then we'll set activate plugins to true. And we will set update plugins to true. Again, because the new role will be stored in the database, you should only run this code when the plugin is activated and not on every page load. Notice how the array of capabilities includes the read capability. This is because the read capability is required for a user attached to that role to be able to access the dashboard. Regardless of any other capabilities a user has, if they do not have the read capability, they will not be able to access the dashboard menu in order to perform the specific task that they should be able to. You can also include a deactivation hook to remove the role when the plugin is deactivated using the remove role function. So let's just steal the deactivation code here. I'll say remove custom role. And then we can simply say remove role and pass in the role name. Because we've made some changes to the activation and deactivation hooks, now it would be a good idea to deactivate and then reactivate the plugin for all the role functionality to be updated. So in our plugins, let's deactivate this plugin and then let's activate it. You can now create a new user with the assistant capability. Then switch users and notice how that all that user can do is manage plugins. So we're logged in as admin, so let's go to the users, create a new user, and give them the assistant capability. And then fill in all the details. Make a simple password for testing purposes and create the user. And then log out and log in as that user. And all we can really manage are the plugins. For more information on developing user roles and capabilities, see the roles and capabilities section of the plugin developer handbook at developer.wordpress.org. Happy coding!