[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * User API: WP_Roles class
   4   *
   5   * @package WordPress
   6   * @subpackage Users
   7   * @since 4.4.0
   8   */
   9  
  10  /**
  11   * Core class used to implement a user roles API.
  12   *
  13   * The role option is simple, the structure is organized by role name that store
  14   * the name in value of the 'name' key. The capabilities are stored as an array
  15   * in the value of the 'capability' key.
  16   *
  17   *     array (
  18   *          'rolename' => array (
  19   *              'name' => 'rolename',
  20   *              'capabilities' => array()
  21   *          )
  22   *     )
  23   *
  24   * @since 2.0.0
  25   */
  26  class WP_Roles {
  27      /**
  28       * List of roles and capabilities.
  29       *
  30       * @since 2.0.0
  31       * @var array[]
  32       */
  33      public $roles;
  34  
  35      /**
  36       * List of the role objects.
  37       *
  38       * @since 2.0.0
  39       * @var WP_Role[]
  40       */
  41      public $role_objects = array();
  42  
  43      /**
  44       * List of role names.
  45       *
  46       * @since 2.0.0
  47       * @var string[]
  48       */
  49      public $role_names = array();
  50  
  51      /**
  52       * Option name for storing role list.
  53       *
  54       * @since 2.0.0
  55       * @var string
  56       */
  57      public $role_key;
  58  
  59      /**
  60       * Whether to use the database for retrieval and storage.
  61       *
  62       * @since 2.1.0
  63       * @var bool
  64       */
  65      public $use_db = true;
  66  
  67      /**
  68       * The site ID the roles are initialized for.
  69       *
  70       * @since 4.9.0
  71       * @var int
  72       */
  73      protected $site_id = 0;
  74  
  75      /**
  76       * Constructor
  77       *
  78       * @since 2.0.0
  79       * @since 4.9.0 The `$site_id` argument was added.
  80       *
  81       * @global array $wp_user_roles Used to set the 'roles' property value.
  82       *
  83       * @param int $site_id Site ID to initialize roles for. Default is the current site.
  84       */
  85  	public function __construct( $site_id = null ) {
  86          global $wp_user_roles;
  87  
  88          $this->use_db = empty( $wp_user_roles );
  89  
  90          $this->for_site( $site_id );
  91      }
  92  
  93      /**
  94       * Make private/protected methods readable for backward compatibility.
  95       *
  96       * @since 4.0.0
  97       *
  98       * @param string $name      Method to call.
  99       * @param array  $arguments Arguments to pass when calling.
 100       * @return mixed|false Return value of the callback, false otherwise.
 101       */
 102  	public function __call( $name, $arguments ) {
 103          if ( '_init' === $name ) {
 104              return $this->_init( ...$arguments );
 105          }
 106          return false;
 107      }
 108  
 109      /**
 110       * Set up the object properties.
 111       *
 112       * The role key is set to the current prefix for the $wpdb object with
 113       * 'user_roles' appended. If the $wp_user_roles global is set, then it will
 114       * be used and the role option will not be updated or used.
 115       *
 116       * @since 2.1.0
 117       * @deprecated 4.9.0 Use WP_Roles::for_site()
 118       */
 119  	protected function _init() {
 120          _deprecated_function( __METHOD__, '4.9.0', 'WP_Roles::for_site()' );
 121  
 122          $this->for_site();
 123      }
 124  
 125      /**
 126       * Reinitialize the object
 127       *
 128       * Recreates the role objects. This is typically called only by switch_to_blog()
 129       * after switching wpdb to a new site ID.
 130       *
 131       * @since 3.5.0
 132       * @deprecated 4.7.0 Use WP_Roles::for_site()
 133       */
 134  	public function reinit() {
 135          _deprecated_function( __METHOD__, '4.7.0', 'WP_Roles::for_site()' );
 136  
 137          $this->for_site();
 138      }
 139  
 140      /**
 141       * Add role name with capabilities to list.
 142       *
 143       * Updates the list of roles, if the role doesn't already exist.
 144       *
 145       * The capabilities are defined in the following format `array( 'read' => true );`
 146       * To explicitly deny a role a capability you set the value for that capability to false.
 147       *
 148       * @since 2.0.0
 149       *
 150       * @param string $role         Role name.
 151       * @param string $display_name Role display name.
 152       * @param bool[] $capabilities List of capabilities keyed by the capability name,
 153       *                             e.g. array( 'edit_posts' => true, 'delete_posts' => false ).
 154       * @return WP_Role|void WP_Role object, if role is added.
 155       */
 156  	public function add_role( $role, $display_name, $capabilities = array() ) {
 157          if ( empty( $role ) || isset( $this->roles[ $role ] ) ) {
 158              return;
 159          }
 160  
 161          $this->roles[ $role ] = array(
 162              'name'         => $display_name,
 163              'capabilities' => $capabilities,
 164          );
 165          if ( $this->use_db ) {
 166              update_option( $this->role_key, $this->roles );
 167          }
 168          $this->role_objects[ $role ] = new WP_Role( $role, $capabilities );
 169          $this->role_names[ $role ]   = $display_name;
 170          return $this->role_objects[ $role ];
 171      }
 172  
 173      /**
 174       * Remove role by name.
 175       *
 176       * @since 2.0.0
 177       *
 178       * @param string $role Role name.
 179       */
 180  	public function remove_role( $role ) {
 181          if ( ! isset( $this->role_objects[ $role ] ) ) {
 182              return;
 183          }
 184  
 185          unset( $this->role_objects[ $role ] );
 186          unset( $this->role_names[ $role ] );
 187          unset( $this->roles[ $role ] );
 188  
 189          if ( $this->use_db ) {
 190              update_option( $this->role_key, $this->roles );
 191          }
 192  
 193          if ( get_option( 'default_role' ) == $role ) {
 194              update_option( 'default_role', 'subscriber' );
 195          }
 196      }
 197  
 198      /**
 199       * Add capability to role.
 200       *
 201       * @since 2.0.0
 202       *
 203       * @param string $role  Role name.
 204       * @param string $cap   Capability name.
 205       * @param bool   $grant Optional. Whether role is capable of performing capability.
 206       *                      Default true.
 207       */
 208  	public function add_cap( $role, $cap, $grant = true ) {
 209          if ( ! isset( $this->roles[ $role ] ) ) {
 210              return;
 211          }
 212  
 213          $this->roles[ $role ]['capabilities'][ $cap ] = $grant;
 214          if ( $this->use_db ) {
 215              update_option( $this->role_key, $this->roles );
 216          }
 217      }
 218  
 219      /**
 220       * Remove capability from role.
 221       *
 222       * @since 2.0.0
 223       *
 224       * @param string $role Role name.
 225       * @param string $cap  Capability name.
 226       */
 227  	public function remove_cap( $role, $cap ) {
 228          if ( ! isset( $this->roles[ $role ] ) ) {
 229              return;
 230          }
 231  
 232          unset( $this->roles[ $role ]['capabilities'][ $cap ] );
 233          if ( $this->use_db ) {
 234              update_option( $this->role_key, $this->roles );
 235          }
 236      }
 237  
 238      /**
 239       * Retrieve role object by name.
 240       *
 241       * @since 2.0.0
 242       *
 243       * @param string $role Role name.
 244       * @return WP_Role|null WP_Role object if found, null if the role does not exist.
 245       */
 246  	public function get_role( $role ) {
 247          if ( isset( $this->role_objects[ $role ] ) ) {
 248              return $this->role_objects[ $role ];
 249          } else {
 250              return null;
 251          }
 252      }
 253  
 254      /**
 255       * Retrieve list of role names.
 256       *
 257       * @since 2.0.0
 258       *
 259       * @return string[] List of role names.
 260       */
 261  	public function get_names() {
 262          return $this->role_names;
 263      }
 264  
 265      /**
 266       * Whether role name is currently in the list of available roles.
 267       *
 268       * @since 2.0.0
 269       *
 270       * @param string $role Role name to look up.
 271       * @return bool
 272       */
 273  	public function is_role( $role ) {
 274          return isset( $this->role_names[ $role ] );
 275      }
 276  
 277      /**
 278       * Initializes all of the available roles.
 279       *
 280       * @since 4.9.0
 281       */
 282  	public function init_roles() {
 283          if ( empty( $this->roles ) ) {
 284              return;
 285          }
 286  
 287          $this->role_objects = array();
 288          $this->role_names   = array();
 289          foreach ( array_keys( $this->roles ) as $role ) {
 290              $this->role_objects[ $role ] = new WP_Role( $role, $this->roles[ $role ]['capabilities'] );
 291              $this->role_names[ $role ]   = $this->roles[ $role ]['name'];
 292          }
 293  
 294          /**
 295           * After the roles have been initialized, allow plugins to add their own roles.
 296           *
 297           * @since 4.7.0
 298           *
 299           * @param WP_Roles $wp_roles A reference to the WP_Roles object.
 300           */
 301          do_action( 'wp_roles_init', $this );
 302      }
 303  
 304      /**
 305       * Sets the site to operate on. Defaults to the current site.
 306       *
 307       * @since 4.9.0
 308       *
 309       * @global wpdb $wpdb WordPress database abstraction object.
 310       *
 311       * @param int $site_id Site ID to initialize roles for. Default is the current site.
 312       */
 313  	public function for_site( $site_id = null ) {
 314          global $wpdb;
 315  
 316          if ( ! empty( $site_id ) ) {
 317              $this->site_id = absint( $site_id );
 318          } else {
 319              $this->site_id = get_current_blog_id();
 320          }
 321  
 322          $this->role_key = $wpdb->get_blog_prefix( $this->site_id ) . 'user_roles';
 323  
 324          if ( ! empty( $this->roles ) && ! $this->use_db ) {
 325              return;
 326          }
 327  
 328          $this->roles = $this->get_roles_data();
 329  
 330          $this->init_roles();
 331      }
 332  
 333      /**
 334       * Gets the ID of the site for which roles are currently initialized.
 335       *
 336       * @since 4.9.0
 337       *
 338       * @return int Site ID.
 339       */
 340  	public function get_site_id() {
 341          return $this->site_id;
 342      }
 343  
 344      /**
 345       * Gets the available roles data.
 346       *
 347       * @since 4.9.0
 348       *
 349       * @global array $wp_user_roles Used to set the 'roles' property value.
 350       *
 351       * @return array Roles array.
 352       */
 353  	protected function get_roles_data() {
 354          global $wp_user_roles;
 355  
 356          if ( ! empty( $wp_user_roles ) ) {
 357              return $wp_user_roles;
 358          }
 359  
 360          if ( is_multisite() && get_current_blog_id() != $this->site_id ) {
 361              remove_action( 'switch_blog', 'wp_switch_roles_and_user', 1 );
 362  
 363              $roles = get_blog_option( $this->site_id, $this->role_key, array() );
 364  
 365              add_action( 'switch_blog', 'wp_switch_roles_and_user', 1, 2 );
 366  
 367              return $roles;
 368          }
 369  
 370          return get_option( $this->role_key, array() );
 371      }
 372  }