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