[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * bbPress Capabilites
   5   *
   6   * The functions in this file are used primarily as convenient wrappers for
   7   * capability output in user profiles. This includes mapping capabilities and
   8   * groups to human readable strings,
   9   *
  10   * @package bbPress
  11   * @subpackage Capabilities
  12   */
  13  
  14  // Exit if accessed directly
  15  defined( 'ABSPATH' ) || exit;
  16  
  17  /** Mapping *******************************************************************/
  18  
  19  /**
  20   * Returns an array of capabilities based on the role that is being requested.
  21   *
  22   * @since 2.0.0 bbPress (r2994)
  23   *
  24   * @todo Map all of these and deprecate
  25   *
  26   * @param string $role Optional. Defaults to The role to load caps for
  27   *
  28   * @return array Capabilities for $role
  29   */
  30  function bbp_get_caps_for_role( $role = '' ) {
  31  
  32      // Which role are we looking for?
  33      switch ( $role ) {
  34  
  35          // Keymaster
  36          case bbp_get_keymaster_role() :
  37              $caps = array(
  38  
  39                  // Keymasters only
  40                  'keep_gate'             => true,
  41  
  42                  // Primary caps
  43                  'spectate'              => true,
  44                  'participate'           => true,
  45                  'moderate'              => true,
  46                  'throttle'              => true,
  47                  'view_trash'            => true,
  48                  'assign_moderators'     => true,
  49  
  50                  // Forum caps
  51                  'publish_forums'        => true,
  52                  'edit_forums'           => true,
  53                  'edit_others_forums'    => true,
  54                  'delete_forums'         => true,
  55                  'delete_others_forums'  => true,
  56                  'read_private_forums'   => true,
  57                  'read_hidden_forums'    => true,
  58  
  59                  // Topic caps
  60                  'publish_topics'        => true,
  61                  'edit_topics'           => true,
  62                  'edit_others_topics'    => true,
  63                  'delete_topics'         => true,
  64                  'delete_others_topics'  => true,
  65                  'read_private_topics'   => true,
  66  
  67                  // Reply caps
  68                  'publish_replies'       => true,
  69                  'edit_replies'          => true,
  70                  'edit_others_replies'   => true,
  71                  'delete_replies'        => true,
  72                  'delete_others_replies' => true,
  73                  'read_private_replies'  => true,
  74  
  75                  // Topic tag caps
  76                  'manage_topic_tags'     => true,
  77                  'edit_topic_tags'       => true,
  78                  'delete_topic_tags'     => true,
  79                  'assign_topic_tags'     => true
  80              );
  81  
  82              break;
  83  
  84          // Moderator
  85          case bbp_get_moderator_role() :
  86              $caps = array(
  87  
  88                  // Primary caps
  89                  'spectate'              => true,
  90                  'participate'           => true,
  91                  'moderate'              => true,
  92                  'throttle'              => true,
  93                  'view_trash'            => true,
  94                  'assign_moderators'     => true,
  95  
  96                  // Forum caps
  97                  'publish_forums'        => true,
  98                  'edit_forums'           => true,
  99                  'read_private_forums'   => true,
 100                  'read_hidden_forums'    => true,
 101  
 102                  // Topic caps
 103                  'publish_topics'        => true,
 104                  'edit_topics'           => true,
 105                  'edit_others_topics'    => true,
 106                  'delete_topics'         => true,
 107                  'delete_others_topics'  => true,
 108                  'read_private_topics'   => true,
 109  
 110                  // Reply caps
 111                  'publish_replies'       => true,
 112                  'edit_replies'          => true,
 113                  'edit_others_replies'   => true,
 114                  'delete_replies'        => true,
 115                  'delete_others_replies' => true,
 116                  'read_private_replies'  => true,
 117  
 118                  // Topic tag caps
 119                  'manage_topic_tags'     => true,
 120                  'edit_topic_tags'       => true,
 121                  'delete_topic_tags'     => true,
 122                  'assign_topic_tags'     => true,
 123              );
 124  
 125              break;
 126  
 127          // Spectators can only read
 128          case bbp_get_spectator_role()   :
 129              $caps = array(
 130  
 131                  // Primary caps
 132                  'spectate'              => true,
 133              );
 134  
 135              break;
 136  
 137          // Explicitly blocked
 138          case bbp_get_blocked_role() :
 139              $caps = array(
 140  
 141                  // Primary caps
 142                  'spectate'              => false,
 143                  'participate'           => false,
 144                  'moderate'              => false,
 145                  'throttle'              => false,
 146                  'view_trash'            => false,
 147  
 148                  // Forum caps
 149                  'publish_forums'        => false,
 150                  'edit_forums'           => false,
 151                  'edit_others_forums'    => false,
 152                  'delete_forums'         => false,
 153                  'delete_others_forums'  => false,
 154                  'read_private_forums'   => false,
 155                  'read_hidden_forums'    => false,
 156  
 157                  // Topic caps
 158                  'publish_topics'        => false,
 159                  'edit_topics'           => false,
 160                  'edit_others_topics'    => false,
 161                  'delete_topics'         => false,
 162                  'delete_others_topics'  => false,
 163                  'read_private_topics'   => false,
 164  
 165                  // Reply caps
 166                  'publish_replies'       => false,
 167                  'edit_replies'          => false,
 168                  'edit_others_replies'   => false,
 169                  'delete_replies'        => false,
 170                  'delete_others_replies' => false,
 171                  'read_private_replies'  => false,
 172  
 173                  // Topic tag caps
 174                  'manage_topic_tags'     => false,
 175                  'edit_topic_tags'       => false,
 176                  'delete_topic_tags'     => false,
 177                  'assign_topic_tags'     => false,
 178              );
 179  
 180              break;
 181  
 182          // Participant/Default
 183          case bbp_get_participant_role() :
 184          default :
 185              $caps = array(
 186  
 187                  // Primary caps
 188                  'spectate'              => true,
 189                  'participate'           => true,
 190  
 191                  // Forum caps
 192                  'read_private_forums'   => true,
 193  
 194                  // Topic caps
 195                  'publish_topics'        => true,
 196                  'edit_topics'           => true,
 197  
 198                  // Reply caps
 199                  'publish_replies'       => true,
 200                  'edit_replies'          => true,
 201  
 202                  // Topic tag caps
 203                  'assign_topic_tags'     => true,
 204              );
 205  
 206              break;
 207      }
 208  
 209      // Filter & return
 210      return apply_filters( 'bbp_get_caps_for_role', $caps, $role );
 211  }
 212  
 213  /**
 214   * Adds capabilities to WordPress user roles.
 215   *
 216   * @since 2.0.0 bbPress (r2608)
 217   */
 218  function bbp_add_caps() {
 219  
 220      // Loop through available roles and add caps
 221      foreach ( bbp_get_wp_roles()->role_objects as $role ) {
 222          foreach ( bbp_get_caps_for_role( $role->name ) as $cap => $value ) {
 223              $role->add_cap( $cap, $value );
 224          }
 225      }
 226  
 227      do_action( 'bbp_add_caps' );
 228  }
 229  
 230  /**
 231   * Removes capabilities from WordPress user roles.
 232   *
 233   * @since 2.0.0 bbPress (r2608)
 234   */
 235  function bbp_remove_caps() {
 236  
 237      // Loop through available roles and remove caps
 238      foreach ( bbp_get_wp_roles()->role_objects as $role ) {
 239          foreach ( array_keys( bbp_get_caps_for_role( $role->name ) ) as $cap ) {
 240              $role->remove_cap( $cap );
 241          }
 242      }
 243  
 244      do_action( 'bbp_remove_caps' );
 245  }
 246  
 247  /**
 248   * Get the available roles, minus the dynamic roles that come with bbPress
 249   *
 250   * @since 2.4.0 bbPress (r5064)
 251   *
 252   * @return array
 253   */
 254  function bbp_get_blog_roles() {
 255  
 256      // Get WordPress's roles (returns $wp_roles global)
 257      $wp_roles = bbp_get_wp_roles();
 258  
 259      // Apply the WordPress 'editable_roles' filter to let plugins ride along.
 260      //
 261      // We use this internally via bbp_filter_blog_editable_roles() to remove
 262      // any custom bbPress roles that are added to the global.
 263      $the_roles = isset( $wp_roles->roles ) ? $wp_roles->roles : false;
 264      $all_roles = apply_filters( 'editable_roles', $the_roles );
 265  
 266      // Filter & return
 267      return apply_filters( 'bbp_get_blog_roles', $all_roles, $wp_roles );
 268  }
 269  
 270  /** Forum Roles ***************************************************************/
 271  
 272  /**
 273   * Add the bbPress roles to the $wp_roles global.
 274   *
 275   * We do this to avoid adding these values to the database.
 276   *
 277   * Note: bbPress is purposely assertive here, overwriting any keys & values
 278   * that may already exist in the $wp_roles array.
 279   *
 280   * @since 2.2.0 bbPress (r4290)
 281   *
 282   * @param WP_Roles $wp_roles The array of WP_Role objects that was initialized
 283   *
 284   * @return WP_Roles The main $wp_roles global
 285   */
 286  function bbp_add_forums_roles( $wp_roles = null ) {
 287  
 288      // Get the dynamic roles
 289      $bbp_roles = bbp_get_dynamic_roles();
 290  
 291      // Loop through dynamic roles and add them to the $wp_roles array
 292      foreach ( $bbp_roles as $role_id => $details ) {
 293          $wp_roles->roles[ $role_id ]        = $details;
 294          $wp_roles->role_objects[ $role_id ] = new WP_Role( $role_id, $details['capabilities'] );
 295          $wp_roles->role_names[ $role_id ]   = $details['name'];
 296      }
 297  
 298      // Return the modified $wp_roles array
 299      return $wp_roles;
 300  }
 301  
 302  /**
 303   * Helper function to add filter to option_wp_user_roles
 304   *
 305   * @since 2.2.0 bbPress (r4363)
 306   * @deprecated 2.6.0 bbPress (r6105)
 307   *
 308   * @see _bbp_reinit_dynamic_roles()
 309   */
 310  function bbp_filter_user_roles_option() {
 311      $role_key = bbp_db()->prefix . 'user_roles';
 312  
 313      add_filter( 'option_' . $role_key, '_bbp_reinit_dynamic_roles' );
 314  }
 315  
 316  /**
 317   * This is necessary because in a few places (noted below) WordPress initializes
 318   * a blog's roles directly from the database option. When this happens, the
 319   * $wp_roles global gets flushed, causing a user to magically lose any
 320   * dynamically assigned roles or capabilities when $current_user in refreshed.
 321   *
 322   * Because dynamic multiple roles is a new concept in WordPress, we work around
 323   * it here for now, knowing that improvements will come to WordPress core later.
 324   *
 325   * Also note that if using the $wp_user_roles global non-database approach,
 326   * bbPress does not have an intercept point to add its dynamic roles.
 327   *
 328   * @see bbp_switch_to_site()
 329   * @see bbp_restore_current_site()
 330   * @see WP_Roles::_init()
 331   *
 332   * @since 2.2.0 bbPress (r4363)
 333   * @deprecated 2.6.0 bbPress (r6105)
 334   *
 335   * @internal Used by bbPress to reinitialize dynamic roles on blog switch
 336   *
 337   * @param array $roles
 338   * @return array Combined array of database roles and dynamic bbPress roles
 339   */
 340  function _bbp_reinit_dynamic_roles( $roles = array() ) {
 341      foreach ( bbp_get_dynamic_roles() as $role_id => $details ) {
 342          $roles[ $role_id ] = $details;
 343      }
 344      return $roles;
 345  }
 346  
 347  /**
 348   * Fetch a filtered list of forum roles that the current user is
 349   * allowed to have.
 350   *
 351   * Simple function who's main purpose is to allow filtering of the
 352   * list of forum roles so that plugins can remove inappropriate ones depending
 353   * on the situation or user making edits.
 354   *
 355   * Specifically because without filtering, anyone with the edit_users
 356   * capability can edit others to be administrators, even if they are
 357   * only editors or authors. This filter allows admins to delegate
 358   * user management.
 359   *
 360   * @since 2.2.0 bbPress (r4284)
 361   * @since 2.6.0 bbPress (r6117) Use bbpress()->roles
 362   *
 363   * @return array
 364   */
 365  function bbp_get_dynamic_roles() {
 366  
 367      // Defaults
 368      $to_array = array();
 369      $roles    = bbpress()->roles;
 370  
 371      // Convert WP_Roles objects to arrays
 372      foreach ( $roles as $role_id => $wp_role ) {
 373          $to_array[ $role_id ] = (array) $wp_role;
 374      }
 375  
 376      // Filter & return
 377      return (array) apply_filters( 'bbp_get_dynamic_roles', $to_array, $roles );
 378  }
 379  
 380  /**
 381   * Gets a translated role name from a role ID
 382   *
 383   * @since 2.3.0 bbPress (r4792)
 384   * @since 2.6.0 bbPress (r6117) Use bbp_translate_user_role()
 385   *
 386   * @param string $role_id
 387   * @return string Translated role name
 388   */
 389  function bbp_get_dynamic_role_name( $role_id = '' ) {
 390      $roles = bbp_get_dynamic_roles();
 391      $role  = isset( $roles[ $role_id ] )
 392          ? bbp_translate_user_role( $roles[ $role_id ]['name'] )
 393          : '';
 394  
 395      // Filter & return
 396      return apply_filters( 'bbp_get_dynamic_role_name', $role, $role_id, $roles );
 397  }
 398  
 399  /**
 400   * Removes the bbPress roles from the editable roles array
 401   *
 402   * This used to use array_diff_assoc() but it randomly broke before 2.2 release.
 403   * Need to research what happened, and if there's a way to speed this up.
 404   *
 405   * @since 2.2.0 bbPress (r4303)
 406   *
 407   * @param array $all_roles All registered roles
 408   * @return array
 409   */
 410  function bbp_filter_blog_editable_roles( $all_roles = array() ) {
 411  
 412      // Loop through bbPress roles
 413      foreach ( array_keys( bbp_get_dynamic_roles() ) as $bbp_role ) {
 414  
 415          // Loop through WordPress roles
 416          foreach ( array_keys( $all_roles ) as $wp_role ) {
 417  
 418              // If keys match, unset
 419              if ( $wp_role === $bbp_role ) {
 420                  unset( $all_roles[ $wp_role ] );
 421              }
 422          }
 423      }
 424  
 425      return $all_roles;
 426  }
 427  
 428  /**
 429   * The keymaster role for bbPress users
 430   *
 431   * @since 2.2.0 bbPress (r4284)
 432   *
 433   * @return string
 434   */
 435  function bbp_get_keymaster_role() {
 436  
 437      // Filter & return
 438      return apply_filters( 'bbp_get_keymaster_role', 'bbp_keymaster' );
 439  }
 440  
 441  /**
 442   * The moderator role for bbPress users
 443   *
 444   * @since 2.0.0 bbPress (r3410)
 445   *
 446   * @return string
 447   */
 448  function bbp_get_moderator_role() {
 449  
 450      // Filter & return
 451      return apply_filters( 'bbp_get_moderator_role', 'bbp_moderator' );
 452  }
 453  
 454  /**
 455   * The participant role for registered user that can participate in forums
 456   *
 457   * @since 2.0.0 bbPress (r3410)
 458   *
 459   * @return string
 460   */
 461  function bbp_get_participant_role() {
 462  
 463      // Filter & return
 464      return apply_filters( 'bbp_get_participant_role', 'bbp_participant' );
 465  }
 466  
 467  /**
 468   * The spectator role is for registered users without any capabilities
 469   *
 470   * @since 2.1.0 bbPress (r3860)
 471   *
 472   * @return string
 473   */
 474  function bbp_get_spectator_role() {
 475  
 476      // Filter & return
 477      return apply_filters( 'bbp_get_spectator_role', 'bbp_spectator' );
 478  }
 479  
 480  /**
 481   * The blocked role is for registered users that cannot spectate or participate
 482   *
 483   * @since 2.2.0 bbPress (r4284)
 484   *
 485   * @return string
 486   */
 487  function bbp_get_blocked_role() {
 488  
 489      // Filter & return
 490      return apply_filters( 'bbp_get_blocked_role', 'bbp_blocked' );
 491  }
 492  
 493  /**
 494   * Adds bbPress-specific user roles.
 495   *
 496   * @since 2.0.0 bbPress (r2741)
 497   *
 498   * @deprecated 2.2.0 bbPress (r4164)
 499   */
 500  function bbp_add_roles() {
 501      _doing_it_wrong( 'bbp_add_roles', esc_html__( 'Editable forum roles no longer exist.', 'bbpress' ), '2.2' );
 502  }
 503  
 504  /**
 505   * Removes bbPress-specific user roles from the `wp_user_roles` array.
 506   *
 507   * This is currently only used when updating, uninstalling, or resetting bbPress.
 508   *
 509   * @see    bbp_admin_reset_handler()
 510   * @see bbp_do_uninstall()
 511   * @see bbp_version_updater()
 512   *
 513   * @since 2.0.0 bbPress (r2741)
 514   */
 515  function bbp_remove_roles() {
 516  
 517      // Remove the bbPress roles
 518      foreach ( array_keys( bbp_get_dynamic_roles() ) as $bbp_role ) {
 519          remove_role( $bbp_role );
 520      }
 521  
 522      // Some early adopters may have a deprecated visitor role. It was later
 523      // replaced by the Spectator role.
 524      remove_role( 'bbp_visitor' );
 525  }