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