How to Add Custom Capability in WordPress Easily

To add a custom capability in WordPress, use the add_cap() method on a role object, like get_role('administrator')->add_cap('custom_capability'). This lets you define new permissions that you can check with current_user_can('custom_capability').

Syntax

Use the add_cap() method on a role object to add a custom capability. The main parts are:

• get_role('role_name'): Gets the role object (e.g., 'administrator', 'editor').
• add_cap('capability_name'): Adds the new capability string to that role.

php

$role = get_role('role_name');
$role->add_cap('custom_capability');

Example

This example adds a custom capability called edit_special_content to the administrator role. Then it checks if the current user has that capability.

php

<?php
// Add custom capability to administrator role
function add_custom_capability() {
    $role = get_role('administrator');
    if ($role && !$role->has_cap('edit_special_content')) {
        $role->add_cap('edit_special_content');
    }
}
add_action('init', 'add_custom_capability');

// Check capability usage example
if (current_user_can('edit_special_content')) {
    echo 'You can edit special content!';
} else {
    echo 'You do NOT have permission to edit special content.';
}
?>

Output

You can edit special content!

Common Pitfalls

Common mistakes when adding custom capabilities:

• Adding capabilities outside of an action hook like init can cause errors because roles may not be loaded yet.
• Not checking if the capability already exists can add duplicates or cause unexpected behavior.
• Forgetting to assign the capability to the correct role means users won't get the permission.
• Assuming capabilities automatically apply to all roles; you must add them explicitly.

php

<?php
// Wrong: Adding capability too early
$role = get_role('administrator');
$role->add_cap('edit_special_content'); // May fail if roles not loaded yet

// Right: Add capability inside init hook
add_action('init', function() {
    $role = get_role('administrator');
    if ($role && !$role->has_cap('edit_special_content')) {
        $role->add_cap('edit_special_content');
    }
});
?>

Quick Reference

Summary tips for adding custom capabilities in WordPress:

• Use get_role('role_name')->add_cap('capability') to add capabilities.
• Always add capabilities inside an action hook like init.
• Check if the capability exists with has_cap() before adding.
• Use current_user_can('capability') to check permissions in your code.
• Remove capabilities with remove_cap() if needed.

Key Takeaways

Add custom capabilities using get_role('role_name')->add_cap('capability') inside an init hook.

Always check if a capability exists before adding it to avoid duplicates.

Use current_user_can('capability') to verify user permissions in your code.

Assign capabilities only to roles that should have them for proper access control.

Remove capabilities with remove_cap() when cleaning up or changing permissions.