superpowers-sage:wp-capabilities

WordPress Capabilities and Authorization

When to use

When implementing access control, permission checks, or role-based authorization in a Sage/Acorn project. This includes protecting REST API endpoints, restricting admin features, creating custom capabilities for custom post types, and bridging WordPress capabilities with Laravel-style Gates and Policies via Acorn.

Inputs required

• The resource or action being protected (e.g., a CPT, an API endpoint, an admin page)
• The user roles that need access
• Whether custom capabilities are needed or built-in ones suffice
• Whether JWT middleware or Acorn guards are involved (cross-reference acorn-middleware)

Procedure

1. Understand the capability hierarchy

WordPress authorization follows: Roles -> Capabilities -> Meta Capabilities.

• Roles are named collections of capabilities (administrator, editor, author, contributor, subscriber).
• Capabilities are granular permissions (edit_posts, manage_options, upload_files).
• Meta capabilities are virtual capabilities that map dynamically based on context (e.g., edit_post for a specific post maps to edit_posts or edit_others_posts depending on ownership).

2. Common capability groups

Group	Capabilities
Options	manage_options, manage_network_options
Posts	edit_posts, edit_others_posts, publish_posts, delete_posts, read_private_posts
Pages	edit_pages, edit_others_pages, publish_pages, delete_pages
Users	list_users, create_users, edit_users, delete_users, promote_users
Uploads	upload_files
Plugins/Themes	activate_plugins, edit_plugins, switch_themes, edit_themes

3. Check capabilities in code

// In Service classes or controllers
if (current_user_can('edit_post', $post_id)) {
    // User can edit this specific post (meta capability — ownership checked)
}

if (current_user_can('manage_options')) {
    // User is an administrator
}