Skip to:

Roles and Capabilities in bbPress 2.2

  • John James Jacoby


    bbPress 2.2 implements a new way to think about user roles in both WordPress and bbPress. A few users have posted up having issues after upgrading, so I’m going to take some time to explain what changed and why.

    The problem bbPress 2.2 addresses, is the situation where a users ability to take certain actions in the forums was dictated by their role on the entire site, or their “blog role” as I’ll refer to it in some places going forward.

    This means that in the past, a user could not be both a blog Editor and a forum Moderator at the same time; you’d need to be one or the other, and it was clear this wasn’t what anybody wanted.

    In bbPress 2.0 and 2.1, every time you activated bbPress on a site, it went in and added a bunch of capabilities to the database. You never knew this, but it needed these roles so that users could perform certain tasks. bbPress would go in and modify the core WordPress roles, to add these capabilities to them. This made multisite installations a challenge, and network activation was very difficult too, because these roles needed to be added to every single site.

    For existing users of sites, bbPress performed a bunch of calculations and educated guesses to automatically grant users with certain roles and capabilities. To do this, it would eventually need to add capabilities to the user, or switch them to a role that had those capabilities already; Forum Participant.

    Subsequent updates to bbPress required database migration scripts for every change to user roles and capabilities. This is a lot of work for very little gain, since we’re not solving any problems with users needing multiple roles, and at the same time we’re polluting the database with a bunch of data that doesn’t change 99% of the time.

    Under the hood, WordPress comes with support for users having multiple roles, and this is a perfect use-case for needing that functionality. Roles are just groups of capabilities. If a user has a role, it’s safe to assume they also have certain capabilities, right?

    Wrong. Kind of. Sometimes.

    Capabilities are saved in the database, per user, per site, and they bubble based on the role they are granted. If you use any plugin that modifies editable roles or capabilities in the database, what you’re doing is changing the individual capabilities for every user that gets that role going forward, but not necessarily every user that had that role in the past.

    Remember, individual users have individual capabilities. When a user gets a new role that is modified in some way, they also get assigned the changed capabilities, either positive or negative. Negative capabilities are explicitly negative, and neither WordPress nor bbPress use these in core. They’re tricky, and make it easy to break things.

    Once you’ve gone this far in, you’re playing with fire and will likely get burned. You now have altered core user roles, extra forum user roles, and a mish-mash of registered users with a random assortment of capabilities, based on when they signed up, what role they were granted, and what you happened to have changed that blog role’s capabilities to be at that moment.

    To top this all off, there is no “repair” for your users, they’re basically stuck.

    For bbPress users that never modified user roles or capabilities, their update process would be smooth sailing. It’s the modifications to database permissions that cause issues with bbPress 2.2. Why?

    bbPress 2.2 introduces the concept of “dynamic roles” VS WordPress’s “editable roles.” What’s the difference? Editable roles are saved in the database, and allow you to completely shoot yourself in the foot (as above) once you start changing them around. Dynamic roles do not touch the database in any way, other than to assign the 1 role to the user, side-by-side with any other role they might have on your site.

    bbPress comes with filters to allow you to modify the roles, and it’s still possible to add or subtract specific forum capabilities to a user if you needed to, and without all the fuss and danger of bbPress interfering with existing user roles and capabilities.

    For users that are stuck with users that can’t access the forums, try using the forums role repair tool, located in: Admin > Tools > Forums

    That tool loops through your users, and grants them a forum role based on their blog role based on the following map:

    Admin = Keymaster
    Editor = Participant
    Author = Participant
    Contributor = Participant
    Subscriber = Participant

    The map can be filtered, as can the default role of Participant. The problem will come in with existing users that have modified Participant roles that you may have tinkered with. They’ll end up with capabilities that are totally out of whack, no matter what you do. You’ll need to use an additional tool on top of this, if you want to clean up those old roles introduced by plugins like S2member.

    Going forward, I’d like to get a better idea on what these plugins are doing, and make sure that bbPress plays as nicely as it can with them. Dynamic roles in WordPress core are probably a few releases away, but it’s important to bbPress’s future to have them in and working as soon as possible, to get everything dialed in for everyone.

