Skip to:
Content

BuddyPress.org


Ignore:
Timestamp:
11/22/2015 04:58:34 AM (9 years ago)
Author:
tw2113
Message:

More docs cleanup for BP-Groups component.

See #6401.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/bp-groups/bp-groups-functions.php

    r10351 r10373  
    3636 *
    3737 * @param array|string $args {
    38  *  Array of al arguments.
    39  *  @type int  $group_id        ID of the group.
    40  *  @type bool $load_users      No longer used.
    41  *  @type bool $populate_extras Whether to fetch membership data and other
    42  *                              extra information about the group.
    43  *                              Default: false.
     38 *     Array of al arguments.
     39 *     @type int  $group_id        ID of the group.
     40 *     @type bool $load_users      No longer used.
     41 *     @type bool $populate_extras Whether to fetch membership data and other
     42 *                                 extra information about the group.
     43 *                                 Default: false.
    4444 * }
    4545 * @return BP_Groups_Group $group The group object.
    … …  
    8484 *     @type string   $slug         The group slug.
    8585 *     @type string   $status       The group's status. Accepts 'public', 'private' or
    86                                     'hidden'. Defaults to 'public'.
     86 *                                  'hidden'. Defaults to 'public'.
    8787 *     @type int      $enable_forum Optional. Whether the group has a forum enabled.
    8888 *                                  If the legacy forums are enabled for this group
    … …  
    110110    extract( $args, EXTR_SKIP );
    111111
    112     // Pass an existing group ID
     112    // Pass an existing group ID.
    113113    if ( ! empty( $group_id ) ) {
    114114        $group = groups_get_group( array( 'group_id' => (int) $group_id ) );
    … …  
    117117        $description = ! empty( $description ) ? $description : $group->description;
    118118
    119         // Groups need at least a name
     119        // Groups need at least a name.
    120120        if ( empty( $name ) ) {
    121121            return false;
    122122        }
    123123
    124     // Create a new group
     124    // Create a new group.
    125125    } else {
    126         // Instantiate new group object
     126        // Instantiate new group object.
    127127        $group = new BP_Groups_Group;
    128128    }
    129129
    130     // Set creator ID
     130    // Set creator ID.
    131131    if ( $creator_id ) {
    132132        $group->creator_id = (int) $creator_id;
    … …  
    139139    }
    140140
    141     // Validate status
     141    // Validate status.
    142142    if ( ! groups_is_valid_status( $status ) ) {
    143143        return false;
    144144    }
    145145
    146     // Set group name
     146    // Set group name.
    147147    $group->name         = $name;
    148148    $group->description  = $description;
    … …  
    152152    $group->date_created = $date_created;
    153153
    154     // Save group
     154    // Save group.
    155155    if ( ! $group->save() ) {
    156156        return false;
    157157    }
    158158
    159     // If this is a new group, set up the creator as the first member and admin
     159    // If this is a new group, set up the creator as the first member and admin.
    160160    if ( empty( $group_id ) ) {
    161161        $member                = new BP_Groups_Member;
    … …  
    217217 * @param bool   $notify_members Whether to send an email notification to group
    218218 *                               members about changes in these details.
    219  *
    220219 * @return bool True on success, false on failure.
    221220 */
    … …  
    263262 * @param string|bool $invite_status Optional. Who is allowed to send invitations
    264263 *                                   to the group. 'members', 'mods', or 'admins'.
    265  *
    266264 * @return bool True on success, false on failure.
    267265 */
    … …  
    271269    $group->enable_forum = $enable_forum;
    272270
    273     /***
     271    /**
    274272     * Before we potentially switch the group status, if it has been changed to public
    275273     * from private and there are outstanding membership requests, auto-accept those requests.
    … …  
    278276        groups_accept_all_pending_membership_requests( $group->id );
    279277
    280     // Now update the status
     278    // Now update the status.
    281279    $group->status = $status;
    282280
    … …  
    291289    }
    292290
    293     // Set the invite status
     291    // Set the invite status.
    294292    if ( $invite_status )
    295293        groups_update_groupmeta( $group->id, 'invite_status', $invite_status );
    … …  
    315313 *
    316314 * @param int $group_id ID of the group to delete.
    317  *
    318315 * @return bool True on success, false on failure.
    319316 */
    … …  
    329326    do_action( 'groups_before_delete_group', $group_id );
    330327
    331     // Get the group object
     328    // Get the group object.
    332329    $group = groups_get_group( array( 'group_id' => $group_id ) );
    333330
    334     // Bail if group cannot be deleted
     331    // Bail if group cannot be deleted.
    335332    if ( ! $group->delete() ) {
    336333        return false;
    337334    }
    338335
    339     // Remove all outstanding invites for this group
     336    // Remove all outstanding invites for this group.
    340337    groups_delete_all_group_invites( $group_id );
    341338
    … …  
    356353 *
    357354 * @param string $status Status to check.
    358  *
    359355 * @return bool True if status is allowed, otherwise false.
    360356 */
    … …  
    369365 *
    370366 * @param string $slug Group slug to check.
    371  *
    372367 * @return string $slug A unique and sanitized slug.
    373368 */
    … …  
    395390 *
    396391 * @param int $group_id The numeric ID of the group.
    397  *
    398392 * @return string The group's slug.
    399393 */
    … …  
    409403 *
    410404 * @param string $group_slug The group's slug.
    411  *
    412405 * @return int The ID.
    413406 */
    … …  
    424417 * @param int $user_id  Optional. ID of the user. Defaults to the currently
    425418 *                      logged-in user.
    426  *
    427419 * @return bool True on success, false on failure.
    428420 */
    … …  
    465457 * @param int $user_id  Optional. ID of the user. Defaults to the currently
    466458 *                      logged-in user.
    467  *
    468459 * @return bool True on success, false on failure.
    469460 */
    … …  
    481472        groups_delete_membership_request( null, $user_id, $group_id );
    482473
    483     // User is already a member, just return true
     474    // User is already a member, just return true.
    484475    if ( groups_is_user_member( $user_id, $group_id ) )
    485476        return true;
    … …  
    504495        $group = $bp->groups->current_group;
    505496
    506     // Record this in activity streams
     497    // Record this in activity streams.
    507498    groups_record_activity( array(
    508499        'type'    => 'joined_group',
    … …  
    530521 *
    531522 * @param int $group_id ID of the group.
    532  *
    533523 * @return array Info about group admins (user_id + date_modified).
    534524 */
    … …  
    541531 *
    542532 * @param int $group_id ID of the group.
    543  *
    544533 * @return array Info about group admins (user_id + date_modified).
    545534 */
    … …  
    580569function groups_get_group_members( $args = array() ) {
    581570
    582     // Backward compatibility with old method of passing arguments
     571    // Backward compatibility with old method of passing arguments.
    583572    if ( ! is_array( $args ) || func_num_args() > 1 ) {
    584573        _deprecated_argument( __METHOD__, '2.0.0', sprintf( __( 'Arguments passed to %1$s should be in an associative array. See the inline documentation at %2$s for more details.', 'buddypress' ), __METHOD__, __FILE__ ) );
    … …  
    612601    // For legacy users. Use of BP_Groups_Member::get_all_for_group()
    613602    // is deprecated. func_get_args() can't be passed to a function in PHP
    614     // 5.2.x, so we create a variable
     603    // 5.2.x, so we create a variable.
    615604    $func_args = func_get_args();
    616605    if ( apply_filters( 'bp_use_legacy_group_member_query', false, __FUNCTION__, $func_args ) ) {
    … …  
    618607    } else {
    619608
    620         // exclude_admins_mods and exclude_banned are legacy arguments.
    621         // Convert to group_role
     609        // Both exclude_admins_mods and exclude_banned are legacy arguments.
     610        // Convert to group_role.
    622611        if ( empty( $r['group_role'] ) ) {
    623612            $r['group_role'] = array( 'member' );
    … …  
    633622        }
    634623
    635         // Perform the group member query (extends BP_User_Query)
     624        // Perform the group member query (extends BP_User_Query).
    636625        $members = new BP_Group_Member_Query( array(
    637626            'group_id'       => $r['group_id'],
    … …  
    644633        ) );
    645634
    646         // Structure the return value as expected by the template functions
     635        // Structure the return value as expected by the template functions.
    647636        $retval = array(
    648637            'members' => array_values( $members->results ),
    … …  
    658647 *
    659648 * @param int $group_id Group ID.
    660  *
    661649 * @return int Count of confirmed members for the group.
    662650 */
    … …  
    682670
    683671    $defaults = array(
    684         'type'              => false,    // active, newest, alphabetical, random, popular, most-forum-topics or most-forum-posts
    685         'order'             => 'DESC',   // 'ASC' or 'DESC'
    686         'orderby'           => 'date_created', // date_created, last_activity, total_member_count, name, random
    687         'user_id'           => false,    // Pass a user_id to limit to only groups that this user is a member of
    688         'include'           => false,    // Only include these specific groups (group_ids)
    689         'exclude'           => false,    // Do not include these specific groups (group_ids)
    690         'search_terms'      => false,    // Limit to groups that match these search terms
    691         'meta_query'        => false,    // Filter by groupmeta. See WP_Meta_Query for syntax
    692         'show_hidden'       => false,    // Show hidden groups to non-admins
    693         'per_page'          => 20,       // The number of results to return per page
    694         'page'              => 1,        // The page to return if limiting per page
    695         'populate_extras'   => true,     // Fetch meta such as is_banned and is_member
    696         'update_meta_cache' => true,   // Pre-fetch groupmeta for queried groups
     672        'type'              => false,          // Active, newest, alphabetical, random, popular, most-forum-topics or most-forum-posts.
     673        'order'             => 'DESC',         // 'ASC' or 'DESC'
     674        'orderby'           => 'date_created', // date_created, last_activity, total_member_count, name, random.
     675        'user_id'           => false,          // Pass a user_id to limit to only groups that this user is a member of.
     676        'include'           => false,          // Only include these specific groups (group_ids).
     677        'exclude'           => false,          // Do not include these specific groups (group_ids).
     678        'search_terms'      => false,          // Limit to groups that match these search terms.
     679        'meta_query'        => false,          // Filter by groupmeta. See WP_Meta_Query for syntax.
     680        'show_hidden'       => false,          // Show hidden groups to non-admins.
     681        'per_page'          => 20,             // The number of results to return per page.
     682        'page'              => 1,              // The page to return if limiting per page.
     683        'populate_extras'   => true,           // Fetch meta such as is_banned and is_member.
     684        'update_meta_cache' => true,           // Pre-fetch groupmeta for queried groups.
    697685    );
    698686
    … …  
    769757 *
    770758 * @param int $user_id Optional. Default: ID of the displayed user.
    771  *
    772759 * @return int Group count.
    773760 */
    … …  
    816803 * Generate the avatar upload directory path for a given group.
    817804 *
    818  * @param int $group_id Optional. ID of the group. Default: ID of the
    819  *                      current group.
     805 * @param int $group_id Optional. ID of the group. Default: ID of the current group.
    820806 * @return string
    821807 */
    … …  
    857843 * @param int $user_id ID of the user.
    858844 * @param int $group_id ID of the group.
    859  *
    860845 * @return bool
    861846 */
    … …  
    869854 * @param int $user_id ID of the user.
    870855 * @param int $group_id ID of the group.
    871  *
    872856 * @return bool
    873857 */
    … …  
    881865 * @param int $user_id ID of the user.
    882866 * @param int $group_id ID of the group.
    883  *
    884867 * @return bool
    885868 */
    … …  
    899882 * @param int $user_id ID of the user.
    900883 * @param int $group_id ID of the group.
    901  *
    902884 * @return bool
    903885 */
    … …  
    947929        return false;
    948930
    949     // Record this in activity streams
     931    // Record this in activity streams.
    950932    $activity_action  = sprintf( __( '%1$s posted an update in the group %2$s', 'buddypress'), bp_core_get_userlink( $user_id ), '<a href="' . bp_get_group_permalink( $bp->groups->current_group ) . '">' . esc_attr( $bp->groups->current_group->name ) . '</a>' );
    951933    $activity_content = $content;
    … …  
    1000982 *
    1001983 * @param int               $user_id ID of the inviting user.
    1002  * @param int|bool          $limit Limit to restrict to.
    1003  * @param int|bool          $page
    1004  * @param string|array|bool $exclude
    1005  *
     984 * @param int|bool          $limit   Limit to restrict to.
     985 * @param int|bool          $page    Optional. Page offset of results to return.
     986 * @param string|array|bool $exclude Array of comma-separated list of group IDs
     987 *                                   to exclude from results.
    1006988 * @return array $value IDs of users who have been invited to the group by the
    1007989 *                      user but have not yet accepted.
    … …  
    10211003 *
    10221004 * @param int $user_id The user ID.
    1023  *
    10241005 * @return int
    10251006 */
    … …  
    10641045        return false;
    10651046
    1066     // if the user has already requested membership, accept the request
     1047    // If the user has already requested membership, accept the request.
    10671048    if ( $membership_id = groups_check_for_membership_request( $user_id, $group_id ) ) {
    10681049        groups_accept_membership_request( $membership_id, $user_id, $group_id );
    10691050
    1070     // Otherwise, create a new invitation
     1051    // Otherwise, create a new invitation.
    10711052    } elseif ( ! groups_is_user_member( $user_id, $group_id ) && ! groups_check_user_has_invite( $user_id, $group_id, 'all' ) ) {
    10721053        $invite                = new BP_Groups_Member;
    … …  
    11001081 * @param int $user_id  ID of the user.
    11011082 * @param int $group_id ID of the group.
    1102  *
    11031083 * @return bool True on success, false on failure.
    11041084 */
    … …  
    11281108 * @param int $user_id  ID of the user.
    11291109 * @param int $group_id ID of the group.
    1130  *
    11311110 * @return bool True when the user is a member of the group, otherwise false.
    11321111 */
    … …  
    11341113
    11351114    // If the user is already a member (because BP at one point allowed two invitations to
    1136     // slip through), delete all existing invitations/requests and return true
     1115    // slip through), delete all existing invitations/requests and return true.
    11371116    if ( groups_is_user_member( $user_id, $group_id ) ) {
    11381117        if ( groups_check_user_has_invite( $user_id, $group_id ) ) {
    … …  
    11541133    }
    11551134
    1156     // Remove request to join
     1135    // Remove request to join.
    11571136    if ( $member->check_for_membership_request( $user_id, $group_id ) ) {
    11581137        $member->delete_request( $user_id, $group_id );
    11591138    }
    11601139
    1161     // Modify group meta
     1140    // Modify group meta.
    11621141    groups_update_groupmeta( $group_id, 'last_activity', bp_core_current_time() );
    11631142
    … …  
    11801159 * @param int $user_id  ID of the user.
    11811160 * @param int $group_id ID of the group.
    1182  *
    11831161 * @return bool True on success, false on failure.
    11841162 */
    … …  
    12051183 * @param int $user_id  ID of the invited user.
    12061184 * @param int $group_id ID of the group.
    1207  *
    12081185 * @return bool True on success, false on failure.
    12091186 */
    … …  
    12431220        $member = new BP_Groups_Member( $invited_users[$i], $group_id );
    12441221
    1245         // Send the actual invite
     1222        // Send the actual invite.
    12461223        groups_notification_group_invites( $group, $member, $user_id );
    12471224
    … …  
    12681245 * @param int $user_id  ID of the inviting user.
    12691246 * @param int $group_id ID of the group.
    1270  *
    12711247 * @return array $value IDs of users who have been invited to the group by the
    12721248 *                      user but have not yet accepted.
    … …  
    12871263 * @param string $type     Optional. Use 'sent' to check for sent invites,
    12881264 *                         'all' to check for all. Default: 'sent'.
    1289  *
    12901265 * @return bool True if an invitation is found, otherwise false.
    12911266 */
    … …  
    12981273 *
    12991274 * @param int $group_id ID of the group whose invitations are being deleted.
    1300  *
    13011275 * @return int|null Number of rows records deleted on success, null on failure.
    13021276 */
    … …  
    13131287 * @param int    $group_id ID of the group.
    13141288 * @param string $status   The new status. 'mod' or 'admin'.
    1315  *
    13161289 * @return bool True on success, false on failure.
    13171290 */
    … …  
    13451318 * @param int $user_id  ID of the user.
    13461319 * @param int $group_id ID of the group.
    1347  *
    13481320 * @return bool True on success, false on failure.
    13491321 */
    … …  
    13731345 * @param int $user_id  ID of the user.
    13741346 * @param int $group_id ID of the group.
    1375  *
    13761347 * @return bool True on success, false on failure.
    13771348 */
    … …  
    14011372 * @param int $user_id  ID of the user.
    14021373 * @param int $group_id ID of the group.
    1403  *
    14041374 * @return bool True on success, false on failure.
    14051375 */
    … …  
    14311401 * @param int $user_id  ID of the user.
    14321402 * @param int $group_id ID of the group.
    1433  *
    14341403 * @return bool True on success, false on failure.
    14351404 */
    … …  
    14621431 * @param int $requesting_user_id ID of the user requesting membership.
    14631432 * @param int $group_id           ID of the group.
    1464  *
    14651433 * @return bool True on success, false on failure.
    14661434 */
    14671435function groups_send_membership_request( $requesting_user_id, $group_id ) {
    14681436
    1469     // Prevent duplicate requests
     1437    // Prevent duplicate requests.
    14701438    if ( groups_check_for_membership_request( $requesting_user_id, $group_id ) )
    14711439        return false;
    14721440
    1473     // Check if the user is already a member or is banned
     1441    // Check if the user is already a member or is banned.
    14741442    if ( groups_is_user_member( $requesting_user_id, $group_id ) || groups_is_user_banned( $requesting_user_id, $group_id ) )
    14751443        return false;
    14761444
    1477     // Check if the user is already invited - if so, simply accept invite
     1445    // Check if the user is already invited - if so, simply accept invite.
    14781446    if ( groups_check_user_has_invite( $requesting_user_id, $group_id ) ) {
    14791447        groups_accept_invite( $requesting_user_id, $group_id );
    … …  
    14941462        $admins = groups_get_group_admins( $group_id );
    14951463
    1496         // Saved okay, now send the email notification
     1464        // Saved okay, now send the email notification.
    14971465        for ( $i = 0, $count = count( $admins ); $i < $count; ++$i )
    14981466            groups_notification_new_membership_request( $requesting_user_id, $admins[$i]->user_id, $group_id, $requesting_user->id );
    … …  
    15261494 *                           requested. Provide this value along with $user_id to
    15271495 *                           override $membership_id.
    1528  *
    15291496 * @return bool True on success, false on failure.
    15301497 */
    … …  
    15721539 *                           requested. Provide this value along with $user_id to
    15731540 *                           override $membership_id.
    1574  *
    15751541 * @return bool True on success, false on failure.
    15761542 */
    … …  
    16041570 *                           requested. Provide this value along with $user_id to
    16051571 *                           override $membership_id.
    1606  *
    16071572 * @return bool True on success, false on failure.
    16081573 */
    … …  
    16241589 * @param int $user_id  ID of the user.
    16251590 * @param int $group_id ID of the group.
    1626  *
    16271591 * @return int|null ID of the membership if found, otherwise false.
    16281592 */
    … …  
    16351599 *
    16361600 * @param int $group_id ID of the group.
    1637  *
    16381601 * @return bool True on success, false on failure.
    16391602 */
    … …  
    16721635 *                                metadata entries for the specified group.
    16731636 *                                Default: false.
    1674  *
    16751637 * @return bool True on success, false on failure.
    16761638 */
    … …  
    16781640    global $wpdb;
    16791641
    1680     // Legacy - if no meta_key is passed, delete all for the item
     1642    // Legacy - if no meta_key is passed, delete all for the item.
    16811643    if ( empty( $meta_key ) ) {
    16821644        $keys = $wpdb->get_col( $wpdb->prepare( "SELECT meta_key FROM {$wpdb->groupmeta} WHERE group_id = %d", $group_id ) );
    16831645
    1684         // With no meta_key, ignore $delete_all
     1646        // With no meta_key, ignore $delete_all.
    16851647        $delete_all = false;
    16861648    } else {
    … …  
    17081670 *                         specified meta_key. This parameter has no effect if
    17091671 *                         meta_key is empty.
    1710  *
    17111672 * @return mixed Metadata value.
    17121673 */
    … …  
    17281689 *                           metadata entries with the specified value.
    17291690 *                           Otherwise, update all entries.
    1730  *
    17311691 * @return bool|int $retval Returns false on failure. On successful update of existing
    17321692 *                          metadata, returns true. On successful creation of new metadata,
    … …  
    17531713 *                           has a value for the key, no change will be made.
    17541714 *                           Default: false.
    1755  *
    17561715 * @return int|bool The meta ID on successful update, false on failure.
    17571716 */
Note: See TracChangeset for help on using the changeset viewer.