WP_Roles

Core class used to implement a user roles API.

Defined (1)

The class is defined in the following location(s).

/wp-includes/class-wp-roles.php  
  1. class WP_Roles { 
  2. /** 
  3. * List of roles and capabilities. 
  4. * @since 2.0.0 
  5. * @access public 
  6. * @var array 
  7. */ 
  8. public $roles; 
  9.  
  10. /** 
  11. * List of the role objects. 
  12. * @since 2.0.0 
  13. * @access public 
  14. * @var array 
  15. */ 
  16. public $role_objects = array(); 
  17.  
  18. /** 
  19. * List of role names. 
  20. * @since 2.0.0 
  21. * @access public 
  22. * @var array 
  23. */ 
  24. public $role_names = array(); 
  25.  
  26. /** 
  27. * Option name for storing role list. 
  28. * @since 2.0.0 
  29. * @access public 
  30. * @var string 
  31. */ 
  32. public $role_key; 
  33.  
  34. /** 
  35. * Whether to use the database for retrieval and storage. 
  36. * @since 2.1.0 
  37. * @access public 
  38. * @var bool 
  39. */ 
  40. public $use_db = true; 
  41.  
  42. /** 
  43. * Constructor 
  44. * @since 2.0.0 
  45. */ 
  46. public function __construct() { 
  47. $this->_init(); 
  48.  
  49. /** 
  50. * Make private/protected methods readable for backward compatibility. 
  51. * @since 4.0.0 
  52. * @access public 
  53. * @param callable $name Method to call. 
  54. * @param array $arguments Arguments to pass when calling. 
  55. * @return mixed|false Return value of the callback, false otherwise. 
  56. */ 
  57. public function __call( $name, $arguments ) { 
  58. if ( '_init' === $name ) { 
  59. return call_user_func_array( array( $this, $name ), $arguments ); 
  60. return false; 
  61.  
  62. /** 
  63. * Set up the object properties. 
  64. * The role key is set to the current prefix for the $wpdb object with 
  65. * 'user_roles' appended. If the $wp_user_roles global is set, then it will 
  66. * be used and the role option will not be updated or used. 
  67. * @since 2.1.0 
  68. * @access protected 
  69. * @global array $wp_user_roles Used to set the 'roles' property value. 
  70. */ 
  71. protected function _init() { 
  72. global $wp_user_roles, $wpdb; 
  73.  
  74. $this->role_key = $wpdb->get_blog_prefix() . 'user_roles'; 
  75. if ( ! empty( $wp_user_roles ) ) { 
  76. $this->roles = $wp_user_roles; 
  77. $this->use_db = false; 
  78. } else { 
  79. $this->roles = get_option( $this->role_key ); 
  80.  
  81. if ( empty( $this->roles ) ) 
  82. return; 
  83.  
  84. $this->role_objects = array(); 
  85. $this->role_names = array(); 
  86. foreach ( array_keys( $this->roles ) as $role ) { 
  87. $this->role_objects[$role] = new WP_Role( $role, $this->roles[$role]['capabilities'] ); 
  88. $this->role_names[$role] = $this->roles[$role]['name']; 
  89.  
  90. /** 
  91. * After the roles have been initialized, allow plugins to add their own roles. 
  92. * @since 4.7.0 
  93. * @param WP_Roles $this A reference to the WP_Roles object. 
  94. */ 
  95. do_action( 'wp_roles_init', $this ); 
  96.  
  97. /** 
  98. * Reinitialize the object 
  99. * Recreates the role objects. This is typically called only by switch_to_blog() 
  100. * after switching wpdb to a new site ID. 
  101. * @since 3.5.0 
  102. * @deprecated 4.7.0 Use new WP_Roles() 
  103. * @access public 
  104. */ 
  105. public function reinit() { 
  106. _deprecated_function( __METHOD__, '4.7.0', 'new WP_Roles()' ); 
  107. $this->_init(); 
  108.  
  109. /** 
  110. * Add role name with capabilities to list. 
  111. * Updates the list of roles, if the role doesn't already exist. 
  112. * The capabilities are defined in the following format `array( 'read' => true );` 
  113. * To explicitly deny a role a capability you set the value for that capability to false. 
  114. * @since 2.0.0 
  115. * @access public 
  116. * @param string $role Role name. 
  117. * @param string $display_name Role display name. 
  118. * @param array $capabilities List of role capabilities in the above format. 
  119. * @return WP_Role|void WP_Role object, if role is added. 
  120. */ 
  121. public function add_role( $role, $display_name, $capabilities = array() ) { 
  122. if ( empty( $role ) || isset( $this->roles[ $role ] ) ) { 
  123. return; 
  124.  
  125. $this->roles[$role] = array( 
  126. 'name' => $display_name,  
  127. 'capabilities' => $capabilities 
  128. ); 
  129. if ( $this->use_db ) 
  130. update_option( $this->role_key, $this->roles ); 
  131. $this->role_objects[$role] = new WP_Role( $role, $capabilities ); 
  132. $this->role_names[$role] = $display_name; 
  133. return $this->role_objects[$role]; 
  134.  
  135. /** 
  136. * Remove role by name. 
  137. * @since 2.0.0 
  138. * @access public 
  139. * @param string $role Role name. 
  140. */ 
  141. public function remove_role( $role ) { 
  142. if ( ! isset( $this->role_objects[$role] ) ) 
  143. return; 
  144.  
  145. unset( $this->role_objects[$role] ); 
  146. unset( $this->role_names[$role] ); 
  147. unset( $this->roles[$role] ); 
  148.  
  149. if ( $this->use_db ) 
  150. update_option( $this->role_key, $this->roles ); 
  151.  
  152. if ( get_option( 'default_role' ) == $role ) 
  153. update_option( 'default_role', 'subscriber' ); 
  154.  
  155. /** 
  156. * Add capability to role. 
  157. * @since 2.0.0 
  158. * @access public 
  159. * @param string $role Role name. 
  160. * @param string $cap Capability name. 
  161. * @param bool $grant Optional, default is true. Whether role is capable of performing capability. 
  162. */ 
  163. public function add_cap( $role, $cap, $grant = true ) { 
  164. if ( ! isset( $this->roles[$role] ) ) 
  165. return; 
  166.  
  167. $this->roles[$role]['capabilities'][$cap] = $grant; 
  168. if ( $this->use_db ) 
  169. update_option( $this->role_key, $this->roles ); 
  170.  
  171. /** 
  172. * Remove capability from role. 
  173. * @since 2.0.0 
  174. * @access public 
  175. * @param string $role Role name. 
  176. * @param string $cap Capability name. 
  177. */ 
  178. public function remove_cap( $role, $cap ) { 
  179. if ( ! isset( $this->roles[$role] ) ) 
  180. return; 
  181.  
  182. unset( $this->roles[$role]['capabilities'][$cap] ); 
  183. if ( $this->use_db ) 
  184. update_option( $this->role_key, $this->roles ); 
  185.  
  186. /** 
  187. * Retrieve role object by name. 
  188. * @since 2.0.0 
  189. * @access public 
  190. * @param string $role Role name. 
  191. * @return WP_Role|null WP_Role object if found, null if the role does not exist. 
  192. */ 
  193. public function get_role( $role ) { 
  194. if ( isset( $this->role_objects[$role] ) ) 
  195. return $this->role_objects[$role]; 
  196. else 
  197. return null; 
  198.  
  199. /** 
  200. * Retrieve list of role names. 
  201. * @since 2.0.0 
  202. * @access public 
  203. * @return array List of role names. 
  204. */ 
  205. public function get_names() { 
  206. return $this->role_names; 
  207.  
  208. /** 
  209. * Whether role name is currently in the list of available roles. 
  210. * @since 2.0.0 
  211. * @access public 
  212. * @param string $role Role name to look up. 
  213. * @return bool 
  214. */ 
  215. public function is_role( $role ) { 
  216. return isset( $this->role_names[$role] );