Roles and Capabilities

How BuddyNext decides who can do what. This page covers the permission model developers extend: the single buddynext_can() entry point, the four resolution layers in PermissionService, the capability catalog registered through the WordPress Abilities API, and the filter seams (buddynext_user_can, buddynext_role_map, buddynext_abilities) an extension uses to add, gate, or override a capability.

Overview / Contract#

BuddyNext does not register any custom WordPress roles. Neither Free nor Pro makes an add_role() call, and Pro's manifest confirms this with customRoles: []. There are no new WP_Role capabilities to map. Member authority is modeled in two BuddyNext-owned layers instead:

• A community role stored in user meta (bn_community_role): one of member, moderator, admin. Defaults to member when unset. RoleService::set_role() ignores any other value; owner exists only as a per-space role (below).
• A per-space role stored in the bn_space_members table (role column): owner, moderator, or member for an active membership.

WordPress site administrators are recognized through the native manage_options capability, not a BuddyNext role. Every wp-admin screen BuddyNext registers gates on manage_options (see Admin Pages and Settings).

Every permission decision in the plugin flows through one function:

buddynext_can( int $user_id, string $capability, array $context = array() ): bool

Defined in buddynext.php, it resolves the permissions service from the container and calls PermissionService::can(). Never call current_user_can() against a BuddyNext capability or read bn_community_role directly to make an authorization decision - route it through buddynext_can() so all four layers and the filter seams apply.

The four resolution layers#

PermissionService::can() resolves a check in this order:

Three hard-deny short-circuits apply around the layers above:

