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

https://bitbucket.org/skyarch-iijima/wordpress · 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. * Core class used to implement a user roles API.
  11. *
  12. * The role option is simple, the structure is organized by role name that store
  13. * the name in value of the 'name' key. The capabilities are stored as an array
  14. * in the value of the 'capability' key.
  15. *
  16. * array (
  17. * 'rolename' => array (
  18. * 'name' => 'rolename',
  19. * 'capabilities' => array()
  20. * )
  21. * )
  22. *
  23. * @since 2.0.0
  24. */
  25. class WP_Roles {
  26. /**
  27. * List of roles and capabilities.
  28. *
  29. * @since 2.0.0
  30. * @var array
  31. */
  32. public $roles;
  33. /**
  34. * List of the role objects.
  35. *
  36. * @since 2.0.0
  37. * @var array
  38. */
  39. public $role_objects = array();
  40. /**
  41. * List of role names.
  42. *
  43. * @since 2.0.0
  44. * @var array
  45. */
  46. public $role_names = array();
  47. /**
  48. * Option name for storing role list.
  49. *
  50. * @since 2.0.0
  51. * @var string
  52. */
  53. public $role_key;
  54. /**
  55. * Whether to use the database for retrieval and storage.
  56. *
  57. * @since 2.1.0
  58. * @var bool
  59. */
  60. public $use_db = true;
  61. /**
  62. * The site ID the roles are initialized for.
  63. *
  64. * @since 4.9.0
  65. * @var int
  66. */
  67. protected $site_id = 0;
  68. /**
  69. * Constructor
  70. *
  71. * @since 2.0.0
  72. * @since 4.9.0 The $site_id argument was added.
  73. *
  74. * @global array $wp_user_roles Used to set the 'roles' property value.
  75. *
  76. * @param int $site_id Site ID to initialize roles for. Default is the current site.
  77. */
  78. public function __construct( $site_id = null ) {
  79. global $wp_user_roles;
  80. $this->use_db = empty( $wp_user_roles );
  81. $this->for_site( $site_id );
  82. }
  83. /**
  84. * Make private/protected methods readable for backward compatibility.
  85. *
  86. * @since 4.0.0
  87. *
  88. * @param callable $name Method to call.
  89. * @param array $arguments Arguments to pass when calling.
  90. * @return mixed|false Return value of the callback, false otherwise.
  91. */
  92. public function __call( $name, $arguments ) {
  93. if ( '_init' === $name ) {
  94. return call_user_func_array( array( $this, $name ), $arguments );
  95. }
  96. return false;
  97. }
  98. /**
  99. * Set up the object properties.
  100. *
  101. * The role key is set to the current prefix for the $wpdb object with
  102. * 'user_roles' appended. If the $wp_user_roles global is set, then it will
  103. * be used and the role option will not be updated or used.
  104. *
  105. * @since 2.1.0
  106. * @deprecated 4.9.0 Use WP_Roles::for_site()
  107. */
  108. protected function _init() {
  109. _deprecated_function( __METHOD__, '4.9.0', 'WP_Roles::for_site()' );
  110. $this->for_site();
  111. }
  112. /**
  113. * Reinitialize the object
  114. *
  115. * Recreates the role objects. This is typically called only by switch_to_blog()
  116. * after switching wpdb to a new site ID.
  117. *
  118. * @since 3.5.0
  119. * @deprecated 4.7.0 Use WP_Roles::for_site()
  120. */
  121. public function reinit() {
  122. _deprecated_function( __METHOD__, '4.7.0', 'WP_Roles::for_site()' );
  123. $this->for_site();
  124. }
  125. /**
  126. * Add role name with capabilities to list.
  127. *
  128. * Updates the list of roles, if the role doesn't already exist.
  129. *
  130. * The capabilities are defined in the following format `array( 'read' => true );`
  131. * To explicitly deny a role a capability you set the value for that capability to false.
  132. *
  133. * @since 2.0.0
  134. *
  135. * @param string $role Role name.
  136. * @param string $display_name Role display name.
  137. * @param array $capabilities List of role capabilities in the above format.
  138. * @return WP_Role|void WP_Role object, if role is added.
  139. */
  140. public function add_role( $role, $display_name, $capabilities = array() ) {
  141. if ( empty( $role ) || isset( $this->roles[ $role ] ) ) {
  142. return;
  143. }
  144. $this->roles[$role] = array(
  145. 'name' => $display_name,
  146. 'capabilities' => $capabilities
  147. );
  148. if ( $this->use_db )
  149. update_option( $this->role_key, $this->roles );
  150. $this->role_objects[$role] = new WP_Role( $role, $capabilities );
  151. $this->role_names[$role] = $display_name;
  152. return $this->role_objects[$role];
  153. }
  154. /**
  155. * Remove role by name.
  156. *
  157. * @since 2.0.0
  158. *
  159. * @param string $role Role name.
  160. */
  161. public function remove_role( $role ) {
  162. if ( ! isset( $this->role_objects[$role] ) )
  163. return;
  164. unset( $this->role_objects[$role] );
  165. unset( $this->role_names[$role] );
  166. unset( $this->roles[$role] );
  167. if ( $this->use_db )
  168. update_option( $this->role_key, $this->roles );
  169. if ( get_option( 'default_role' ) == $role )
  170. update_option( 'default_role', 'subscriber' );
  171. }
  172. /**
  173. * Add capability to role.
  174. *
  175. * @since 2.0.0
  176. *
  177. * @param string $role Role name.
  178. * @param string $cap Capability name.
  179. * @param bool $grant Optional, default is true. Whether role is capable of performing capability.
  180. */
  181. public function add_cap( $role, $cap, $grant = true ) {
  182. if ( ! isset( $this->roles[$role] ) )
  183. return;
  184. $this->roles[$role]['capabilities'][$cap] = $grant;
  185. if ( $this->use_db )
  186. update_option( $this->role_key, $this->roles );
  187. }
  188. /**
  189. * Remove capability from role.
  190. *
  191. * @since 2.0.0
  192. *
  193. * @param string $role Role name.
  194. * @param string $cap Capability name.
  195. */
  196. public function remove_cap( $role, $cap ) {
  197. if ( ! isset( $this->roles[$role] ) )
  198. return;
  199. unset( $this->roles[$role]['capabilities'][$cap] );
  200. if ( $this->use_db )
  201. update_option( $this->role_key, $this->roles );
  202. }
  203. /**
  204. * Retrieve role object by name.
  205. *
  206. * @since 2.0.0
  207. *
  208. * @param string $role Role name.
  209. * @return WP_Role|null WP_Role object if found, null if the role does not exist.
  210. */
  211. public function get_role( $role ) {
  212. if ( isset( $this->role_objects[$role] ) )
  213. return $this->role_objects[$role];
  214. else
  215. return null;
  216. }
  217. /**
  218. * Retrieve list of role names.
  219. *
  220. * @since 2.0.0
  221. *
  222. * @return array List of role names.
  223. */
  224. public function get_names() {
  225. return $this->role_names;
  226. }
  227. /**
  228. * Whether role name is currently in the list of available roles.
  229. *
  230. * @since 2.0.0
  231. *
  232. * @param string $role Role name to look up.
  233. * @return bool
  234. */
  235. public function is_role( $role ) {
  236. return isset( $this->role_names[$role] );
  237. }
  238. /**
  239. * Initializes all of the available roles.
  240. *
  241. * @since 4.9.0
  242. */
  243. public function init_roles() {
  244. if ( empty( $this->roles ) ) {
  245. return;
  246. }
  247. $this->role_objects = array();
  248. $this->role_names = array();
  249. foreach ( array_keys( $this->roles ) as $role ) {
  250. $this->role_objects[ $role ] = new WP_Role( $role, $this->roles[ $role ]['capabilities'] );
  251. $this->role_names[ $role ] = $this->roles[ $role ]['name'];
  252. }
  253. /**
  254. * After the roles have been initialized, allow plugins to add their own roles.
  255. *
  256. * @since 4.7.0
  257. *
  258. * @param WP_Roles $this A reference to the WP_Roles object.
  259. */
  260. do_action( 'wp_roles_init', $this );
  261. }
  262. /**
  263. * Sets the site to operate on. Defaults to the current site.
  264. *
  265. * @since 4.9.0
  266. *
  267. * @global wpdb $wpdb WordPress database abstraction object.
  268. *
  269. * @param int $site_id Site ID to initialize roles for. Default is the current site.
  270. */
  271. public function for_site( $site_id = null ) {
  272. global $wpdb;
  273. if ( ! empty( $site_id ) ) {
  274. $this->site_id = absint( $site_id );
  275. } else {
  276. $this->site_id = get_current_blog_id();
  277. }
  278. $this->role_key = $wpdb->get_blog_prefix( $this->site_id ) . 'user_roles';
  279. if ( ! empty( $this->roles ) && ! $this->use_db ) {
  280. return;
  281. }
  282. $this->roles = $this->get_roles_data();
  283. $this->init_roles();
  284. }
  285. /**
  286. * Gets the ID of the site for which roles are currently initialized.
  287. *
  288. * @since 4.9.0
  289. *
  290. * @return int Site ID.
  291. */
  292. public function get_site_id() {
  293. return $this->site_id;
  294. }
  295. /**
  296. * Gets the available roles data.
  297. *
  298. * @since 4.9.0
  299. *
  300. * @global array $wp_user_roles Used to set the 'roles' property value.
  301. *
  302. * @return array Roles array.
  303. */
  304. protected function get_roles_data() {
  305. global $wp_user_roles;
  306. if ( ! empty( $wp_user_roles ) ) {
  307. return $wp_user_roles;
  308. }
  309. if ( is_multisite() && $this->site_id != get_current_blog_id() ) {
  310. remove_action( 'switch_blog', 'wp_switch_roles_and_user', 1 );
  311. $roles = get_blog_option( $this->site_id, $this->role_key, array() );
  312. add_action( 'switch_blog', 'wp_switch_roles_and_user', 1, 2 );
  313. return $roles;
  314. }
  315. return get_option( $this->role_key, array() );
  316. }
  317. }