Hooks: Spaces

The action and filter seams for spaces (groups) and their membership: creation, update, deletion, ownership, joins, requests, invitations, bans, role changes, and per-member notification preferences. This page is for developers building moderation tools, notification bridges, gated-access or paywall integrations, and theme extensions for space pages. Every hook below is fired or applied by BuddyNext Free. The two seams that matter most for extension are buddynext_can_join_space (the Free-to-Pro access gate) and buddynext_space_types (registering new space kinds).

Overview / Contract

• Actions fire after the write commits. Membership and lifecycle actions pass IDs, not hydrated rows. Re-fetch via buddynext_service( 'spaces' )->get( $space_id ) when you need more than the IDs. The container key is spaces, not space_service.
• buddynext_can_join_space is the access gate. It runs before any database work in both the direct-join and request-membership paths. Return false to block; BuddyNext then short-circuits with a WP_Error built by the denial path, and buddynext_space_join_denied_data lets you attach a payload (for example a Pro paywall) to that error.
• Removal vs ban are distinct events. A ban also removes the membership, so a ban fires both buddynext_space_member_removed (so removal listeners such as cache busting always react) and buddynext_space_user_banned (so ban-specific listeners react). Listen to whichever matches your intent.
• Idempotent membership writes. Joins, requests, and invites use INSERT IGNORE; their actions fire only when the membership state actually changes. Unban fires only when an active ban row was deleted.
• Space types are config maps, not classes. buddynext_space_types filters a slug-keyed array. Behaviour (visibility and join flow) is derived from each entry's visibility field; the three built-in types cannot be removed.
• Visibility has ONE decision point. BuddyNext\Spaces\SpaceVisibility answers "can this viewer see this space / its roster / its content?" for every surface - the server-rendered template AND the REST route. buddynext_space_can_view_roster is applied inside it, so a single add_filter() changes the members page and GET /spaces/{id}/members together; the page and the app cannot disagree.

Space visibility

Default: true for open spaces; false for private and secret spaces unless the viewer is an active member, a moderator, the space owner, or a site admin. A private space is listed but gated - its name, description, house rules, avatar, cover, category, member COUNT, and its owner + moderator list stay public (a stranger needs them to decide whether to request to join), while the full member roster does not.

Return true to re-open private rosters Facebook-style. The filter is applied at the single decision point, so this one call re-opens both the members page and the REST roster route:

// Anyone may browse a private space's member list (Facebook-style).
add_filter( 'buddynext_space_can_view_roster', '__return_true' );

// Or selectively: open private rosters to logged-in members of the community,
// but never a secret space's, and never to a logged-out visitor.
add_filter( 'buddynext_space_can_view_roster', function ( bool $can_view, int $space_id, int $viewer_id, string $type ): bool {
    if ( $can_view || 'private' !== $type ) {
        return $can_view;
    }
    return $viewer_id > 0;
}, 10, 4 );

Space lifecycle

buddynext_space_archived and buddynext_space_unarchived are dispatched from a single call site that selects the hook name by state, so a listener only fires on the transition it registered for.

buddynext_space_updated fires with the full three arguments from every call site.

This was not always true. SpaceFieldRegistry::save() used to fire $space_id alone, so a typed three-parameter listener - registered exactly as documented - took an ArgumentCountError on that one path. It now passes $space_id, get_current_user_id(), $saved like the two SpaceService call sites, and the source carries a comment saying the arity is part of the contract and must not vary by call site. Earlier versions of this page told you to default the second and third parameters as a workaround; that is no longer necessary.

Membership: join, request, invite

Note: When a request is approved, both buddynext_space_join_approved and buddynext_space_member_joined fire (in that order). The first is the moderation event; the second is the "this user is now an active member" event, identical to the one fired on a direct join.

Membership: leave, remove, ban, roles, preferences

Warning: A ban removes the membership, so it fires buddynext_space_member_removed and buddynext_space_user_banned together. If you maintain a banned-users list, listen to buddynext_space_user_banned specifically; if you only need to react to "this user is no longer in the space" (for example, busting a sidebar cache), listen to buddynext_space_member_removed and you will cover both removals and bans.

Space types

Each space-type entry has this shape. Visibility drives the behaviour: public allows direct joins, private requires a request, secret is invite-only.

'open' => [
    'label'      => __( 'Open', 'buddynext' ),  // UI label
    'tone'       => 'success',                   // badge tone slug
    'visibility' => 'public',                    // 'public' | 'private' | 'secret'
    'join'       => 'direct',                    // 'direct' | 'request' | 'invite'
],

The built-in types are open (public/direct), private (private/request), and secret (secret/invite). They cannot be removed by the filter, only added to.

Examples

Gate a space behind a membership plan

buddynext_can_join_space is the seam Pro uses for paywalls and gated plans. Return false to block; pair it with buddynext_space_join_denied_data to surface a reason or paywall payload in the REST error response. The gate runs before any database work, so a denied user never creates a row.

// Block the join/request unless the user holds the required entitlement.
add_filter( 'buddynext_can_join_space', function ( bool $can, array $space, int $user_id, string $action ): bool {
    if ( ! $can ) {
        return false; // Someone already denied it.
    }
    $required_tier = (int) get_post_meta( (int) ( $space['id'] ?? 0 ), '_required_tier', true );
    if ( $required_tier > 0 && ! my_membership_user_has_tier( $user_id, $required_tier ) ) {
        return false;
    }
    return $can;
}, 10, 4 );

// Attach a paywall payload to the denial so the client can render a CTA.
add_filter( 'buddynext_space_join_denied_data', function ( array $data, int $space_id, int $user_id, array $space, string $action ): array {
    $data['paywall'] = [
        'message' => __( 'This space is for premium members.', 'my-addon' ),
        'cta_url' => home_url( '/upgrade/' ),
    ];
    return $data;
}, 10, 5 );

Note: buddynext_can_join_space fires for both the direct-join path ($action === 'join') and the request-membership path ($action === 'request'). Branch on $action if your rules differ between the two.

Register a custom space type

add_filter( 'buddynext_space_types', function ( array $types ): array {
    $types['announce_only'] = [
        'label'      => __( 'Announcements', 'my-addon' ),
        'tone'       => 'info',
        'visibility' => 'public',  // anyone can join
        'join'       => 'direct',
    ];
    return $types;
} );

React to a new member in a space

add_action( 'buddynext_space_member_joined', function ( int $space_id, int $user_id, string $role ): void {
    my_addon_send_welcome_dm( $user_id, $space_id );
}, 10, 3 );

Notes / gotchas

• Free vs Pro. Every hook here is fired by Free. buddynext_can_join_space plus buddynext_space_join_denied_data are the documented gated-spaces / paywall seam that Pro builds on; buddynext_space_types is the extension point for new space kinds.
• The gate runs first. Because buddynext_can_join_space short-circuits before any insert, you cannot rely on a *_member_joined action to undo a join you wanted to block. Block it at the gate.
• Ban fires two actions. Choose buddynext_space_user_banned for ban-specific behaviour and buddynext_space_member_removed for "no longer a member" behaviour. They fire together on a ban.
• Re-fetch space data. Lifecycle actions pass IDs only. Hydrate via buddynext_service( 'spaces' )->get( $space_id ) rather than reading $space from a stale closure.