[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 array $capabilities List of role capabilities in the above format.
 153       * @return WP_Role|void WP_Role object, if role is added.
 154       */
 155  	public function add_role( $role, $display_name, $capabilities = array() ) {
 156          if ( empty( $role ) || isset( $this->roles[ $role ] ) ) {
 157              return;
 158          }
 159  
 160          $this->roles[ $role ] = array(
 161              'name'         => $display_name,
 162              'capabilities' => $capabilities,
 163          );
 164          if ( $this->use_db ) {
 165              update_option( $this->role_key, $this->roles );
 166          }
 167          $this->role_objects[ $role ] = new WP_Role( $role, $capabilities );
 168          $this->role_names[ $role ]   = $display_name;
 169          return $this->role_objects[ $role ];
 170      }
 171  
 172      /**
 173       * Remove role by name.
 174       *
 175       * @since 2.0.0
 176       *
 177       * @param string $role Role name.
 178       */
 179  	public function remove_role( $role ) {
 180          if ( ! isset( $this->role_objects[ $role ] ) ) {
 181              return;
 182          }
 183  
 184          unset( $this->role_objects[ $role ] );
 185          unset( $this->role_names[ $role ] );
 186          unset( $this->roles[ $role ] );
 187  
 188          if ( $this->use_db ) {
 189              update_option( $this->role_key, $this->roles );
 190          }
 191  
 192          if ( get_option( 'default_role' ) == $role ) {
 193              update_option( 'default_role', 'subscriber' );
 194          }
 195      }
 196  
 197      /**
 198       * Add capability to role.
 199       *
 200       * @since 2.0.0
 201       *
 202       * @param string $role Role name.
 203       * @param string $cap Capability name.
 204       * @param bool $grant Optional, default is true. Whether role is capable of performing capability.
 205       */
 206  	public function add_cap( $role, $cap, $grant = true ) {
 207          if ( ! isset( $this->roles[ $role ] ) ) {
 208              return;
 209          }
 210  
 211          $this->roles[ $role ]['capabilities'][ $cap ] = $grant;
 212          if ( $this->use_db ) {
 213              update_option( $this->role_key, $this->roles );
 214          }
 215      }
 216  
 217      /**
 218       * Remove capability from role.
 219       *
 220       * @since 2.0.0
 221       *
 222       * @param string $role Role name.
 223       * @param string $cap Capability name.
 224       */
 225  	public function remove_cap( $role, $cap ) {
 226          if ( ! isset( $this->roles[ $role ] ) ) {
 227              return;
 228          }
 229  
 230          unset( $this->roles[ $role ]['capabilities'][ $cap ] );
 231          if ( $this->use_db ) {
 232              update_option( $this->role_key, $this->roles );
 233          }
 234      }
 235  
 236      /**
 237       * Retrieve role object by name.
 238       *
 239       * @since 2.0.0
 240       *
 241       * @param string $role Role name.
 242       * @return WP_Role|null WP_Role object if found, null if the role does not exist.
 243       */
 244  	public function get_role( $role ) {
 245          if ( isset( $this->role_objects[ $role ] ) ) {
 246              return $this->role_objects[ $role ];
 247          } else {
 248              return null;
 249          }
 250      }
 251  
 252      /**
 253       * Retrieve list of role names.
 254       *
 255       * @since 2.0.0
 256       *
 257       * @return string[] List of role names.
 258       */
 259  	public function get_names() {
 260          return $this->role_names;
 261      }
 262  
 263      /**
 264       * Whether role name is currently in the list of available roles.
 265       *
 266       * @since 2.0.0
 267       *
 268       * @param string $role Role name to look up.
 269       * @return bool
 270       */
 271  	public function is_role( $role ) {
 272          return isset( $this->role_names[ $role ] );
 273      }
 274  
 275      /**
 276       * Initializes all of the available roles.
 277       *
 278       * @since 4.9.0
 279       */
 280  	public function init_roles() {
 281          if ( empty( $this->roles ) ) {
 282              return;
 283          }
 284  
 285          $this->role_objects = array();
 286          $this->role_names   = array();
 287          foreach ( array_keys( $this->roles ) as $role ) {
 288              $this->role_objects[ $role ] = new WP_Role( $role, $this->roles[ $role ]['capabilities'] );
 289              $this->role_names[ $role ]   = $this->roles[ $role ]['name'];
 290          }
 291  
 292          /**
 293           * After the roles have been initialized, allow plugins to add their own roles.
 294           *
 295           * @since 4.7.0
 296           *
 297           * @param WP_Roles $this A reference to the WP_Roles object.
 298           */
 299          do_action( 'wp_roles_init', $this );
 300      }
 301  
 302      /**
 303       * Sets the site to operate on. Defaults to the current site.
 304       *
 305       * @since 4.9.0
 306       *
 307       * @global wpdb $wpdb WordPress database abstraction object.
 308       *
 309       * @param int $site_id Site ID to initialize roles for. Default is the current site.
 310       */
 311  	public function for_site( $site_id = null ) {
 312          global $wpdb;
 313  
 314          if ( ! empty( $site_id ) ) {
 315              $this->site_id = absint( $site_id );
 316          } else {
 317              $this->site_id = get_current_blog_id();
 318          }
 319  
 320          $this->role_key = $wpdb->get_blog_prefix( $this->site_id ) . 'user_roles';
 321  
 322          if ( ! empty( $this->roles ) && ! $this->use_db ) {
 323              return;
 324          }
 325  
 326          $this->roles = $this->get_roles_data();
 327  
 328          $this->init_roles();
 329      }
 330  
 331      /**
 332       * Gets the ID of the site for which roles are currently initialized.
 333       *
 334       * @since 4.9.0
 335       *
 336       * @return int Site ID.
 337       */
 338  	public function get_site_id() {
 339          return $this->site_id;
 340      }
 341  
 342      /**
 343       * Gets the available roles data.
 344       *
 345       * @since 4.9.0
 346       *
 347       * @global array $wp_user_roles Used to set the 'roles' property value.
 348       *
 349       * @return array Roles array.
 350       */
 351  	protected function get_roles_data() {
 352          global $wp_user_roles;
 353  
 354          if ( ! empty( $wp_user_roles ) ) {
 355              return $wp_user_roles;
 356          }
 357  
 358          if ( is_multisite() && $this->site_id != get_current_blog_id() ) {
 359              remove_action( 'switch_blog', 'wp_switch_roles_and_user', 1 );
 360  
 361              $roles = get_blog_option( $this->site_id, $this->role_key, array() );
 362  
 363              add_action( 'switch_blog', 'wp_switch_roles_and_user', 1, 2 );
 364  
 365              return $roles;
 366          }
 367  
 368          return get_option( $this->role_key, array() );
 369      }
 370  }