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