/wp-includes/class-wp-roles.php

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