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 wpdb $wpdb WordPress database abstraction object. 
  70. * @global array $wp_user_roles Used to set the 'roles' property value. 
  71. */ 
  72. protected function _init() { 
  73. global $wpdb, $wp_user_roles; 
  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. * Reinitialize the object 
  92. * Recreates the role objects. This is typically called only by switch_to_blog() 
  93. * after switching wpdb to a new site ID. 
  94. * @since 3.5.0 
  95. * @access public 
  96. * @global wpdb $wpdb WordPress database abstraction object. 
  97. */ 
  98. public function reinit() { 
  99. // There is no need to reinit if using the wp_user_roles global. 
  100. if ( ! $this->use_db ) 
  101. return; 
  102.  
  103. global $wpdb; 
  104.  
  105. // Duplicated from _init() to avoid an extra function call. 
  106. $this->role_key = $wpdb->get_blog_prefix() . 'user_roles'; 
  107. $this->roles = get_option( $this->role_key ); 
  108. if ( empty( $this->roles ) ) 
  109. return; 
  110.  
  111. $this->role_objects = array(); 
  112. $this->role_names = array(); 
  113. foreach ( array_keys( $this->roles ) as $role ) { 
  114. $this->role_objects[$role] = new WP_Role( $role, $this->roles[$role]['capabilities'] ); 
  115. $this->role_names[$role] = $this->roles[$role]['name']; 
  116.  
  117. /** 
  118. * Add role name with capabilities to list. 
  119. * Updates the list of roles, if the role doesn't already exist. 
  120. * The capabilities are defined in the following format `array( 'read' => true );` 
  121. * To explicitly deny a role a capability you set the value for that capability to false. 
  122. * @since 2.0.0 
  123. * @access public 
  124. * @param string $role Role name. 
  125. * @param string $display_name Role display name. 
  126. * @param array $capabilities List of role capabilities in the above format. 
  127. * @return WP_Role|void WP_Role object, if role is added. 
  128. */ 
  129. public function add_role( $role, $display_name, $capabilities = array() ) { 
  130. if ( empty( $role ) || isset( $this->roles[ $role ] ) ) { 
  131. return; 
  132.  
  133. $this->roles[$role] = array( 
  134. 'name' => $display_name,  
  135. 'capabilities' => $capabilities 
  136. ); 
  137. if ( $this->use_db ) 
  138. update_option( $this->role_key, $this->roles ); 
  139. $this->role_objects[$role] = new WP_Role( $role, $capabilities ); 
  140. $this->role_names[$role] = $display_name; 
  141. return $this->role_objects[$role]; 
  142.  
  143. /** 
  144. * Remove role by name. 
  145. * @since 2.0.0 
  146. * @access public 
  147. * @param string $role Role name. 
  148. */ 
  149. public function remove_role( $role ) { 
  150. if ( ! isset( $this->role_objects[$role] ) ) 
  151. return; 
  152.  
  153. unset( $this->role_objects[$role] ); 
  154. unset( $this->role_names[$role] ); 
  155. unset( $this->roles[$role] ); 
  156.  
  157. if ( $this->use_db ) 
  158. update_option( $this->role_key, $this->roles ); 
  159.  
  160. if ( get_option( 'default_role' ) == $role ) 
  161. update_option( 'default_role', 'subscriber' ); 
  162.  
  163. /** 
  164. * Add capability to role. 
  165. * @since 2.0.0 
  166. * @access public 
  167. * @param string $role Role name. 
  168. * @param string $cap Capability name. 
  169. * @param bool $grant Optional, default is true. Whether role is capable of performing capability. 
  170. */ 
  171. public function add_cap( $role, $cap, $grant = true ) { 
  172. if ( ! isset( $this->roles[$role] ) ) 
  173. return; 
  174.  
  175. $this->roles[$role]['capabilities'][$cap] = $grant; 
  176. if ( $this->use_db ) 
  177. update_option( $this->role_key, $this->roles ); 
  178.  
  179. /** 
  180. * Remove capability from role. 
  181. * @since 2.0.0 
  182. * @access public 
  183. * @param string $role Role name. 
  184. * @param string $cap Capability name. 
  185. */ 
  186. public function remove_cap( $role, $cap ) { 
  187. if ( ! isset( $this->roles[$role] ) ) 
  188. return; 
  189.  
  190. unset( $this->roles[$role]['capabilities'][$cap] ); 
  191. if ( $this->use_db ) 
  192. update_option( $this->role_key, $this->roles ); 
  193.  
  194. /** 
  195. * Retrieve role object by name. 
  196. * @since 2.0.0 
  197. * @access public 
  198. * @param string $role Role name. 
  199. * @return WP_Role|null WP_Role object if found, null if the role does not exist. 
  200. */ 
  201. public function get_role( $role ) { 
  202. if ( isset( $this->role_objects[$role] ) ) 
  203. return $this->role_objects[$role]; 
  204. else 
  205. return null; 
  206.  
  207. /** 
  208. * Retrieve list of role names. 
  209. * @since 2.0.0 
  210. * @access public 
  211. * @return array List of role names. 
  212. */ 
  213. public function get_names() { 
  214. return $this->role_names; 
  215.  
  216. /** 
  217. * Whether role name is currently in the list of available roles. 
  218. * @since 2.0.0 
  219. * @access public 
  220. * @param string $role Role name to look up. 
  221. * @return bool 
  222. */ 
  223. public function is_role( $role ) { 
  224. return isset( $this->role_names[$role] );