| @@ -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,9 +9,9 @@ | ||
| 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 (r4242) |
| 16 | 16 | * |
| 17 | 17 | * @param array $caps Capabilities for meta capability. |
| @@ -18,9 +18,9 @@ | ||
| 18 | 18 | * @param string $cap Capability name. |
| 19 | 19 | * @param int $user_id User id. |
| 20 | 20 | * @param array $args Arguments. |
| 21 | 21 | * |
| 22 | - * @return array Actual capabilities for meta capability. | |
| 22 | + * @return array Actual capabilities for meta capability | |
| 23 | 23 | */ |
| 24 | 24 | function bbp_map_primary_meta_caps( $caps = array(), $cap = '', $user_id = 0, $args = array() ) { |
| 25 | 25 | |
| 26 | 26 | // What capability is being checked? |
| @@ -145,13 +145,13 @@ | ||
| 145 | 145 | return (array) apply_filters( 'bbp_map_primary_meta_caps', $caps, $cap, $user_id, $args ); |
| 146 | 146 | } |
| 147 | 147 | |
| 148 | 148 | /** |
| 149 | - * Set a user's role in the forums. | |
| 149 | + * Set a user's role in the forums | |
| 150 | 150 | * |
| 151 | 151 | * @since 2.1.0 bbPress (r3860) |
| 152 | 152 | * |
| 153 | - * @param int $user_id User id. | |
| 153 | + * @param int $user_id | |
| 154 | 154 | * |
| 155 | 155 | * @return mixed False if no change. String of new role if changed. |
| 156 | 156 | */ |
| 157 | 157 | function bbp_set_user_role( $user_id = 0, $new_role = '' ) { |
| @@ -183,9 +183,9 @@ | ||
| 183 | 183 | $user->add_role( $new_role ); |
| 184 | 184 | } |
| 185 | 185 | } |
| 186 | 186 | |
| 187 | - // User does don exist so return false | |
| 187 | + // User does not exist so return false | |
| 188 | 188 | } else { |
| 189 | 189 | $new_role = false; |
| 190 | 190 | } |
| 191 | 191 | |
| @@ -193,13 +193,13 @@ | ||
| 193 | 193 | return apply_filters( 'bbp_set_user_role', $new_role, $user_id, $user ); |
| 194 | 194 | } |
| 195 | 195 | |
| 196 | 196 | /** |
| 197 | - * Return a user's forums role. | |
| 197 | + * Return a user's forums role | |
| 198 | 198 | * |
| 199 | 199 | * @since 2.1.0 bbPress (r3860) |
| 200 | 200 | * |
| 201 | - * @param int $user_id User id. | |
| 201 | + * @param int $user_id | |
| 202 | 202 | * |
| 203 | 203 | * @return string |
| 204 | 204 | */ |
| 205 | 205 | function bbp_get_user_role( $user_id = 0 ) { |
| @@ -230,13 +230,13 @@ | ||
| 230 | 230 | return apply_filters( 'bbp_get_user_role', $role, $user_id, $user ); |
| 231 | 231 | } |
| 232 | 232 | |
| 233 | 233 | /** |
| 234 | - * Return a user's blog role. | |
| 234 | + * Return a user's blog role | |
| 235 | 235 | * |
| 236 | 236 | * @since 2.3.0 bbPress (r4446) |
| 237 | 237 | * |
| 238 | - * @param int $user_id User id. | |
| 238 | + * @param int $user_id | |
| 239 | 239 | * |
| 240 | 240 | * @return string |
| 241 | 241 | */ |
| 242 | 242 | function bbp_get_user_blog_role( $user_id = 0 ) { |
| @@ -267,14 +267,19 @@ | ||
| 267 | 267 | return apply_filters( 'bbp_get_user_blog_role', $role, $user_id, $user ); |
| 268 | 268 | } |
| 269 | 269 | |
| 270 | 270 | /** |
| 271 | - * Helper function hooked to 'bbp_profile_update' action to save or | |
| 272 | - * update user roles and capabilities. | |
| 271 | + * Helper function to save or update user roles and capabilities. | |
| 273 | 272 | * |
| 273 | + * By default, this is hooked to the `bbp_profile_update` action which fires | |
| 274 | + * after a user profile is updated to avoid being stomped by set_role(). | |
| 275 | + * | |
| 274 | 276 | * @since 2.2.0 bbPress (r4235) |
| 275 | 277 | * |
| 276 | - * @param int $user_id User id. | |
| 278 | + * @param int $user_id | |
| 279 | + * | |
| 280 | + * @return void If no user ID passed, invalid request, trying to set own role, | |
| 281 | + * current user cannot promote the passing user, or no role passed | |
| 277 | 282 | */ |
| 278 | 283 | function bbp_profile_update_role( $user_id = 0 ) { |
| 279 | 284 | |
| 280 | 285 | // Bail if no user ID |
| @@ -386,20 +391,13 @@ | ||
| 386 | 391 | return (bool) apply_filters( 'bbp_current_user_can_edit_user_field', $retval, $field, $user_id, $current_user_id ); |
| 387 | 392 | } |
| 388 | 393 | |
| 389 | 394 | /** |
| 390 | - * Check if a role ID is valid. | |
| 395 | + * Check if a role string is valid | |
| 391 | 396 | * |
| 392 | - * This helper function accepts a role ID as a string, and compares it against | |
| 393 | - * the array of registered dynamic roles. | |
| 394 | - * | |
| 395 | - * Use this function anytime you are manually attempting to set a user role | |
| 396 | - * without using the bbp_set_user_role() function, or if you need to halt | |
| 397 | - * additional processing during role validation. | |
| 398 | - * | |
| 399 | 397 | * @since 2.6.5 |
| 400 | 398 | * |
| 401 | - * @param string $role A well-formed (string) role ID to validate. | |
| 399 | + * @param string $role | |
| 402 | 400 | * |
| 403 | 401 | * @return bool True if role is valid. False if role is not valid. |
| 404 | 402 | */ |
| 405 | 403 | function bbp_is_valid_role( $role = '' ) { |
| @@ -425,9 +423,9 @@ | ||
| 425 | 423 | return (bool) apply_filters( 'bbp_is_valid_role', $retval, $role ); |
| 426 | 424 | } |
| 427 | 425 | |
| 428 | 426 | /** |
| 429 | - * Add the default role to the current user if needed. | |
| 427 | + * Add the default role to the current user if needed | |
| 430 | 428 | * |
| 431 | 429 | * This function will bail if the forum is not global in a multisite |
| 432 | 430 | * installation of WordPress, or if the user is marked as spam or deleted. |
| 433 | 431 | * |
| @@ -432,9 +430,9 @@ | ||
| 432 | 430 | * installation of WordPress, or if the user is marked as spam or deleted. |
| 433 | 431 | * |
| 434 | 432 | * @since 2.0.0 bbPress (r3380) |
| 435 | 433 | * |
| 436 | - * @return If not multisite, not global, or user is deleted/spammed. | |
| 434 | + * @return void If not multisite, not global, or user is deleted/spammed | |
| 437 | 435 | */ |
| 438 | 436 | function bbp_set_current_user_default_role() { |
| 439 | 437 | |
| 440 | 438 | /** Sanity ****************************************************************/ |
| @@ -507,9 +505,9 @@ | ||
| 507 | 505 | * role in the forums. Also guarantees WordPress admins get the Keymaster role. |
| 508 | 506 | * |
| 509 | 507 | * @since 2.2.0 bbPress (r4334) |
| 510 | 508 | * |
| 511 | - * @return array Filtered array of WordPress roles to bbPress roles. | |
| 509 | + * @return array Filtered array of WordPress roles to bbPress roles | |
| 512 | 510 | */ |
| 513 | 511 | function bbp_get_user_role_map() { |
| 514 | 512 | |
| 515 | 513 | // Get the default role once here |
| @@ -569,9 +567,9 @@ | ||
| 569 | 567 | return (bool) apply_filters( 'bbp_core_is_user_spammer', $is_spammer ); |
| 570 | 568 | } |
| 571 | 569 | |
| 572 | 570 | /** |
| 573 | - * Mark a users topics and replies as spam when the user is marked as spam. | |
| 571 | + * Mark a users topics and replies as spam when the user is marked as spam | |
| 574 | 572 | * |
| 575 | 573 | * @since 2.0.0 bbPress (r3405) |
| 576 | 574 | * |
| 577 | 575 | * @param int $user_id Optional. User ID to spam. Defaults to displayed user. |
| @@ -656,9 +654,9 @@ | ||
| 656 | 654 | return true; |
| 657 | 655 | } |
| 658 | 656 | |
| 659 | 657 | /** |
| 660 | - * Mark a users topics and replies as spam when the user is marked as spam. | |
| 658 | + * Mark a users topics and replies as spam when the user is marked as spam | |
| 661 | 659 | * |
| 662 | 660 | * @since 2.0.0 bbPress (r3405) |
| 663 | 661 | * |
| 664 | 662 | * @param int $user_id Optional. User ID to unspam. Defaults to displayed user. |
| @@ -786,14 +784,14 @@ | ||
| 786 | 784 | return (bool) apply_filters( 'bbp_core_is_user_deleted', $is_deleted ); |
| 787 | 785 | } |
| 788 | 786 | |
| 789 | 787 | /** |
| 790 | - * Checks if user is active. | |
| 788 | + * Checks if user is active | |
| 791 | 789 | * |
| 792 | 790 | * @since 2.0.0 bbPress (r3502) |
| 793 | 791 | * |
| 794 | - * @param int $user_id The user ID to check. | |
| 795 | - * @return bool True if public, false if not. | |
| 792 | + * @param int $user_id The user ID to check | |
| 793 | + * @return bool True if public, false if not | |
| 796 | 794 | */ |
| 797 | 795 | function bbp_is_user_active( $user_id = 0 ) { |
| 798 | 796 | |
| 799 | 797 | // No user to check |
| @@ -820,10 +818,10 @@ | ||
| 820 | 818 | * Checks if user is not active. |
| 821 | 819 | * |
| 822 | 820 | * @since 2.0.0 bbPress (r3502) |
| 823 | 821 | * |
| 824 | - * @param int $user_id The user ID to check. Defaults to current user ID. | |
| 825 | - * @return bool True if inactive, false if active. | |
| 822 | + * @param int $user_id The user ID to check. Defaults to current user ID | |
| 823 | + * @return bool True if inactive, false if active | |
| 826 | 824 | */ |
| 827 | 825 | function bbp_is_user_inactive( $user_id = 0 ) { |
| 828 | 826 | return ! bbp_is_user_active( $user_id ); |
| 829 | 827 | } |
| @@ -828,14 +826,14 @@ | ||
| 828 | 826 | return ! bbp_is_user_active( $user_id ); |
| 829 | 827 | } |
| 830 | 828 | |
| 831 | 829 | /** |
| 832 | - * Checks if user is a keymaster. | |
| 830 | + * Checks if user is a keymaster | |
| 833 | 831 | * |
| 834 | 832 | * @since 2.3.0 bbPress (r4783) |
| 835 | 833 | * |
| 836 | - * @param int $user_id The user ID to check. Defaults to current user ID. | |
| 837 | - * @return bool True if keymaster, false if not. | |
| 834 | + * @param int $user_id | |
| 835 | + * @return bool True if keymaster, false if not | |
| 838 | 836 | */ |
| 839 | 837 | function bbp_is_user_keymaster( $user_id = 0 ) { |
| 840 | 838 | $_user_id = bbp_get_user_id( $user_id, false, true ); |
| 841 | 839 | $retval = user_can( $_user_id, 'keep_gate' ); |
| @@ -844,13 +842,13 @@ | ||
| 844 | 842 | return (bool) apply_filters( 'bbp_is_user_keymaster', $retval, $_user_id, $user_id ); |
| 845 | 843 | } |
| 846 | 844 | |
| 847 | 845 | /** |
| 848 | - * Does a user have a profile for the current site. | |
| 846 | + * Does a user have a profile for the current site | |
| 849 | 847 | * |
| 850 | 848 | * @since 2.2.0 bbPress (r4362) |
| 851 | 849 | * |
| 852 | - * @param int $user_id User ID to check. | |
| 850 | + * @param int $user_id User ID to check | |
| 853 | 851 | * |
| 854 | 852 | * @return bool Whether or not the user has a profile on this blog_id. |
| 855 | 853 | */ |
| 856 | 854 | function bbp_user_has_profile( $user_id = 0 ) { |
| @@ -879,15 +877,15 @@ | ||
| 879 | 877 | |
| 880 | 878 | /** Moderators ****************************************************************/ |
| 881 | 879 | |
| 882 | 880 | /** |
| 883 | - * Add a moderator to an object. | |
| 881 | + * Add a moderator to an object | |
| 884 | 882 | * |
| 885 | 883 | * @since 2.6.0 bbPress (r6056) |
| 886 | 884 | * |
| 887 | - * @param int $object_id Traditionally a post ID. | |
| 888 | - * @param int $user_id User ID. | |
| 889 | - * @param string $object_type Type of meta (post,term,user,comment). | |
| 885 | + * @param int $object_id Traditionally a post ID | |
| 886 | + * @param int $user_id User ID | |
| 887 | + * @param string $object_type Type of meta (post,term,user,comment) | |
| 890 | 888 | * |
| 891 | 889 | * @return bool |
| 892 | 890 | */ |
| 893 | 891 | function bbp_add_moderator( $object_id = 0, $user_id = 0, $object_type = 'post' ) { |
| @@ -894,15 +892,15 @@ | ||
| 894 | 892 | return bbp_add_user_to_object( $object_id, $user_id, '_bbp_moderator_id', $object_type ); |
| 895 | 893 | } |
| 896 | 894 | |
| 897 | 895 | /** |
| 898 | - * Remove a moderator user ID from an object. | |
| 896 | + * Remove a moderator user ID from an object | |
| 899 | 897 | * |
| 900 | 898 | * @since 2.6.0 bbPress (r6056) |
| 901 | 899 | * |
| 902 | - * @param int $object_id Traditionally a post ID. | |
| 903 | - * @param int $user_id User ID. | |
| 904 | - * @param string $object_type Type of meta (post,term,user,comment). | |
| 900 | + * @param int $object_id Traditionally a post ID | |
| 901 | + * @param int $user_id User ID | |
| 902 | + * @param string $object_type Type of meta (post,term,user,comment) | |
| 905 | 903 | * |
| 906 | 904 | * @return bool |
| 907 | 905 | */ |
| 908 | 906 | function bbp_remove_moderator( $object_id = 0, $user_id = 0, $object_type = 'post' ) { |
| @@ -909,14 +907,14 @@ | ||
| 909 | 907 | return bbp_remove_user_from_object( $object_id, $user_id, '_bbp_moderator_id', $object_type ); |
| 910 | 908 | } |
| 911 | 909 | |
| 912 | 910 | /** |
| 913 | - * Get user IDs of moderators for an object. | |
| 911 | + * Get user IDs of moderators for an object | |
| 914 | 912 | * |
| 915 | 913 | * @since 2.6.0 bbPress (r6056) |
| 916 | 914 | * |
| 917 | - * @param int $object_id Traditionally a post ID. | |
| 918 | - * @param string $object_type Type of meta (post,term,user,comment). | |
| 915 | + * @param int $object_id Traditionally a post ID | |
| 916 | + * @param string $object_type Type of meta (post,term,user,comment) | |
| 919 | 917 | * |
| 920 | 918 | * @return array |
| 921 | 919 | */ |
| 922 | 920 | function bbp_get_moderator_ids( $object_id = 0, $object_type = 'post' ) { |
| @@ -928,10 +926,10 @@ | ||
| 928 | 926 | * object ID is empty. |
| 929 | 927 | * |
| 930 | 928 | * @since 2.6.0 bbPress (r6056) |
| 931 | 929 | * |
| 932 | - * @param int $object_id Traditionally a post ID. | |
| 933 | - * @param string $object_type Type of meta (post,term,user,comment). | |
| 930 | + * @param int $object_id Traditionally a post ID | |
| 931 | + * @param string $object_type Type of meta (post,term,user,comment) | |
| 934 | 932 | * |
| 935 | 933 | * @return array |
| 936 | 934 | */ |
| 937 | 935 | function bbp_get_moderators( $object_id = 0, $object_type = 'post' ) { |
