Skip to:
Content

BuddyPress.org


Ignore:
Timestamp:
09/17/2014 01:49:22 AM (5 years ago)
Author:
boonebgorges
Message:

Improved inline documentation in bp-groups

See #5022

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/bp-groups/bp-groups-functions.php

    r8662 r9027  
    1717
    1818/**
    19  * Checks $bp pages global and looks for directory page
    20  *
    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)
    2222 *
    2323 * @global BuddyPress $bp The one true BuddyPress instance
     
    3131
    3232/**
    33  * Pulls up the database object corresponding to a group
     33 * Fetch a single group object.
    3434 *
    3535 * When calling up a group object, you should always use this function instead
     
    3737 * support and pass through the groups_get_group filter.
    3838 *
    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.
    4146 */
    4247function groups_get_group( $args = '' ) {
     
    5661}
    5762
    58 /*** Group Creation, Editing & Deletion *****************************************/
     63/** Group Creation, Editing & Deletion ****************************************/
    5964
    6065/**
     
    164169}
    165170
     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 */
    166184function groups_edit_base_group_details( $group_id, $group_name, $group_desc, $notify_members ) {
    167185
     
    185203}
    186204
     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 */
    187218function groups_edit_group_settings( $group_id, $enable_forum, $status, $invite_status = false ) {
    188219
     
    221252
    222253/**
    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.
    228260 */
    229261function groups_delete_group( $group_id ) {
     
    247279}
    248280
     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 */
    249287function groups_is_valid_status( $status ) {
    250288    global $bp;
     
    253291}
    254292
     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 */
    255299function groups_check_slug( $slug ) {
    256300    global $bp;
     
    273317
    274318/**
    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.
    279323 */
    280324function groups_get_slug( $group_id ) {
     
    284328
    285329/**
    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.
    292336 */
    293337function groups_get_id( $group_slug ) {
     
    295339}
    296340
    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 */
    299351function groups_leave_group( $group_id, $user_id = 0 ) {
    300352    global $bp;
     
    323375}
    324376
     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 */
    325385function groups_join_group( $group_id, $user_id = 0 ) {
    326386    global $bp;
     
    373433}
    374434
    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 */
    377443function groups_get_group_admins( $group_id ) {
    378444    return BP_Groups_Member::get_group_administrator_ids( $group_id );
    379445}
    380446
     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 */
    381453function groups_get_group_mods( $group_id ) {
    382454    return BP_Groups_Member::get_group_moderator_ids( $group_id );
     
    489561}
    490562
     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 */
    491569function groups_get_total_member_count( $group_id ) {
    492570    return BP_Groups_Group::get_total_member_count( $group_id );
    493571}
    494572
    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()}.
    504586 */
    505587function groups_get_groups( $args = '' ) {
     
    542624}
    543625
     626/**
     627 * Get the total group count for the site.
     628 *
     629 * @return int
     630 */
    544631function groups_get_total_group_count() {
    545632    if ( !$count = wp_cache_get( 'bp_total_group_count', 'bp' ) ) {
     
    551638}
    552639
     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 */
    553653function groups_get_user_groups( $user_id = 0, $pag_num = 0, $pag_page = 0 ) {
    554654
     
    559659}
    560660
     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 */
    561667function groups_total_groups_for_user( $user_id = 0 ) {
    562668
     
    573679
    574680/**
    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.
    581686 */
    582687function groups_get_current_group() {
     
    588693}
    589694
    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 */
    592704function groups_avatar_upload_dir( $group_id = 0 ) {
    593705    global $bp;
     
    609721}
    610722
    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 */
    613732function groups_is_user_admin( $user_id, $group_id ) {
    614733    return BP_Groups_Member::check_is_admin( $user_id, $group_id );
    615734}
    616735
     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 */
    617743function groups_is_user_mod( $user_id, $group_id ) {
    618744    return BP_Groups_Member::check_is_mod( $user_id, $group_id );
    619745}
    620746
     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 */
    621754function groups_is_user_member( $user_id, $group_id ) {
    622755    return BP_Groups_Member::check_is_member( $user_id, $group_id );
     
    630763 * Is the specified user the creator of the group?
    631764 *
    632  * @param int $user_id
    633  * @param int $group_id
    634765 * @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.
    636770 */
    637771function groups_is_user_creator( $user_id, $group_id ) {
     
    639773}
    640774
    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 */
    643792function groups_post_update( $args = '' ) {
    644793    global $bp;
     
    683832}
    684833
    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 */
    687844function groups_get_invites_for_user( $user_id = 0, $limit = false, $page = false, $exclude = false ) {
    688845
     
    694851
    695852/**
    696  * Gets the total group invite count for a user.
     853 * Get the total group invite count for a user.
    697854 *
    698855 * @since BuddyPress (2.0.0)
    699856 *
    700  * @param int $user_id The user ID
     857 * @param int $user_id The user ID.
    701858 * @return int
    702859 */
     
    709866}
    710867
     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 */
    711884function groups_invite_user( $args = '' ) {
    712885
     
    747920}
    748921
     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 */
    749931function groups_uninvite_user( $user_id, $group_id ) {
    750932
     
    762944 * Returns true if a user is already a member of the group.
    763945 *
    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.
    767949 */
    768950function groups_accept_invite( $user_id, $group_id ) {
     
    802984}
    803985
     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 */
    804993function groups_reject_invite( $user_id, $group_id ) {
    805994    if ( ! BP_Groups_Member::delete( $user_id, $group_id ) )
     
    8111000}
    8121001
     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 */
    8131009function groups_delete_invite( $user_id, $group_id ) {
    8141010    if ( ! BP_Groups_Member::delete_invite( $user_id, $group_id ) )
     
    8201016}
    8211017
     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 */
    8221024function groups_send_invites( $user_id, $group_id ) {
    8231025
     
    8471049
    8481050/**
    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.
    8611062 */
    8621063function groups_check_user_has_invite( $user_id, $group_id, $type = 'sent' ) {
     
    8641065}
    8651066
     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 */
    8661073function groups_delete_all_group_invites( $group_id ) {
    8671074    return BP_Groups_Group::delete_all_invites( $group_id );
    8681075}
    8691076
    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 */
    8721087function groups_promote_member( $user_id, $group_id, $status ) {
    8731088
     
    8861101}
    8871102
     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 */
    8881110function groups_demote_member( $user_id, $group_id ) {
    8891111
     
    8981120}
    8991121
     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 */
    9001129function groups_ban_member( $user_id, $group_id ) {
    9011130
     
    9101139}
    9111140
     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 */
    9121148function groups_unban_member( $user_id, $group_id ) {
    9131149
     
    9221158}
    9231159
    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 */
    9261169function groups_remove_member( $user_id, $group_id ) {
    9271170
     
    9361179}
    9371180
    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 */
    9401190function groups_send_membership_request( $requesting_user_id, $group_id ) {
    9411191
     
    9791229}
    9801230
     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 */
    9811242function groups_accept_membership_request( $membership_id, $user_id = 0, $group_id = 0 ) {
    9821243
     
    10031264}
    10041265
     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 */
    10051277function groups_reject_membership_request( $membership_id, $user_id = 0, $group_id = 0 ) {
    10061278    if ( !$membership = groups_delete_membership_request( $membership_id, $user_id, $group_id ) ) {
     
    10131285}
    10141286
     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 */
    10151298function groups_delete_membership_request( $membership_id, $user_id = 0, $group_id = 0 ) {
    10161299    if ( !empty( $user_id ) && !empty( $group_id ) )
     
    10251308}
    10261309
     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 */
    10271317function groups_check_for_membership_request( $user_id, $group_id ) {
    10281318    return BP_Groups_Member::check_for_membership_request( $user_id, $group_id );
    10291319}
    10301320
     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 */
    10311327function groups_accept_all_pending_membership_requests( $group_id ) {
    10321328    $user_ids = BP_Groups_Member::get_all_membership_request_user_ids( $group_id );
     
    10431339}
    10441340
    1045 /*** Group Meta ****************************************************/
     1341/** Group Meta ****************************************************************/
    10461342
    10471343/**
     
    11441440}
    11451441
    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 */
    11481451function groups_remove_data_for_user( $user_id ) {
    11491452    BP_Groups_Member::delete_all_for_user( $user_id );
Note: See TracChangeset for help on using the changeset viewer.