| @@ -1,8 +1,8 @@ | ||
| 1 | 1 | <?php |
| 2 | 2 | |
| 3 | 3 | /** |
| 4 | - * bbPress User Capabilities. | |
| 4 | + * bbPress User Capabilites | |
| 5 | 5 | * |
| 6 | 6 | * Used to map user capabilities to WordPress's existing capabilities. |
| 7 | 7 | * |
| 8 | 8 | * @package bbPress |
| @@ -9,12 +9,12 @@ | ||
| 9 | 9 | * @subpackage Capabilities |
| 10 | 10 | */ |
| 11 | 11 | |
| 12 | 12 | /** |
| 13 | - * Maps primary capabilities. | |
| 13 | + * Maps primary capabilities | |
| 14 | 14 | * |
| 15 | 15 | * @since 2.2.0 bbPress (r4244) |
| 16 | - * @since 2.6.19 bbPress (r7689) Limit super moderator edits to site members and protect peer roles. | |
| 16 | + * @since 2.6.19 bbPress (r7690) Limit super moderator edits to site members and protect peer roles. | |
| 17 | 17 | * |
| 18 | 18 | * @param array $caps Capabilities for meta capability. |
| 19 | 19 | * @param string $cap Capability name. |
| 20 | 20 | * @param int $user_id User id. |
| @@ -19,9 +19,9 @@ | ||
| 19 | 19 | * @param string $cap Capability name. |
| 20 | 20 | * @param int $user_id User id. |
| 21 | 21 | * @param array $args Arguments. |
| 22 | 22 | * |
| 23 | - * @return array Actual capabilities for meta capability. | |
| 23 | + * @return array Actual capabilities for meta capability | |
| 24 | 24 | */ |
| 25 | 25 | function bbp_map_primary_meta_caps( $caps = array(), $cap = '', $user_id = 0, $args = array() ) { |
| 26 | 26 | |
| 27 | 27 | // What capability is being checked? |
| @@ -149,13 +149,13 @@ | ||
| 149 | 149 | return (array) apply_filters( 'bbp_map_primary_meta_caps', $caps, $cap, $user_id, $args ); |
| 150 | 150 | } |
| 151 | 151 | |
| 152 | 152 | /** |
| 153 | - * Set a user's role in the forums. | |
| 153 | + * Set a user's role in the forums | |
| 154 | 154 | * |
| 155 | 155 | * @since 2.2.0 bbPress (r4289) |
| 156 | 156 | * |
| 157 | - * @param int $user_id User id. | |
| 157 | + * @param int $user_id | |
| 158 | 158 | * |
| 159 | 159 | * @return mixed False if no change. String of new role if changed. |
| 160 | 160 | */ |
| 161 | 161 | function bbp_set_user_role( $user_id = 0, $new_role = '' ) { |
| @@ -187,9 +187,9 @@ | ||
| 187 | 187 | $user->add_role( $new_role ); |
| 188 | 188 | } |
| 189 | 189 | } |
| 190 | 190 | |
| 191 | - // User does don exist so return false | |
| 191 | + // User does not exist so return false | |
| 192 | 192 | } else { |
| 193 | 193 | $new_role = false; |
| 194 | 194 | } |
| 195 | 195 | |
| @@ -197,13 +197,13 @@ | ||
| 197 | 197 | return apply_filters( 'bbp_set_user_role', $new_role, $user_id, $user ); |
| 198 | 198 | } |
| 199 | 199 | |
| 200 | 200 | /** |
| 201 | - * Return a user's forums role. | |
| 201 | + * Return a user's forums role | |
| 202 | 202 | * |
| 203 | 203 | * @since 2.1.0 bbPress (r3860) |
| 204 | 204 | * |
| 205 | - * @param int $user_id User id. | |
| 205 | + * @param int $user_id | |
| 206 | 206 | * |
| 207 | 207 | * @return string |
| 208 | 208 | */ |
| 209 | 209 | function bbp_get_user_role( $user_id = 0 ) { |
| @@ -234,13 +234,13 @@ | ||
| 234 | 234 | return apply_filters( 'bbp_get_user_role', $role, $user_id, $user ); |
| 235 | 235 | } |
| 236 | 236 | |
| 237 | 237 | /** |
| 238 | - * Return a user's blog role. | |
| 238 | + * Return a user's blog role | |
| 239 | 239 | * |
| 240 | 240 | * @since 2.3.0 bbPress (r4447) |
| 241 | 241 | * |
| 242 | - * @param int $user_id User id. | |
| 242 | + * @param int $user_id | |
| 243 | 243 | * |
| 244 | 244 | * @return string |
| 245 | 245 | */ |
| 246 | 246 | function bbp_get_user_blog_role( $user_id = 0 ) { |
| @@ -271,14 +271,19 @@ | ||
| 271 | 271 | return apply_filters( 'bbp_get_user_blog_role', $role, $user_id, $user ); |
| 272 | 272 | } |
| 273 | 273 | |
| 274 | 274 | /** |
| 275 | - * Helper function hooked to 'bbp_profile_update' action to save or | |
| 276 | - * update user roles and capabilities. | |
| 275 | + * Helper function to save or update user roles and capabilities. | |
| 277 | 276 | * |
| 277 | + * By default, this is hooked to the `bbp_profile_update` action which fires | |
| 278 | + * after a user profile is updated to avoid being stomped by set_role(). | |
| 279 | + * | |
| 278 | 280 | * @since 2.2.0 bbPress (r4330) |
| 279 | 281 | * |
| 280 | - * @param int $user_id User id. | |
| 282 | + * @param int $user_id | |
| 283 | + * | |
| 284 | + * @return void If no user ID passed, invalid request, trying to set own role, | |
| 285 | + * current user cannot promote the passing user, or no role passed | |
| 281 | 286 | */ |
| 282 | 287 | function bbp_profile_update_role( $user_id = 0 ) { |
| 283 | 288 | |
| 284 | 289 | // Bail if no user ID |
| @@ -326,10 +331,10 @@ | ||
| 326 | 331 | |
| 327 | 332 | /** |
| 328 | 333 | * Return the forum roles the current user may assign to another user. |
| 329 | 334 | * |
| 330 | - * @since 2.6.17 bbPress (r7513) | |
| 331 | - * @since 2.6.19 bbPress (r7685) Allow site administrators to assign staff roles. | |
| 335 | + * @since 2.6.17 bbPress (r7514) | |
| 336 | + * @since 2.6.19 bbPress (r7686) Allow site administrators to assign staff roles. | |
| 332 | 337 | * |
| 333 | 338 | * @param int $user_id User being edited. Defaults to the displayed user. |
| 334 | 339 | * @return array Filtered array of editable forum roles. |
| 335 | 340 | */ |
| @@ -351,9 +356,9 @@ | ||
| 351 | 356 | |
| 352 | 357 | /** |
| 353 | 358 | * Return whether the current user may edit a user-profile field. |
| 354 | 359 | * |
| 355 | - * @since 2.6.17 bbPress (r7513) | |
| 360 | + * @since 2.6.17 bbPress (r7514) | |
| 356 | 361 | * |
| 357 | 362 | * @param string $field Profile field group: profile, email, password, |
| 358 | 363 | * site_role, or forum_role. |
| 359 | 364 | * @param int $user_id User being edited. Defaults to the displayed user. |
| @@ -392,21 +397,14 @@ | ||
| 392 | 397 | return (bool) apply_filters( 'bbp_current_user_can_edit_user_field', $retval, $field, $user_id, $current_user_id ); |
| 393 | 398 | } |
| 394 | 399 | |
| 395 | 400 | /** |
| 396 | - * Check if a role ID is valid. | |
| 401 | + * Check if a role string is valid | |
| 397 | 402 | * |
| 398 | - * This helper function accepts a role ID as a string, and compares it against | |
| 399 | - * the array of registered dynamic roles. | |
| 403 | + * @since 2.6.5 bbPress (r7087) | |
| 400 | 404 | * |
| 401 | - * Use this function anytime you are manually attempting to set a user role | |
| 402 | - * without using the bbp_set_user_role() function, or if you need to halt | |
| 403 | - * additional processing during role validation. | |
| 405 | + * @param string $role | |
| 404 | 406 | * |
| 405 | - * @since 2.6.5 bbPress (r7086) | |
| 406 | - * | |
| 407 | - * @param string $role A well-formed (string) role ID to validate. | |
| 408 | - * | |
| 409 | 407 | * @return bool True if role is valid. False if role is not valid. |
| 410 | 408 | */ |
| 411 | 409 | function bbp_is_valid_role( $role = '' ) { |
| 412 | 410 | |
| @@ -431,9 +429,9 @@ | ||
| 431 | 429 | return (bool) apply_filters( 'bbp_is_valid_role', $retval, $role ); |
| 432 | 430 | } |
| 433 | 431 | |
| 434 | 432 | /** |
| 435 | - * Add the default role to the current user if needed. | |
| 433 | + * Add the default role to the current user if needed | |
| 436 | 434 | * |
| 437 | 435 | * This function will bail if the forum is not global in a multisite |
| 438 | 436 | * installation of WordPress, or if the user is marked as spam or deleted. |
| 439 | 437 | * |
| @@ -438,9 +436,9 @@ | ||
| 438 | 436 | * installation of WordPress, or if the user is marked as spam or deleted. |
| 439 | 437 | * |
| 440 | 438 | * @since 2.2.0 bbPress (r4185) |
| 441 | 439 | * |
| 442 | - * @return If not multisite, not global, or user is deleted/spammed. | |
| 440 | + * @return void If not multisite, not global, or user is deleted/spammed | |
| 443 | 441 | */ |
| 444 | 442 | function bbp_set_current_user_default_role() { |
| 445 | 443 | |
| 446 | 444 | /** Sanity ****************************************************************/ |
| @@ -513,9 +511,9 @@ | ||
| 513 | 511 | * role in the forums. Also guarantees WordPress admins get the Keymaster role. |
| 514 | 512 | * |
| 515 | 513 | * @since 2.2.0 bbPress (r4335) |
| 516 | 514 | * |
| 517 | - * @return array Filtered array of WordPress roles to bbPress roles. | |
| 515 | + * @return array Filtered array of WordPress roles to bbPress roles | |
| 518 | 516 | */ |
| 519 | 517 | function bbp_get_user_role_map() { |
| 520 | 518 | |
| 521 | 519 | // Get the default role once here |
| @@ -575,9 +573,9 @@ | ||
| 575 | 573 | return (bool) apply_filters( 'bbp_core_is_user_spammer', $is_spammer ); |
| 576 | 574 | } |
| 577 | 575 | |
| 578 | 576 | /** |
| 579 | - * Mark a users topics and replies as spam when the user is marked as spam. | |
| 577 | + * Mark a users topics and replies as spam when the user is marked as spam | |
| 580 | 578 | * |
| 581 | 579 | * @since 2.0.0 bbPress (r3410) |
| 582 | 580 | * |
| 583 | 581 | * @param int $user_id Optional. User ID to spam. Defaults to displayed user. |
| @@ -662,9 +660,9 @@ | ||
| 662 | 660 | return true; |
| 663 | 661 | } |
| 664 | 662 | |
| 665 | 663 | /** |
| 666 | - * Mark a users topics and replies as spam when the user is marked as spam. | |
| 664 | + * Mark a users topics and replies as spam when the user is marked as spam | |
| 667 | 665 | * |
| 668 | 666 | * @since 2.0.0 bbPress (r3410) |
| 669 | 667 | * |
| 670 | 668 | * @param int $user_id Optional. User ID to unspam. Defaults to displayed user. |
| @@ -792,14 +790,14 @@ | ||
| 792 | 790 | return (bool) apply_filters( 'bbp_core_is_user_deleted', $is_deleted ); |
| 793 | 791 | } |
| 794 | 792 | |
| 795 | 793 | /** |
| 796 | - * Checks if user is active. | |
| 794 | + * Checks if user is active | |
| 797 | 795 | * |
| 798 | 796 | * @since 2.0.0 bbPress (r3504) |
| 799 | 797 | * |
| 800 | - * @param int $user_id The user ID to check. | |
| 801 | - * @return bool True if public, false if not. | |
| 798 | + * @param int $user_id The user ID to check | |
| 799 | + * @return bool True if public, false if not | |
| 802 | 800 | */ |
| 803 | 801 | function bbp_is_user_active( $user_id = 0 ) { |
| 804 | 802 | |
| 805 | 803 | // No user to check |
| @@ -826,10 +824,10 @@ | ||
| 826 | 824 | * Checks if user is not active. |
| 827 | 825 | * |
| 828 | 826 | * @since 2.0.0 bbPress (r3504) |
| 829 | 827 | * |
| 830 | - * @param int $user_id The user ID to check. Defaults to current user ID. | |
| 831 | - * @return bool True if inactive, false if active. | |
| 828 | + * @param int $user_id The user ID to check. Defaults to current user ID | |
| 829 | + * @return bool True if inactive, false if active | |
| 832 | 830 | */ |
| 833 | 831 | function bbp_is_user_inactive( $user_id = 0 ) { |
| 834 | 832 | return ! bbp_is_user_active( $user_id ); |
| 835 | 833 | } |
| @@ -834,14 +832,14 @@ | ||
| 834 | 832 | return ! bbp_is_user_active( $user_id ); |
| 835 | 833 | } |
| 836 | 834 | |
| 837 | 835 | /** |
| 838 | - * Checks if user is a keymaster. | |
| 836 | + * Checks if user is a keymaster | |
| 839 | 837 | * |
| 840 | 838 | * @since 2.3.0 bbPress (r4783) |
| 841 | 839 | * |
| 842 | - * @param int $user_id The user ID to check. Defaults to current user ID. | |
| 843 | - * @return bool True if keymaster, false if not. | |
| 840 | + * @param int $user_id | |
| 841 | + * @return bool True if keymaster, false if not | |
| 844 | 842 | */ |
| 845 | 843 | function bbp_is_user_keymaster( $user_id = 0 ) { |
| 846 | 844 | $_user_id = bbp_get_user_id( $user_id, false, true ); |
| 847 | 845 | $retval = user_can( $_user_id, 'keep_gate' ); |
| @@ -850,13 +848,13 @@ | ||
| 850 | 848 | return (bool) apply_filters( 'bbp_is_user_keymaster', $retval, $_user_id, $user_id ); |
| 851 | 849 | } |
| 852 | 850 | |
| 853 | 851 | /** |
| 854 | - * Does a user have a profile for the current site. | |
| 852 | + * Does a user have a profile for the current site | |
| 855 | 853 | * |
| 856 | 854 | * @since 2.2.0 bbPress (r4363) |
| 857 | 855 | * |
| 858 | - * @param int $user_id User ID to check. | |
| 856 | + * @param int $user_id User ID to check | |
| 859 | 857 | * |
| 860 | 858 | * @return bool Whether or not the user has a profile on this blog_id. |
| 861 | 859 | */ |
| 862 | 860 | function bbp_user_has_profile( $user_id = 0 ) { |
| @@ -885,15 +883,15 @@ | ||
| 885 | 883 | |
| 886 | 884 | /** Moderators ****************************************************************/ |
| 887 | 885 | |
| 888 | 886 | /** |
| 889 | - * Add a moderator to an object. | |
| 887 | + * Add a moderator to an object | |
| 890 | 888 | * |
| 891 | 889 | * @since 2.6.0 bbPress (r6056) |
| 892 | 890 | * |
| 893 | - * @param int $object_id Traditionally a post ID. | |
| 894 | - * @param int $user_id User ID. | |
| 895 | - * @param string $object_type Type of meta (post,term,user,comment). | |
| 891 | + * @param int $object_id Traditionally a post ID | |
| 892 | + * @param int $user_id User ID | |
| 893 | + * @param string $object_type Type of meta (post,term,user,comment) | |
| 896 | 894 | * |
| 897 | 895 | * @return bool |
| 898 | 896 | */ |
| 899 | 897 | function bbp_add_moderator( $object_id = 0, $user_id = 0, $object_type = 'post' ) { |
| @@ -900,15 +898,15 @@ | ||
| 900 | 898 | return bbp_add_user_to_object( $object_id, $user_id, '_bbp_moderator_id', $object_type ); |
| 901 | 899 | } |
| 902 | 900 | |
| 903 | 901 | /** |
| 904 | - * Remove a moderator user ID from an object. | |
| 902 | + * Remove a moderator user ID from an object | |
| 905 | 903 | * |
| 906 | 904 | * @since 2.6.0 bbPress (r6056) |
| 907 | 905 | * |
| 908 | - * @param int $object_id Traditionally a post ID. | |
| 909 | - * @param int $user_id User ID. | |
| 910 | - * @param string $object_type Type of meta (post,term,user,comment). | |
| 906 | + * @param int $object_id Traditionally a post ID | |
| 907 | + * @param int $user_id User ID | |
| 908 | + * @param string $object_type Type of meta (post,term,user,comment) | |
| 911 | 909 | * |
| 912 | 910 | * @return bool |
| 913 | 911 | */ |
| 914 | 912 | function bbp_remove_moderator( $object_id = 0, $user_id = 0, $object_type = 'post' ) { |
| @@ -915,14 +913,14 @@ | ||
| 915 | 913 | return bbp_remove_user_from_object( $object_id, $user_id, '_bbp_moderator_id', $object_type ); |
| 916 | 914 | } |
| 917 | 915 | |
| 918 | 916 | /** |
| 919 | - * Get user IDs of moderators for an object. | |
| 917 | + * Get user IDs of moderators for an object | |
| 920 | 918 | * |
| 921 | 919 | * @since 2.6.0 bbPress (r6056) |
| 922 | 920 | * |
| 923 | - * @param int $object_id Traditionally a post ID. | |
| 924 | - * @param string $object_type Type of meta (post,term,user,comment). | |
| 921 | + * @param int $object_id Traditionally a post ID | |
| 922 | + * @param string $object_type Type of meta (post,term,user,comment) | |
| 925 | 923 | * |
| 926 | 924 | * @return array |
| 927 | 925 | */ |
| 928 | 926 | function bbp_get_moderator_ids( $object_id = 0, $object_type = 'post' ) { |
| @@ -934,10 +932,10 @@ | ||
| 934 | 932 | * object ID is empty. |
| 935 | 933 | * |
| 936 | 934 | * @since 2.6.0 bbPress (r6056) |
| 937 | 935 | * |
| 938 | - * @param int $object_id Traditionally a post ID. | |
| 939 | - * @param string $object_type Type of meta (post,term,user,comment). | |
| 936 | + * @param int $object_id Traditionally a post ID | |
| 937 | + * @param string $object_type Type of meta (post,term,user,comment) | |
| 940 | 938 | * |
| 941 | 939 | * @return array |
| 942 | 940 | */ |
| 943 | 941 | function bbp_get_moderators( $object_id = 0, $object_type = 'post' ) { |
