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