Module 10 • Lesson 01 - How to create/modify/remove roles and capabilities

plugin-developer-learning-pathway/10-Developing-with-Roles-and-Capabilities/01-How-to-create/modify/01-How-to-create/modify/01-How-to-create-modify-remove-roles-and-capabilities.md

@@ -0,0 +1,112 @@
+## Introduction
+
+Managing user roles and capabilities in WordPress is essential for controlling access and permissions on your site. This system allows you to define what each user can and cannot do, ensuring a structured and secure environment. User roles define what actions a user can perform on your site, while capabilities are the specific permissions associated with those roles. 
+
+Understanding how to create, modify, and remove roles and capabilities is essential for managing your WordPress site effectively. This guide will walk you through the process step by step.
+
+## Understanding WordPress User Roles and Capabilities
+
+Before diving into creating or modifying roles, it’s important to understand the default user roles in WordPress:
+
+1. Administrator: Has access to all administrative features.
+2. Editor: Can manage and publish posts, including those of other users.
+3. Author: Can write, edit, and publish their own posts.
+4. Contributor: Can write and edit their own posts but cannot publish them.
+5. Subscriber: Can only manage their profile and leave comments.
+
+Each role has a set of capabilities that determine what actions the user can perform. For example, an Editor can edit_posts, publish_posts, and delete_posts, while a Subscriber can only read content.
+
+## Creating a Custom User Role
+
+If the default roles don’t meet your needs, you can create a custom role with specific capabilities. Here’s how:
+
+1. ### Use the add_role() Function:
+
+To create a new user role with specific capabilities, use the add_role function. This function should ideally be called during plugin activation to ensure it runs only once.
+
+```php
+function custom_add_role() {
+    add_role(
+        'custom_role', // Role slug
+        'Custom Role', // Display name
+        array(
+            'read' => true, // Basic capability
+            'edit_posts' => true, // Can edit posts
+            'delete_posts' => false, // Cannot delete posts
+        )
+    );
+}
+register_activation_hook( __FILE__, 'custom_add_role' );
+
+```
+This code creates a new role called "Custom Role" with the ability to read and edit posts but not delete them.
+
+2. ### Test the New Role:
+After adding the code, go to your WordPress dashboard and check the "Users" section. You should see the new role available for assignment.
+
+## Modifying an Existing Role
+
+To add or remove capabilities from an existing role, retrieve the role object using get_role and then use the add_cap or remove_cap methods.
+
+1. ### Add a Capability to a Role:
+To add a capability, use the add_cap() function.
+
+```php
+function custom_add_capability() {
+    $role = get_role('editor'); // Get the Editor role
+    $role->add_cap('manage_options'); // Add the 'manage_options' capability
+}
+add_action('init', 'custom_add_capability');
+```
+This code gives Editors the ability to manage site options, which is typically reserved for Administrators.
+
+2. ### Remove a Capability from a Role:
+To remove a capability, use the remove_cap() function.
+
+
+```php
+function custom_remove_capability() {
+    $role = get_role('editor'); // Get the Editor role
+    $role->remove_cap('publish_posts'); // Remove the 'publish_posts' capability
+}
+add_action('init', 'custom_remove_capability');
+```
+
+## Removing a Custom User Role
+
+If you need to remove a custom role, use the remove_role function. It's good to do this during plugin deactivation to clean up.
+
+```php
+function remove_custom_role() {
+    remove_role('custom_role'); // Remove the 'custom_role'
+}
+register_deactivation_hook( __FILE__, 'remove_custom_role' );
+
+```
+
+This code removes the "Custom Role" created earlier. Note that users assigned to this role will lose their permissions, so reassign them to another role before removing it.
+
+
+
+## Checking User Capabilities
+
+To check if a user has a specific capability, use the current_user_can() function:
+
+```php
+if (current_user_can('edit_posts')) {
+    echo 'You have permission to edit posts.';
+} else {
+    echo 'You do not have permission to edit posts.';
+}
+```
+
+## Best Practices
+
+- Hook into Activation/Deactivation: 
+ Add or remove roles and capabilities during plugin activation and deactivation to prevent redundant operations.
+- Check Before Modifying:
+ Always verify that the role exists before attempting to modify it to avoid errors.
+- Use Descriptive Names: 
+When creating custom roles or capabilities, use clear and descriptive names to maintain readability and manageability.
+
+For a comprehensive understanding and additional details, see the [Roles and Capabilities](https://developer.wordpress.org/plugins/users/roles-and-capabilities/) section of the Plugin developer handbook on developer.wordpress.org.