• A user who is space-banned (a row in bn_space_bans, or a bn_space_members row with status = 'banned') is denied every buddynext-spaces/* capability when a space_id is in context, regardless of role.
• A suspended member is denied every capability except buddynext-profile/view and buddynext-moderation/review-queue (PermissionService::READ_CAPS), so write controls hide and writes refuse from one source. Site admins are exempt.
• The space-scoped capabilities buddynext-moderate-space, buddynext-manage-space, and buddynext-own-space bypass the generic role map and resolve through dedicated methods that read the caller's role in that specific space.

The role hierarchy#

Roles are ranked numerically. A capability mapped to a role is granted to that role and everything above it. PermissionService ranks four roles; the community role only ever holds admin, moderator or member, and owner applies to the in-space role of a space owner.

A capability mapped to null in the role map has no role gate - it can only be granted through an explicit ability grant or the buddynext_user_can filter.

The capability catalog#

Capabilities are dot-namespaced slugs (buddynext-{domain}/{action}).

There are three lists in code and they are not the same list. Know which one you are looking at:

Enforcement is the list that matters for buddynext_can(). The other two only decide whether an owner gets a control for it.

The role map holds 24 generic capabilities:

A site-wide moderator holds full moderation authority. Clearing the queue, issuing strikes, suspending, shadow-banning, and warnings are all moderator powers. Only appeals, and editing what each role is allowed to do, remain admin-only.

buddynext-spaces/create has one option that overrides its default. The legacy Spaces-tab "who can create spaces" setting is folded into the role map: when get_option( 'buddynext_space_creation_role' ) is 'admin', the map default flips from member to admin. The default ('member') leaves the map untouched. It is applied inside role_map() so it composes with the Roles and Capabilities tab instead of fighting it.

buddynext-comments/create is grantable from the admin. It is present in PermissionService::ROLE_MAP, in Abilities::CATALOG, and in RolesTab::catalog(), so it is registered with the WordPress Abilities API and renders a row ("Comment on posts") on the Roles and Capabilities tab like any other capability. The filter also works if you want to set the role in code:

add_filter( 'buddynext_role_map', static function ( array $map ): array {
    $map['buddynext-comments/create'] = 'moderator';
    return $map;
} );

Three additional space-scoped capabilities - buddynext-moderate-space, buddynext-manage-space, and buddynext-own-space - are resolved by dedicated per-space methods (can_moderate_space() / can_manage_space() / can_own_space()) and are not part of the generic role map. buddynext-moderate-space and buddynext-manage-space are both granted to a space owner OR moderator (moderators can manage space settings, they just cannot remove the owner or delete the space); buddynext-own-space is the strictly owner-only gate, split out for the two things a moderator must never do because neither is reversible from their side: delete the space, and change who owns it (transfer ownership, assign a new owner).

Ability slugs may contain / and -. The grant meta key translates those to _, so buddynext-feed/schedule-post is stored as bn_ability_buddynext_feed_schedule_post. Use PermissionService::ability_meta_key( $slug ) to build the key rather than hand-rolling it.

Examples#

Check a capability#

// A plain capability check.
if ( buddynext_can( get_current_user_id(), 'buddynext-feed/create-post' ) ) {
    // Render the composer.
}

// A space-scoped check - pass the space_id in context.
if ( buddynext_can( $user_id, 'buddynext-spaces/post', array( 'space_id' => 42 ) ) ) {
    // Allow posting into space 42.
}

Register a new capability and gate it behind a role#

Adding a capability is two filters: register the slug with the Abilities API, then give it a role in the role map. Do both on plugins_loaded (or earlier) so they are in place before any check runs.

// 1. Add the slug to the catalog so the Abilities API registers it.
add_filter( 'buddynext_abilities', function ( array $abilities ) {
    $abilities[] = 'buddynext-feed/create-event';
    return $abilities;
} );

// 2. Gate it behind a community role. 'member', 'moderator', 'admin', 'owner',
//    or null for "no role gate" (explicit grant / filter only).
add_filter( 'buddynext_role_map', function ( array $map ) {
    $map['buddynext-feed/create-event'] = 'moderator';
    return $map;
} );

The capability is now enforceable through buddynext_can( $user_id, 'buddynext-feed/create-event' ).

Override a capability for one decision#

buddynext_user_can is the final layer and runs on every check, so it can grant or deny regardless of what the role and grant layers resolved.

add_filter(
    'buddynext_user_can',
    function ( bool $result, int $user_id, string $capability, array $context ) {
        // Let verified members delete any post even though that defaults to moderator.
        if ( 'buddynext-feed/delete-any-post' === $capability
            && get_user_meta( $user_id, 'is_verified_member', true ) ) {
            return true;
        }
        return $result;
    },
    10,
    4
);

Grant a capability to one user#

An explicit grant (layer 3) is a user-meta entry whose value is the expiry: 0 for no expiry, or a future unix timestamp.

use BuddyNext\Core\PermissionService;

// Grant the review-queue capability to user 12, never expiring.
update_user_meta(
    12,
    PermissionService::ability_meta_key( 'buddynext-moderation/review-queue' ),
    0
);

Notes / gotchas#

• No custom roles to clean up. Because BuddyNext registers no WP_Role, there is nothing to remove on deactivation and no capability bloat on the administrator role. Authority lives in user meta and bn_space_members.
• manage_options is the admin gate, not a BuddyNext role. Site admins pass every buddynext_can() check by virtue of layer 1, and every BuddyNext admin screen checks manage_options directly.
• buddynext_role_map fires once and is memoised per request; buddynext_user_can fires on every check. Put baseline role mappings in the role map and per-decision logic in the filter.
• Space context matters. For buddynext-spaces/* capabilities, pass ['space_id' => N] so the in-space role (from bn_space_members) is used. The join capability is the exception - a non-member has no in-space role yet, so join is gated by the community role, with space type (open/request/invite) enforced separately in the join flow.
• Free / Pro boundary. The catalog and the four-layer model live entirely in free. Pro consumes buddynext_can() like any other caller and does not add custom roles or its own permission engine.

See also Admin Pages and Settings for how the admin surface gates on manage_options, and the REST contract page for how controllers resolve buddynext_can() before serving a request.