Changeset 9027 for trunk/src/bp-groups/bp-groups-functions.php
- Timestamp:
- 09/17/2014 01:49:22 AM (11 years ago)
- File:
-
- 1 edited
-
trunk/src/bp-groups/bp-groups-functions.php (modified) (44 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/src/bp-groups/bp-groups-functions.php
r8662 r9027 17 17 18 18 /** 19 * Check s $bp pages global and looks for directory page20 * 21 * @since BuddyPress (1.5 )19 * Check whether there is a Groups directory page in the $bp global. 20 * 21 * @since BuddyPress (1.5.0) 22 22 * 23 23 * @global BuddyPress $bp The one true BuddyPress instance … … 31 31 32 32 /** 33 * Pulls up the database object corresponding to a group33 * Fetch a single group object. 34 34 * 35 35 * When calling up a group object, you should always use this function instead … … 37 37 * support and pass through the groups_get_group filter. 38 38 * 39 * @param string $args The load_users parameter is deprecated and does nothing. 40 * @return BP_Groups_Group $group The group object 39 * @param array $args { 40 * Array of al arguments. 41 * @type int $group_id ID of the group. 42 * @type bool $load_users No longer used. 43 * @type bool $populate_extras Whether to fetch membership data and other 44 * extra information about the group. Default: false. 45 * @return BP_Groups_Group $group The group object. 41 46 */ 42 47 function groups_get_group( $args = '' ) { … … 56 61 } 57 62 58 /** * Group Creation, Editing & Deletion *****************************************/63 /** Group Creation, Editing & Deletion ****************************************/ 59 64 60 65 /** … … 164 169 } 165 170 171 /** 172 * Edit the base details for a group. 173 * 174 * These are the settings that appear on the first page of the group's Admin 175 * section (Name, Description, and "Notify members..."). 176 * 177 * @param int $group_id ID of the group. 178 * @param string $group_name Name of the group. 179 * @param string $group_desc Description of the group. 180 * @param bool $notify_members Whether to send an email notification to group 181 * members about changes in these details. 182 * @return bool True on success, false on failure. 183 */ 166 184 function groups_edit_base_group_details( $group_id, $group_name, $group_desc, $notify_members ) { 167 185 … … 185 203 } 186 204 205 /** 206 * Edit the base details for a group. 207 * 208 * These are the settings that appear on the Settings page of the group's Admin 209 * section (privacy settings, "enable forum", invitation status). 210 * 211 * @param int $group_id ID of the group. 212 * @param bool $enable_forum Whether to enable a forum for the group. 213 * @param string $status Group status. 'public', 'private', 'hidden'. 214 * @param string $invite_status Optional. Who is allowed to send invitations 215 * to the group. 'members', 'mods', or 'admins'. 216 * @return bool True on success, false on failure. 217 */ 187 218 function groups_edit_group_settings( $group_id, $enable_forum, $status, $invite_status = false ) { 188 219 … … 221 252 222 253 /** 223 * Delete a group and all of its associated meta 224 * 225 * @global object $bp BuddyPress global settings 226 * @param int $group_id 227 * @since BuddyPress (1.0) 254 * Delete a group and all of its associated metadata. 255 * 256 * @since BuddyPress (1.0.0) 257 * 258 * @param int $group_id ID of the group to delete. 259 * @return bool True on success, false on failure. 228 260 */ 229 261 function groups_delete_group( $group_id ) { … … 247 279 } 248 280 281 /** 282 * Check a group status (eg 'private') against the whitelist of registered statuses. 283 * 284 * @param string $status Status to check. 285 * @return bool True if status is allowed, otherwise false. 286 */ 249 287 function groups_is_valid_status( $status ) { 250 288 global $bp; … … 253 291 } 254 292 293 /** 294 * Provide a unique, sanitized version of a group slug. 295 * 296 * @param string $slug Group slug to check. 297 * @return A unique and sanitized slug. 298 */ 255 299 function groups_check_slug( $slug ) { 256 300 global $bp; … … 273 317 274 318 /** 275 * Get a group slug by its ID 276 * 277 * @param int $group_id The numeric ID of the group 278 * @return string The group's slug 319 * Get a group slug by its ID. 320 * 321 * @param int $group_id The numeric ID of the group. 322 * @return string The group's slug. 279 323 */ 280 324 function groups_get_slug( $group_id ) { … … 284 328 285 329 /** 286 * Get a group ID by its slug 287 * 288 * @since BuddyPress (1.6 )289 * 290 * @param string $group_slug The group's slug 291 * @return int The ID 330 * Get a group ID by its slug. 331 * 332 * @since BuddyPress (1.6.0) 333 * 334 * @param string $group_slug The group's slug. 335 * @return int The ID. 292 336 */ 293 337 function groups_get_id( $group_slug ) { … … 295 339 } 296 340 297 /*** User Actions ***************************************************************/ 298 341 /** User Actions **************************************************************/ 342 343 /** 344 * Remove a user from a group. 345 * 346 * @param int $group_id ID of the group. 347 * @param int $user_id Optional. ID of the user. Defaults to the currently 348 * logged-in user. 349 * @return bool True on success, false on failure. 350 */ 299 351 function groups_leave_group( $group_id, $user_id = 0 ) { 300 352 global $bp; … … 323 375 } 324 376 377 /** 378 * Add a user to a group. 379 * 380 * @param int $group_id ID of the group. 381 * @param int $user_id Optional. ID of the user. Defaults to the currently 382 * logged-in user. 383 * @return bool True on success, false on failure. 384 */ 325 385 function groups_join_group( $group_id, $user_id = 0 ) { 326 386 global $bp; … … 373 433 } 374 434 375 /*** General Group Functions ****************************************************/ 376 435 /** General Group Functions ***************************************************/ 436 437 /** 438 * Get a list of group administrators. 439 * 440 * @param int $group_id ID of the group. 441 * @return array Info about group admins (user_id + date_modified). 442 */ 377 443 function groups_get_group_admins( $group_id ) { 378 444 return BP_Groups_Member::get_group_administrator_ids( $group_id ); 379 445 } 380 446 447 /** 448 * Get a list of group moderators. 449 * 450 * @param int $group_id ID of the group. 451 * @return array Info about group admins (user_id + date_modified). 452 */ 381 453 function groups_get_group_mods( $group_id ) { 382 454 return BP_Groups_Member::get_group_moderator_ids( $group_id ); … … 489 561 } 490 562 563 /** 564 * Get the member count for a group. 565 * 566 * @param int $group_id Group ID. 567 * @return int Count of confirmed members for the group. 568 */ 491 569 function groups_get_total_member_count( $group_id ) { 492 570 return BP_Groups_Group::get_total_member_count( $group_id ); 493 571 } 494 572 495 /*** Group Fetching, Filtering & Searching *************************************/ 496 497 /** 498 * Get a collection of groups, based on the parameters passed 499 * 500 * @uses apply_filters_ref_array() Filter 'groups_get_groups' to modify return value 501 * @uses BP_Groups_Group::get() 502 * @param array $args See inline documentation for details 503 * @return array 573 /** Group Fetching, Filtering & Searching ************************************/ 574 575 /** 576 * Get a collection of groups, based on the parameters passed. 577 * 578 * @param array $args { 579 * Array of arguments. Supports all arguments of 580 * {@link BP_Groups_Group::get()}. Where the default values differ, they 581 * have been described here. 582 * @type int $per_page Default: 20. 583 * @type int $page Default: 1. 584 * } 585 * @return array See {@link BP_Groups_Group::get()}. 504 586 */ 505 587 function groups_get_groups( $args = '' ) { … … 542 624 } 543 625 626 /** 627 * Get the total group count for the site. 628 * 629 * @return int 630 */ 544 631 function groups_get_total_group_count() { 545 632 if ( !$count = wp_cache_get( 'bp_total_group_count', 'bp' ) ) { … … 551 638 } 552 639 640 /** 641 * Get the IDs of the groups of which a specified user is a member. 642 * 643 * @param int $user_id ID of the user. 644 * @param int $limit Optional. Max number of results to return. 645 * Default: false (no limit). 646 * @param int $page Optional. Page offset of results to return. 647 * Default: false (no limit). 648 * @return array { 649 * @type array $groups Array of groups returned by paginated query. 650 * @type int $total Count of groups matching query. 651 * } 652 */ 553 653 function groups_get_user_groups( $user_id = 0, $pag_num = 0, $pag_page = 0 ) { 554 654 … … 559 659 } 560 660 661 /** 662 * Get the count of groups of which the specified user is a member. 663 * 664 * @param int $user_id Optional. Default: ID of the displayed user. 665 * @return int Group count. 666 */ 561 667 function groups_total_groups_for_user( $user_id = 0 ) { 562 668 … … 573 679 574 680 /** 575 * Returns the group object for the group currently being viewed 576 * 577 * @package BuddyPress 578 * @since BuddyPress (1.5) 579 * 580 * @return BP_Groups_Group The current group object 681 * Get the BP_Groups_Group object corresponding to the current group. 682 * 683 * @since BuddyPress (1.5.0) 684 * 685 * @return BP_Groups_Group The current group object. 581 686 */ 582 687 function groups_get_current_group() { … … 588 693 } 589 694 590 /*** Group Avatars *************************************************************/ 591 695 /** Group Avatars *************************************************************/ 696 697 /** 698 * Generate the avatar upload directory path for a given group. 699 * 700 * @param int $group_id Optional. ID of the group. Default: ID of the 701 * current group. 702 * @return string 703 */ 592 704 function groups_avatar_upload_dir( $group_id = 0 ) { 593 705 global $bp; … … 609 721 } 610 722 611 /*** Group Member Status Checks ************************************************/ 612 723 /** Group Member Status Checks ************************************************/ 724 725 /** 726 * Check whether a user is an admin of a given group. 727 * 728 * @param int $user_id ID of the user. 729 * @param int $group_id ID of the group. 730 * @param int|null ID of the membership if the user is an admin, otherwise null. 731 */ 613 732 function groups_is_user_admin( $user_id, $group_id ) { 614 733 return BP_Groups_Member::check_is_admin( $user_id, $group_id ); 615 734 } 616 735 736 /** 737 * Check whether a user is a mod of a given group. 738 * 739 * @param int $user_id ID of the user. 740 * @param int $group_id ID of the group. 741 * @param int|null ID of the membership if the user is a mod, otherwise null. 742 */ 617 743 function groups_is_user_mod( $user_id, $group_id ) { 618 744 return BP_Groups_Member::check_is_mod( $user_id, $group_id ); 619 745 } 620 746 747 /** 748 * Check whether a user is a member of a given group. 749 * 750 * @param int $user_id ID of the user. 751 * @param int $group_id ID of the group. 752 * @param int|null ID of the membership if the user is a member, otherwise null. 753 */ 621 754 function groups_is_user_member( $user_id, $group_id ) { 622 755 return BP_Groups_Member::check_is_member( $user_id, $group_id ); … … 630 763 * Is the specified user the creator of the group? 631 764 * 632 * @param int $user_id633 * @param int $group_id634 765 * @since BuddyPress (1.2.6) 635 * @uses BP_Groups_Member 766 * 767 * @param int $user_id ID of the user. 768 * @param int $group_id ID of the group. 769 * @return int|null ID of the group if the user is the creator, otherwise false. 636 770 */ 637 771 function groups_is_user_creator( $user_id, $group_id ) { … … 639 773 } 640 774 641 /*** Group Activity Posting **************************************************/ 642 775 /** Group Activity Posting ****************************************************/ 776 777 /** 778 * Post an Activity status update affiliated with a group. 779 * 780 * @todo Should bail out when the Activity component is not active. 781 * 782 * @param array { 783 * Array of arguments. 784 * @type string $content The content of the update. 785 * @type int $user_id Optional. ID of the user posting the update. Default: 786 * ID of the logged-in user. 787 * @type int $group_id Optional. ID of the group to be affiliated with the 788 * update. Default: ID of the current group. 789 * } 790 * @return int 791 */ 643 792 function groups_post_update( $args = '' ) { 644 793 global $bp; … … 683 832 } 684 833 685 /*** Group Invitations *********************************************************/ 686 834 /** Group Invitations *********************************************************/ 835 836 /** 837 * Get IDs of users with outstanding invites to a given group from a specified user. 838 * 839 * @param int $user_id ID of the inviting user. 840 * @param int $group_id ID of the group. 841 * @return array IDs of users who have been invited to the group by the 842 * user but have not yet accepted. 843 */ 687 844 function groups_get_invites_for_user( $user_id = 0, $limit = false, $page = false, $exclude = false ) { 688 845 … … 694 851 695 852 /** 696 * Get sthe total group invite count for a user.853 * Get the total group invite count for a user. 697 854 * 698 855 * @since BuddyPress (2.0.0) 699 856 * 700 * @param int $user_id The user ID 857 * @param int $user_id The user ID. 701 858 * @return int 702 859 */ … … 709 866 } 710 867 868 /** 869 * Invite a user to a group. 870 * 871 * @param array $args { 872 * Array of arguments. 873 * @type int $user_id ID of the user being invited. 874 * @type int $group_id ID of the group to which the user is being invited. 875 * @type int $inviter_id Optional. ID of the inviting user. Default: 876 * ID of the logged-in user. 877 * @type string $date_modified Optional. Modified date for the invitation. 878 * Default: current date/time. 879 * @type bool $is_confirmed. Optional. Whether the invitation should be 880 * marked confirmed. Default: false. 881 * } 882 * @return bool True on success, false on failure. 883 */ 711 884 function groups_invite_user( $args = '' ) { 712 885 … … 747 920 } 748 921 922 /** 923 * Uninvite a user from a group. 924 * 925 * Functionally, this is equivalent to removing a user from a group. 926 * 927 * @param int $user_id ID of the user. 928 * @param int $group_id ID of the group. 929 * @return bool True on success, false on failure. 930 */ 749 931 function groups_uninvite_user( $user_id, $group_id ) { 750 932 … … 762 944 * Returns true if a user is already a member of the group. 763 945 * 764 * @param int $user_id 765 * @param int $group_id 766 * @return bool True when the user is a member of the group, otherwise false 946 * @param int $user_id ID of the user. 947 * @param int $group_id ID of the group. 948 * @return bool True when the user is a member of the group, otherwise false. 767 949 */ 768 950 function groups_accept_invite( $user_id, $group_id ) { … … 802 984 } 803 985 986 /** 987 * Reject a group invitation. 988 * 989 * @param int $user_id ID of the user. 990 * @param int $group_id ID of the group. 991 * @return bool True on success, false on failure. 992 */ 804 993 function groups_reject_invite( $user_id, $group_id ) { 805 994 if ( ! BP_Groups_Member::delete( $user_id, $group_id ) ) … … 811 1000 } 812 1001 1002 /** 1003 * Delete a group invitation. 1004 * 1005 * @param int $user_id ID of the invited user. 1006 * @param int $group_id ID of the group. 1007 * @return bool True on success, false on failure. 1008 */ 813 1009 function groups_delete_invite( $user_id, $group_id ) { 814 1010 if ( ! BP_Groups_Member::delete_invite( $user_id, $group_id ) ) … … 820 1016 } 821 1017 1018 /** 1019 * Send all pending invites by a single user to a specific group. 1020 * 1021 * @param int $user_id ID of the inviting user. 1022 * @param int $group_id ID of the group. 1023 */ 822 1024 function groups_send_invites( $user_id, $group_id ) { 823 1025 … … 847 1049 848 1050 /** 849 * Check to see whether a user has already been invited to a group 850 * 851 * By default, the function checks for invitations that have been sent. Entering 'all' as the $type 852 * parameter will return unsent invitations as well (useful to make sure AJAX requests are not 853 * duplicated) 854 * 855 * @package BuddyPress Groups 856 * 857 * @param int $user_id Potential group member 858 * @param int $group_id Potential group 859 * @param string $type Optional. Use 'sent' to check for sent invites, 'all' to check for all 860 * @return bool Returns true if an invitation is found 1051 * Check to see whether a user has already been invited to a group. 1052 * 1053 * By default, the function checks for invitations that have been sent. 1054 * Entering 'all' as the $type parameter will return unsent invitations as 1055 * well (useful to make sure AJAX requests are not duplicated). 1056 * 1057 * @param int $user_id ID of potential group member. 1058 * @param int $group_id ID of potential group. 1059 * @param string $type Optional. Use 'sent' to check for sent invites, 'all' to 1060 * check for all. Default: 'sent'. 1061 * @return bool True if an invitation is found, otherwise false. 861 1062 */ 862 1063 function groups_check_user_has_invite( $user_id, $group_id, $type = 'sent' ) { … … 864 1065 } 865 1066 1067 /** 1068 * Delete all invitations to a given group. 1069 * 1070 * @param int $group_id ID of the group whose invitations are being deleted. 1071 * @return int|null Number of rows records deleted on success, null on failure. 1072 */ 866 1073 function groups_delete_all_group_invites( $group_id ) { 867 1074 return BP_Groups_Group::delete_all_invites( $group_id ); 868 1075 } 869 1076 870 /*** Group Promotion & Banning *************************************************/ 871 1077 /** Group Promotion & Banning *************************************************/ 1078 1079 /** 1080 * Promote a member to a new status within a group. 1081 * 1082 * @param int $user_id ID of the user. 1083 * @param int $group_id ID of the group. 1084 * @param string $status The new status. 'mod' or 'admin'. 1085 * @return bool True on success, false on failure. 1086 */ 872 1087 function groups_promote_member( $user_id, $group_id, $status ) { 873 1088 … … 886 1101 } 887 1102 1103 /** 1104 * Demone a user to 'member' status within a group. 1105 * 1106 * @param int $user_id ID of the user. 1107 * @param int $group_id ID of the group. 1108 * @return bool True on success, false on failure. 1109 */ 888 1110 function groups_demote_member( $user_id, $group_id ) { 889 1111 … … 898 1120 } 899 1121 1122 /** 1123 * Ban a member from a group. 1124 * 1125 * @param int $user_id ID of the user. 1126 * @param int $group_id ID of the group. 1127 * @return bool True on success, false on failure. 1128 */ 900 1129 function groups_ban_member( $user_id, $group_id ) { 901 1130 … … 910 1139 } 911 1140 1141 /** 1142 * Unban a member from a group. 1143 * 1144 * @param int $user_id ID of the user. 1145 * @param int $group_id ID of the group. 1146 * @return bool True on success, false on failure. 1147 */ 912 1148 function groups_unban_member( $user_id, $group_id ) { 913 1149 … … 922 1158 } 923 1159 924 /*** Group Removal *******************************************************/ 925 1160 /** Group Removal *************************************************************/ 1161 1162 /** 1163 * Remove a member from a group. 1164 * 1165 * @param int $user_id ID of the user. 1166 * @param int $group_id ID of the group. 1167 * @return bool True on success, false on failure. 1168 */ 926 1169 function groups_remove_member( $user_id, $group_id ) { 927 1170 … … 936 1179 } 937 1180 938 /*** Group Membership ****************************************************/ 939 1181 /** Group Membership **********************************************************/ 1182 1183 /** 1184 * Create a group membership request. 1185 * 1186 * @param int $requesting_user_id ID of the user requesting membership. 1187 * @param int $group_id ID of the group. 1188 * @return bool True on success, false on failure. 1189 */ 940 1190 function groups_send_membership_request( $requesting_user_id, $group_id ) { 941 1191 … … 979 1229 } 980 1230 1231 /** 1232 * Accept a pending group membership request. 1233 * 1234 * @param int $membership_id ID of the membership object. 1235 * @param int $user_id Optional. ID of the user who requested membership. 1236 * Provide this value along with $group_id to override $membership_id. 1237 * @param int $group_id Optional. ID of the group to which membership is being 1238 * requested. Provide this value along with $user_id to override 1239 * $membership_id. 1240 * @return bool True on success, false on failure. 1241 */ 981 1242 function groups_accept_membership_request( $membership_id, $user_id = 0, $group_id = 0 ) { 982 1243 … … 1003 1264 } 1004 1265 1266 /** 1267 * Reject a pending group membership request. 1268 * 1269 * @param int $membership_id ID of the membership object. 1270 * @param int $user_id Optional. ID of the user who requested membership. 1271 * Provide this value along with $group_id to override $membership_id. 1272 * @param int $group_id Optional. ID of the group to which membership is being 1273 * requested. Provide this value along with $user_id to override 1274 * $membership_id. 1275 * @return bool True on success, false on failure. 1276 */ 1005 1277 function groups_reject_membership_request( $membership_id, $user_id = 0, $group_id = 0 ) { 1006 1278 if ( !$membership = groups_delete_membership_request( $membership_id, $user_id, $group_id ) ) { … … 1013 1285 } 1014 1286 1287 /** 1288 * Delete a pending group membership request. 1289 * 1290 * @param int $membership_id ID of the membership object. 1291 * @param int $user_id Optional. ID of the user who requested membership. 1292 * Provide this value along with $group_id to override $membership_id. 1293 * @param int $group_id Optional. ID of the group to which membership is being 1294 * requested. Provide this value along with $user_id to override 1295 * $membership_id. 1296 * @return bool True on success, false on failure. 1297 */ 1015 1298 function groups_delete_membership_request( $membership_id, $user_id = 0, $group_id = 0 ) { 1016 1299 if ( !empty( $user_id ) && !empty( $group_id ) ) … … 1025 1308 } 1026 1309 1310 /** 1311 * Check whether a user has an outstanding membership request for a given group. 1312 * 1313 * @param int $user_id ID of the user. 1314 * @param int $group_id ID of the group. 1315 * @return int|null ID of the membership if found, otherwise false. 1316 */ 1027 1317 function groups_check_for_membership_request( $user_id, $group_id ) { 1028 1318 return BP_Groups_Member::check_for_membership_request( $user_id, $group_id ); 1029 1319 } 1030 1320 1321 /** 1322 * Accept all pending membership requests to a group. 1323 * 1324 * @param int $group_id ID of the group. 1325 * @return bool True on success, false on failure. 1326 */ 1031 1327 function groups_accept_all_pending_membership_requests( $group_id ) { 1032 1328 $user_ids = BP_Groups_Member::get_all_membership_request_user_ids( $group_id ); … … 1043 1339 } 1044 1340 1045 /** * Group Meta****************************************************/1341 /** Group Meta ****************************************************************/ 1046 1342 1047 1343 /** … … 1144 1440 } 1145 1441 1146 /*** Group Cleanup Functions ****************************************************/ 1147 1442 /** Group Cleanup Functions ***************************************************/ 1443 1444 /** 1445 * Delete all group membership information for the specified user. 1446 * 1447 * @since BuddyPress (1.0.0) 1448 * 1449 * @param int $user_id ID of the user. 1450 */ 1148 1451 function groups_remove_data_for_user( $user_id ) { 1149 1452 BP_Groups_Member::delete_all_for_user( $user_id );
Note: See TracChangeset
for help on using the changeset viewer.