Viewing 23 replies - 51 through 73 (of 73 total)

  • aberglas


    You say “Capabilities are saved in the database, per user, per site”. That is clearly NOT the (normal) case. The wp_usermeta table wp_2_capabilities row stores ROLES, not capabilities. Those roles appear to index into the wp_2_options tble row wp_2_user_roles row which contains a list of capabilities.

    I have no idea what “Dynamic” roles are nor why bbpress contains a vast amount of capability fidling code, including no less than three files called capability.php. If someone could explain it in terms of actual table rows and colums that might help.

    I want a simple setup where Authors can access Private forums but only in the site which they are an Author. The simple coupled set up that JJJ says is too simplistic. But now it cannot be done at all?

    By default private sites are hidden to users. There is a weird “Auto Role” option that can adds bbp_participant to all users. But that means that users get access to all forums on all sites. Is that the “Dynamic role” feature?

    So turn that off. Try to add bbp_participant role explicitly using action ‘add_user_to_blog’
    However, that failed to add the user. WordPress really only supports one role per user, certainly set_role() only accepts a single role and purges any others. So I think something is resetting it.

    Then I try simply
    get_role( ‘author’ )->add_cap( ‘read_private_topics’ ); // for bbpress.
    That successfully updates the database (wp_2_user_roles), but has no effect on bbpress. I suspect because one of the capability.php files in bbpress has
    case bbp_get_spectator_role() … ‘read_hidden_forums’ => false,
    rather than just leaving it out. So capabilities do not merge properly between roles.

    I am new to WordPress/bbPress, and having spent many hours in this mess am getting very frustrated. How hard can it be? Users/Roles/Capabilities.




    I’ve tried to look around but you’ll see the search terms on this are a bit generic.
    I just installed bbpress and what I found is that non-Admin can’t see the forums.
    I’m using the Advanced Access Manager plugin.
    All the forum-related options are checked in capabilities and none are excluded under posts and taxonomies.
    The forums/topics/replies section on the dashboard navigation (under pages) isn’t there.
    If I switch the user from Super Admin to just Admin, the forums re-appear. If I create a new role “Admin2” with full permissions, the forums disappear again.
    I see all the “is_admin” functions in the plugin code, but I’m not sure how that works. Is there some way to adjust the code to look for capabilities rather than roles?



    Thanks Justin and John for all your amazing contributions to the community. I have a few questions/thoughts…

    Dynamic roles – how to edit their caps?
    The switch to “dynamic” roles in the most recent BBPress has left me completely puzzled. I’m still not sure what “dynamic” is supposed to mean?!

    I can’t seem to find anywhere to view and/or edit the caps of these new forum roles. I’d like to, for some reason only “keymaster” users get the wysiwyg post edit form, whereas “participant” can only see the source code pane (no, there are no js errors?!).

    Roles and capabilities in WP
    I have been using Justin’s Members plugin, which made roles and caps in WordPress work like I feel it should. In the same way as in Drupal core. Any number of roles can be assigned to a user. Caps are assigned to roles – never to one single user of course. One specific user will have the combined capabilities of the roles he/she has.

    Am I right that the only thing keeping us from just having a happy life together with Members plugin – assigning many roles to one user – is WP core’s User Edit screen that cuts everything else but one role away when you click save? If so, this should be easy to fix by just modifying this User Edit form. Right!?

    Thanks! 🙂



    Ok so after digging and reading for many hours, getting a bit more into the situation, I’ve found answers to my questions above. So now I guess I’d just like to chime in to help find the best solution.

    Members plugin
    As I understand it, Justin’s Members plugin has pretty much fixed WP’s handling of capabilities by saving these roles in wp_usermeta as if they were capabilities, and allowing the assignment of capabilities to roles, instead of assigning them to individual user (which is just mad).

    Even though WP already supports multiple roles per user, its own user edit form sabotages this by removing all but one role if you click “save”.

    So it seems to me that if (hopefully when) the Members plugin become part of core, there shouldn’t be any need for bbPress to introduce a role handling interface – instead it would just add to the confusion, which I think is the case now, even though I realize that it is a valiant effort to fix a problem with WP core at this point in time.

    So wouldn’t all this be solved right now by just modifying WP’s user edit form to allow for multiple role assignment?



    I ended up getting
    $user = get_userdata( $user_id );
    to work. (I had been using the wrong method to get the $user.)

    But it is still messy. And @moonoi points out this will be lost whenever the UI is used, due to the set_role bug.

    get_role( ‘author’ )->add_cap( ‘read_private_topics’ );
    Still does not work, although it should. It would be a better solution for me because like 90% of sites I only actually need one role per user.

    It would be good to fix WP in this regard, and then remove the mess from bbPress. Or in the meantime just make BBPress work like everything else. Mucking about with roles is an orthogonal problem.

    I have not played with the Members Plugin, but WP by default does NOT store capabilities against users. It stores Roles agains users, and capabilities against Roles, at least by default.




    @aberglas Thanks for clearing up about WP not storing caps directly on users. I must have misread that somewhere.

    Anyway, you say that you haven’t used the Members plugin. Personally I try to avoid using the UI for any configuration (prefer to modify things with code). But the Members plugin is invaluable, and it really should be part of core. – Along with that fix to allow saving multiple roles. 🙂




    I’m not saying there is anything wrong with the members plugin, I just have not needed it. Like you I prefer code as I need to support multiple sites. And looking in the actual DB tends to provide a more reliable view of what is really going on.

    The original post of this topic could do with some clarification though, and then put up as proper bbPress doc.


    Chee Studio



    Good god man, thank you for posting this. Everything I was reading told me I needed to edit the database manually…I never knew of the Forum Tools. A couple of clicks and everything is fixed. Thank you endlessly!

    Earthman Media


    If you create the user, it doesn’t assign them a role right away. They’ll get role mapped once they login to the site, or once you assign them a role.

    In theory, but in a site using iMember360 and Infusionsoft, the user creation bypasses the standard WordPress hooks. So does logging in. Which leaves me with users who are subscribers but do not get a “Participant” role.

    I have been looking for documentation for how you are “mappping” them to a role as you mention, but can’t find any. Where are the roles stored now, please, and do you have an easy function I can call on a different hook so I can “map” them manually, please?

    @earthman100 If you just want to map them manually you can do this from the WordPress ‘Users’ admin panel though you need to be using bbPress 2.3.

    Earthman Media


    @Stephen – I don’t want to map them manually – Sorry, my wording was incorrect.

    What I meant in my post is that I want to create an Automated Function to tie into a hook when they enter the site, because the Login Hook is not being fired.

    I need to know what BBpress function to call to assign them a role in BBpress, please.

    John James Jacoby


    @earthman100 – Search for `bbp_set_current_user_default_role` – it’s hooked to `bbp_setup_current_user`, which is hooked to `setup_current_user`, which seems odd that any plugin would bypass completely, since pretty much everything a user does is linked to it.

    Which is to say, I don’t think manually handling the login or user-creation process is the problem; I think this plugin is `_doing_it_wrong()` by invoking the current user far too early, before bbPress ever has a chance to hook in.

    Earthman Media


    Thanks for pointing me in the right direction John – what file do I find that in please?

    To be honest, I haven’t dove right into the inner workings of iMember360 plugin yet, to understand fully what they are doing to create users/log people in, but I do know that it isn’t playing well with what you have done.

    Thanks for finally getting the roles sorted, excellent work! Now when the WP core team gets Roles/Caps sorted we will be laughing!

    John James Jacoby



    Thanks for the kind words. WordPress core doesn’t need a ton of work in this regard; a few small fixes would go a long way.

    Earthman Media


    Thanks for that.

    I’m guessing they are worried about ‘breaking’ millions of sites. While I am sure you are exceptionally diligent, even with the relatively small community BBpress has, you are already seeing edge cases here that you hadn’t imagined. With custom Roles and Caps and so many plugins to contend with, I’m sure there are a *few* more in the WP community.

    Earthman Media


    Well I got this far, but every time I try to call the function you suggested, or try to add the role manually, it breaks. Any ideas what I might be missing, please?

    add_action( 'wp', 'bbp_check_user_role_on_load' );
    function bbp_check_user_role_on_load() {
    	global $user_ID;
    	//do they have a role set already?
    	$has_bbp_role = bbp_get_user_role( $user_ID );
    	if(!$has_bbp_role){ //nope, add default BBP role 
    		//tried this but it breaks it
    		// Load up bbPress once
    		$bbp = bbpress();
    		$new_role = 'participant';
    		//this breaks too - wtf?
    		//$bbp->current_user->add_role( $new_role );

    John James Jacoby


    Not entirely sure how you arrived at that solution, but I can’t imagine any of it ever working correctly. 🙂

    The wp action happens before WP_Roles is called, so it’s too soon in the stack. You’re also missing a bunch of sanity checks that bbp_set_current_user_default_role already does for you; no sense in duplicating only some of that work.

    You could try hooking into init but, again, I suspect something in the iMember360 plugin is interfering and won’t allow that to work correctly either.

    You *should* actually be debugging the setup_current_user action, to see if bbp_set_current_user_default_role is even firing, and if it is, where it’s failing.

    If you’re looking for a brute-force kludge, something like this is probably closer to what you need:

    function earthman_force_current_user_caps() {
    	global $current_user;
    	// Only for logged in users
    	if ( ! is_user_logged_in() )
    	// Reload the current user with correct capabilities
    	$current_user = bbpress()->current_user = get_user_by( 'id', bbp_get_current_user_id() );
    	// Try to give them a role on the site, if they need one
    add_action( 'bbp_template_redirect', 'earthman_force_current_user_caps', -99 );

    Earthman Media


    Thanks, that worked! Given that my client is launching in the AM, he and I *both* appreciate your help.

    In regards to debugging the reason why that hook is not being called – I think I will post this on to iMember360 and let them look at *that* one.

    Again, thanks a bunch – I can finally go to bed now.



    I tried all suggestions from this thread and still not able to post new threads or replies except with a key master. moderator or participants can’t.

    tried resetting the forum roles on my 2.3 bbpress isntall and all authors were made spectators. isn’t participant assigned to author?

    ideally all users should be subscribers and participants. any further ideas how to fix broken permissions?



    I still can’t seem to figure out why users can’t delete their own replies. How can I add that ability?


    Ludovic S. Clain


    Hi there 👋 

    Thanks to the details of @stanis I am understanding why when I use WP-Cli with the line:
    wp user set-role <User id> bbp_blocked

    It blows up the existing role of the User on WordPress (in my case it was “customer” which becomes ” – no role for this site -“)

    But it’s still unclear for me. How to modify the role of an User on BBPPRESS without touching its WordPress role?

    Because the opposite is also true, if I do :
    wp user set-role <User ID> customer

    This time it is the role of the User on the forum that jumps and becomes “-No Role for these forums-”

    PS: I also tried
    wp user update <User ID> --role=customer --bbp-forums-role=bbp_blocked
    And that doesn’t do the job too 🙁

    Thanks for your lights!
    Warm regards,

    Robin W


    bbp_set_user_role( $user_id, $new_role )

    Ludovic S. Clain


    Hey 👋 
    Thank you @Robin-W,
    In the meantime I got to know the WP-Cli-Cli package specific to WordPress, which does not work either (I opened an issue visible here).

    To locate the context, I use WooCommerce Subscription plugin and I needed that when a subscription is canceled, access to the bbPress forum is blocked.

    I leave here the snippet that I made and that does the job:

    add_action('woocommerce_subscription_status_cancelled', 'block_forum_user_after_subscription_cancellation_s', 10, 1);
    function block_forum_user_after_subscription_cancellation_s($subscription)
        $user_id = $subscription->get_user_id();
        $new_role = 'bbp_blocked';
        bbp_set_user_role($user_id, $new_role);

    (I also have a webhook version with the WordPress Rest API for remote use, if necessary contact me)

Viewing 23 replies - 51 through 73 (of 73 total)
  • You must be logged in to reply to this topic.
Skip to toolbar