In developing complex WordPress plugins, customizing the admin dashboard, or taking over enterprise-level CMS platforms, one “mountain” that cannot be bypassed is “Roles and Capabilities.”
Not only beginners, but many developers with years of experience can trip up over permission management—such as haphazardly adding permissions on the init hook, incorrectly using role names instead of capability names to check permissions, or even dragging down website performance by installing bloated permission management plugins for convenience.
This article will take you from the underlying logic to thoroughly understand WordPress’s role and permission mechanism. Not only does it include detailed code examples, but we will also connect pieces of practical pitfall-avoidance guides accumulated by this site over the years.
I. Core Concept: What are Roles and Capabilities?
To understand the WordPress permission system, you must first clarify the relationship between these two core concepts:
- Capability: The most basic unit of access control in WordPress. It represents whether a user “can do a specific thing.” For example:
edit_posts(can edit posts),delete_users(can delete users),activate_plugins(can activate plugins). - Role: A role is essentially just a named collection (container) of permissions. You can think of it as a “permission pack” containing multiple capabilities.
💡 Core Essence: WordPress uses Capability-Based Access Control (CBAC), not pure Role-Based Access Control (RBAC). When the system determines whether an operation can be executed, the underlying logic is always to ask “Do you have
xxx_capability?”, not “Are youxxx_role?”.
II. WordPress’s Five Default Basic Roles
After installing WordPress, the system provides 5 basic role hierarchy levels by default (6 in multisite mode):
| Role Name | Common Permission Range | Applicable Scenario |
|---|---|---|
| Administrator | Has all capabilities under a single site. | Site owners, top-level maintenance personnel. |
| Editor | Can publish and manage their own and others’ posts. | Content editors-in-chief, no need to touch site settings. |
| Author | Can publish and manage their own posts. | On-site writers, content creators. |
| Contributor | Can write and manage their own posts but cannot publish directly. | External contributors, need editor review before publishing. |
| Subscriber | Can only manage their own personal profile. | Regular registered users, members. |
| Super Admin | (Multisite only) Manages the entire network, has absolute control. | Network group administrators. |
For a personal blog, this system is more than enough; but in complex CMS or enterprise applications, we need to start modifying them.
III. Core Development Practice: Playing with Roles and Permissions with Pure Code
Now that we understand the concepts, how do we operate them in code? WordPress provides four “god-level” functions: add_role(), remove_role(), add_cap(), remove_cap().
1. Where Do Permissions Exist? (Must-see for Beginners to Avoid Pitfalls)
Before writing code, a fatal misunderstanding must be cleared: WordPress’s role and permission information is persistently stored in the database (the wp_user_roles field of the wp_options table).
👉 Best Practice Warning: As long as you add or delete permissions for a role through code, this change will be permanently solidified. Therefore, you should not repeatedly execute permission modification code every time a page loads (such as hooking to the init hook)! For a more correct and lightweight approach, you can refer to our tutorial:
🔗 Extended Reading: “Modifying WordPress Role Permissions Without Plugins”
2. How to Create a Brand New Role?
Instead of drastically modifying default roles, a safer and more common approach is: Create a new derived role based on an existing role. For example, we need a “Senior Author” role who, in addition to having author permissions, can also upload specific types of files.
We usually get all permissions of an existing role first, then assign them to the new role. See this practical code for specific steps:
🔗 Practical Code: “Creating a New User Role Based on an Existing WordPress Role and Modifying the New Role’s Permissions”
3. Customize the Display Name of the Default Role
If you don’t want to create a new role, but just think “Administrator” doesn’t sound cool enough and want to display it as “Site Director” in the backend, this can also be easily achieved:
🔗 UI Optimization: “Modifying Any Role Name to Meet Your Frontend/Backend Display Needs”
IV. Practical Application: How to Determine Permissions and Restrict Behavior?
Once you have set up the role and permission system, the next step is to intercept permissions in the business code. The core function is current_user_can().
❌ Error Demonstration: Verification Based on Role Name
// Never do this! It violates the principle of least privilege
if ( current_user_can( 'administrator' ) ) {
// Display top-secret data
}✅ Correct Demonstration: Verification Based on Capability Name
// Should ask: Does the current user have the capability named 'view_secret_data'?
if ( current_user_can( 'view_secret_data' ) ) {
// Display top-secret data
}The most typical business scenario based on permission determination is restricting certain low-privilege roles from entering WordPress’s core backend dashboard:
🔗 Typical Case: “How to Restrict Regular Users from Accessing the WordPress Backend Dashboard (wp-admin)”
V. Advanced Battlefield: Custom Post Types (CPT) and Meta Capabilities
When you step into WordPress’s truly advanced development realm—registering “Custom Post Types (CPT)”—the permission system becomes incredibly complex and fascinating.
By default, if you register a CPT named Product, it will inherit the permission mechanism of post. That is to say, someone who can post articles can post products. But this is obviously not okay in an e-commerce scenario—we might need an independent “Product Manager” role who can only post products and cannot touch blog posts. At this time, you need to use the mysterious functional parameter map_meta_cap.
VI. Conclusion and Common Plugin Suggestions
WordPress’s role and permission system is a well-designed, highly extensible underlying logic architecture. When you can proficiently use code to manipulate the above APIs, you will have unparalleled development freedom and will no longer have to worry about performance loss issues of large permission grids.
Of course, what if you’re a non-developer or have a temporary emergency?
If you’re just a site operator, the time cost of writing code might be too high. At this time, you can also return to the plugin ecosystem. The following two plugins are recognized as the most powerful and mature alternative solutions:
- User Role Editor: Old-school, absolutely comprehensive features, what you see is what you get.
- Members (by MemberPress): Modernized interface, excels in content restriction and multi-role assignment.
Want to consult more underlying official specifications? Please enter the developer handbook we translated and organized:
“WordPress Plugin Development Tutorial Handbook — Users, Roles, and Capabilities”
