bbpress / includes / core / capabilities.php

capabilities.php in bbPress trunk, at includes/core/capabilities.php

536 lines 13.4 KB

Raw Download Zip

1	<?php
2
3	/**
4	* bbPress Capabilities.
5	*
6	* The functions in this file are used primarily as convenient wrappers for
7	* capability output in user profiles. This includes mapping capabilities and
8	* groups to human readable strings,
9	*
10	* @package bbPress
11	* @subpackage Capabilities
12	*/
13
14	// Exit if accessed directly
15	defined( 'ABSPATH' ) \|\| exit;
16
17	/ Mapping *****************************************************************/
18
19	/**
20	* Returns an array of capabilities based on the role that is being requested.
21	*
22	* @since 2.0.0 bbPress (r2994)
23	*
24	* @todo Map all of these and deprecate.
25	*
26	* @param string $role Optional. Defaults to The role to load caps for.
27	*
28	* @return array Capabilities for $role.
29	*/
30	function bbp_get_caps_for_role( $role = '' ) {
31
32	// Which role are we looking for?
33	switch ( $role ) {
34
35	// Keymaster
36	case bbp_get_keymaster_role() :
37	$caps = array(
38
39	// Keymasters only
40	'keep_gate' => true,
41
42	// Primary caps
43	'spectate' => true,
44	'participate' => true,
45	'moderate' => true,
46	'throttle' => true,
47	'view_trash' => true,
48	'assign_moderators' => true,
49
50	// Forum caps
51	'publish_forums' => true,
52	'edit_forums' => true,
53	'edit_others_forums' => true,
54	'delete_forums' => true,
55	'delete_others_forums' => true,
56	'read_private_forums' => true,
57	'read_hidden_forums' => true,
58
59	// Topic caps
60	'publish_topics' => true,
61	'edit_topics' => true,
62	'edit_others_topics' => true,
63	'delete_topics' => true,
64	'delete_others_topics' => true,
65	'read_private_topics' => true,
66
67	// Reply caps
68	'publish_replies' => true,
69	'edit_replies' => true,
70	'edit_others_replies' => true,
71	'delete_replies' => true,
72	'delete_others_replies' => true,
73	'read_private_replies' => true,
74
75	// Topic tag caps
76	'manage_topic_tags' => true,
77	'edit_topic_tags' => true,
78	'delete_topic_tags' => true,
79	'assign_topic_tags' => true
80	);
81
82	break;
83
84	// Moderator
85	case bbp_get_moderator_role() :
86	$caps = array(
87
88	// Primary caps
89	'spectate' => true,
90	'participate' => true,
91	'moderate' => true,
92	'throttle' => true,
93	'view_trash' => true,
94	'assign_moderators' => true,
95
96	// Forum caps
97	'publish_forums' => true,
98	'edit_forums' => true,
99	'read_private_forums' => true,
100	'read_hidden_forums' => true,
101
102	// Topic caps
103	'publish_topics' => true,
104	'edit_topics' => true,
105	'edit_others_topics' => true,
106	'delete_topics' => true,
107	'delete_others_topics' => true,
108	'read_private_topics' => true,
109
110	// Reply caps
111	'publish_replies' => true,
112	'edit_replies' => true,
113	'edit_others_replies' => true,
114	'delete_replies' => true,
115	'delete_others_replies' => true,
116	'read_private_replies' => true,
117
118	// Topic tag caps
119	'manage_topic_tags' => true,
120	'edit_topic_tags' => true,
121	'delete_topic_tags' => true,
122	'assign_topic_tags' => true,
123	);
124
125	break;
126
127	// Spectators can only read
128	case bbp_get_spectator_role() :
129	$caps = array(
130
131	// Primary caps
132	'spectate' => true,
133	);
134
135	break;
136
137	// Explicitly blocked
138	case bbp_get_blocked_role() :
139	$caps = array(
140
141	// Primary caps
142	'spectate' => false,
143	'participate' => false,
144	'moderate' => false,
145	'throttle' => false,
146	'view_trash' => false,
147
148	// Forum caps
149	'publish_forums' => false,
150	'edit_forums' => false,
151	'edit_others_forums' => false,
152	'delete_forums' => false,
153	'delete_others_forums' => false,
154	'read_private_forums' => false,
155	'read_hidden_forums' => false,
156
157	// Topic caps
158	'publish_topics' => false,
159	'edit_topics' => false,
160	'edit_others_topics' => false,
161	'delete_topics' => false,
162	'delete_others_topics' => false,
163	'read_private_topics' => false,
164
165	// Reply caps
166	'publish_replies' => false,
167	'edit_replies' => false,
168	'edit_others_replies' => false,
169	'delete_replies' => false,
170	'delete_others_replies' => false,
171	'read_private_replies' => false,
172
173	// Topic tag caps
174	'manage_topic_tags' => false,
175	'edit_topic_tags' => false,
176	'delete_topic_tags' => false,
177	'assign_topic_tags' => false,
178	);
179
180	break;
181
182	// Participant/Default
183	case bbp_get_participant_role() :
184	default :
185	$caps = array(
186
187	// Primary caps
188	'spectate' => true,
189	'participate' => true,
190
191	// Forum caps
192	'read_private_forums' => true,
193
194	// Topic caps
195	'publish_topics' => true,
196	'edit_topics' => true,
197
198	// Reply caps
199	'publish_replies' => true,
200	'edit_replies' => true,
201
202	// Topic tag caps
203	'assign_topic_tags' => true,
204	);
205
206	break;
207	}
208
209	// Filter & return
210	return apply_filters( 'bbp_get_caps_for_role', $caps, $role );
211	}
212
213	/**
214	* Adds capabilities to WordPress user roles.
215	*
216	* @since 2.0.0 bbPress (r2608)
217	*/
218	function bbp_add_caps() {
219
220	// Loop through available roles and add caps
221	foreach ( bbp_get_wp_roles()->role_objects as $role ) {
222	foreach ( bbp_get_caps_for_role( $role->name ) as $cap => $value ) {
223	$role->add_cap( $cap, $value );
224	}
225	}
226
227	do_action( 'bbp_add_caps' );
228	}
229
230	/**
231	* Removes capabilities from WordPress user roles.
232	*
233	* @since 2.0.0 bbPress (r2608)
234	*/
235	function bbp_remove_caps() {
236
237	// Loop through available roles and remove caps
238	foreach ( bbp_get_wp_roles()->role_objects as $role ) {
239	foreach ( array_keys( bbp_get_caps_for_role( $role->name ) ) as $cap ) {
240	$role->remove_cap( $cap );
241	}
242	}
243
244	do_action( 'bbp_remove_caps' );
245	}
246
247	/**
248	* Get the available roles, minus the dynamic roles that come with bbPress.
249	*
250	* @since 2.4.0 bbPress (r5064)
251	*
252	* @return array
253	*/
254	function bbp_get_blog_roles() {
255
256	// Get WordPress's roles (returns $wp_roles global)
257	$wp_roles = bbp_get_wp_roles();
258
259	// Apply the WordPress 'editable_roles' filter to let plugins ride along.
260	//
261	// We use this internally via bbp_filter_blog_editable_roles() to remove
262	// any custom bbPress roles that are added to the global.
263	$the_roles = isset( $wp_roles->roles ) ? $wp_roles->roles : false;
264	$all_roles = apply_filters( 'editable_roles', $the_roles );
265
266	// Filter & return
267	return apply_filters( 'bbp_get_blog_roles', $all_roles, $wp_roles );
268	}
269
270	/ Forum Roles *************************************************************/
271
272	/**
273	* Add the bbPress roles to the $wp_roles global.
274	*
275	* We do this to avoid adding these values to the database.
276	*
277	* Note: bbPress is purposely assertive here, overwriting any keys & values
278	* that may already exist in the $wp_roles array.
279	*
280	* @since 2.2.0 bbPress (r4290)
281	*
282	* @param WP_Roles $wp_roles The array of WP_Role objects that was initialized.
283	*
284	* @return WP_Roles The main $wp_roles global.
285	*/
286	function bbp_add_forums_roles( $wp_roles = null ) {
287
288	// Maybe initialize WP_Roles just-in-time, but
289	if ( empty( $wp_roles ) && ! doing_action( 'wp_roles_init' ) ) {
290	$wp_roles = wp_roles();
291	}
292
293	// Bail if unexpected param type
294	if ( ! is_a( $wp_roles, 'WP_Roles' ) ) {
295	return;
296	}
297
298	// Get the dynamic roles
299	$bbp_roles = bbp_get_dynamic_roles();
300
301	// Loop through dynamic roles and add them to the $wp_roles array
302	foreach ( $bbp_roles as $role_id => $details ) {
303	$wp_roles->roles[ $role_id ] = $details;
304	$wp_roles->role_objects[ $role_id ] = new WP_Role( $role_id, $details['capabilities'] );
305	$wp_roles->role_names[ $role_id ] = $details['name'];
306	}
307
308	// Return the modified $wp_roles array
309	return $wp_roles;
310	}
311
312	/**
313	* Helper function to add filter to option_wp_user_roles.
314	*
315	* @since 2.2.0 bbPress (r4363)
316	* @deprecated 2.6.0 bbPress (r6105)
317	*
318	* @see _bbp_reinit_dynamic_roles()
319	*/
320	function bbp_filter_user_roles_option() {
321	$role_key = bbp_db()->prefix . 'user_roles';
322
323	add_filter( 'option_' . $role_key, '_bbp_reinit_dynamic_roles' );
324	}
325
326	/**
327	* This is necessary because in a few places (noted below) WordPress initializes
328	* a blog's roles directly from the database option. When this happens, the
329	* $wp_roles global gets flushed, causing a user to magically lose any
330	* dynamically assigned roles or capabilities when $current_user in refreshed.
331	*
332	* Because dynamic multiple roles is a new concept in WordPress, we work around
333	* it here for now, knowing that improvements will come to WordPress core later.
334	*
335	* Also note that if using the $wp_user_roles global non-database approach,
336	* bbPress does not have an intercept point to add its dynamic roles.
337	*
338	* @see bbp_switch_to_site()
339	* @see bbp_restore_current_site()
340	* @see WP_Roles::_init()
341	*
342	* @since 2.2.0 bbPress (r4363)
343	* @deprecated 2.6.0 bbPress (r6105)
344	*
345	* @internal Used by bbPress to reinitialize dynamic roles on blog switch.
346	*
347	* @param array $roles
348	* @return array Combined array of database roles and dynamic bbPress roles.
349	*/
350	function _bbp_reinit_dynamic_roles( $roles = array() ) {
351	foreach ( bbp_get_dynamic_roles() as $role_id => $details ) {
352	$roles[ $role_id ] = $details;
353	}
354	return $roles;
355	}
356
357	/**
358	* Fetch a filtered list of forum roles that the current user is
359	* allowed to have.
360	*
361	* Simple function who's main purpose is to allow filtering of the
362	* list of forum roles so that plugins can remove inappropriate ones depending
363	* on the situation or user making edits.
364	*
365	* Specifically because without filtering, anyone with the edit_users
366	* capability can edit others to be administrators, even if they are
367	* only editors or authors. This filter allows admins to delegate
368	* user management.
369	*
370	* @since 2.2.0 bbPress (r4284)
371	* @since 2.6.0 bbPress (r6117) Use bbpress()->roles
372	*
373	* @return array
374	*/
375	function bbp_get_dynamic_roles() {
376
377	// Defaults
378	$to_array = array();
379	$roles = bbpress()->roles;
380
381	// Convert WP_Roles objects to arrays
382	foreach ( $roles as $role_id => $wp_role ) {
383	$to_array[ $role_id ] = (array) $wp_role;
384	}
385
386	// Filter & return
387	return (array) apply_filters( 'bbp_get_dynamic_roles', $to_array, $roles );
388	}
389
390	/**
391	* Gets a translated role name from a role ID.
392	*
393	* @since 2.3.0 bbPress (r4792)
394	* @since 2.6.0 bbPress (r6117) Use bbp_translate_user_role()
395	*
396	* @param string $role_id
397	* @return string Translated role name.
398	*/
399	function bbp_get_dynamic_role_name( $role_id = '' ) {
400	$roles = bbp_get_dynamic_roles();
401	$role = isset( $roles[ $role_id ] )
402	? bbp_translate_user_role( $roles[ $role_id ]['name'] )
403	: '';
404
405	// Filter & return
406	return apply_filters( 'bbp_get_dynamic_role_name', $role, $role_id, $roles );
407	}
408
409	/**
410	* Removes the bbPress roles from the editable roles array.
411	*
412	* This used to use array_diff_assoc() but it randomly broke before 2.2 release.
413	* Need to research what happened, and if there's a way to speed this up.
414	*
415	* @since 2.2.0 bbPress (r4303)
416	*
417	* @param array $all_roles All registered roles.
418	* @return array
419	*/
420	function bbp_filter_blog_editable_roles( $all_roles = array() ) {
421
422	// Loop through bbPress roles
423	foreach ( array_keys( bbp_get_dynamic_roles() ) as $bbp_role ) {
424
425	// Loop through WordPress roles
426	foreach ( array_keys( $all_roles ) as $wp_role ) {
427
428	// If keys match, unset
429	if ( $wp_role === $bbp_role ) {
430	unset( $all_roles[ $wp_role ] );
431	}
432	}
433	}
434
435	return $all_roles;
436	}
437
438	/**
439	* The keymaster role for bbPress users.
440	*
441	* @since 2.2.0 bbPress (r4284)
442	*
443	* @return string
444	*/
445	function bbp_get_keymaster_role() {
446
447	// Filter & return
448	return apply_filters( 'bbp_get_keymaster_role', 'bbp_keymaster' );
449	}
450
451	/**
452	* The moderator role for bbPress users.
453	*
454	* @since 2.0.0 bbPress (r3410)
455	*
456	* @return string
457	*/
458	function bbp_get_moderator_role() {
459
460	// Filter & return
461	return apply_filters( 'bbp_get_moderator_role', 'bbp_moderator' );
462	}
463
464	/**
465	* The participant role for registered user that can participate in forums.
466	*
467	* @since 2.0.0 bbPress (r3410)
468	*
469	* @return string
470	*/
471	function bbp_get_participant_role() {
472
473	// Filter & return
474	return apply_filters( 'bbp_get_participant_role', 'bbp_participant' );
475	}
476
477	/**
478	* The spectator role is for registered users without any capabilities.
479	*
480	* @since 2.1.0 bbPress (r3860)
481	*
482	* @return string
483	*/
484	function bbp_get_spectator_role() {
485
486	// Filter & return
487	return apply_filters( 'bbp_get_spectator_role', 'bbp_spectator' );
488	}
489
490	/**
491	* The blocked role is for registered users that cannot spectate or participate.
492	*
493	* @since 2.2.0 bbPress (r4284)
494	*
495	* @return string
496	*/
497	function bbp_get_blocked_role() {
498
499	// Filter & return
500	return apply_filters( 'bbp_get_blocked_role', 'bbp_blocked' );
501	}
502
503	/**
504	* Adds bbPress-specific user roles.
505	*
506	* @since 2.0.0 bbPress (r2741)
507	*
508	* @deprecated 2.2.0 bbPress (r4164)
509	*/
510	function bbp_add_roles() {
511	_doing_it_wrong( 'bbp_add_roles', esc_html__( 'Editable forum roles no longer exist.', 'bbpress' ), '2.2' );
512	}
513
514	/**
515	* Removes bbPress-specific user roles from the `wp_user_roles` array.
516	*
517	* This is currently only used when updating, uninstalling, or resetting bbPress.
518	*
519	* @see bbp_admin_reset_handler()
520	* @see bbp_do_uninstall()
521	* @see bbp_version_updater()
522	*
523	* @since 2.0.0 bbPress (r2741)
524	*/
525	function bbp_remove_roles() {
526
527	// Remove the bbPress roles
528	foreach ( array_keys( bbp_get_dynamic_roles() ) as $bbp_role ) {
529	remove_role( $bbp_role );
530	}
531
532	// Some early adopters may have a deprecated visitor role. It was later
533	// replaced by the Spectator role.
534	remove_role( 'bbp_visitor' );
535	}
536