Skip to:
Content

BuddyPress.org

Changeset 7558


Ignore:
Timestamp:
11/11/2013 12:52:44 AM (10 years ago)
Author:
boonebgorges
Message:

Improve inline docs in bp-friends component. See #5022

Location:
trunk/bp-friends
Files:
4 edited

Legend:

Unmodified
Added
Removed

  • trunk/bp-friends/bp-friends-filters.php

    r6314 r7558  
    99
    1010/**
    11  * Filter BP_User_Query::populate_extras to override each queried users fullname
     11 * Filter BP_User_Query::populate_extras to override each queried users fullname.
    1212 *
    13  * @since BuddyPress (1.7)
     13 * @since BuddyPress (1.7.0)
    1414 *
    15  * @global BuddyPress $bp
    16  * @global WPDB $wpdb
    17  * @param BP_User_Query $user_query
    18  * @param string $user_ids_sql
     15 * @global BuddyPress $bp Global BuddyPress settings.
     16 * @global WPDB $wpdb WordPress database access object.
     17 *
     18 * @param BP_User_Query $user_query The BP_User_Query object.
     19 * @param string $user_ids_sql Comma-separated list of user IDs to fetch extra
     20 *        data for, as determined by BP_User_Query.
    1921 */
    2022function bp_friends_filter_user_query_populate_extras( BP_User_Query $user_query, $user_ids_sql ) {

  • trunk/bp-friends/bp-friends-functions.php

    r7530 r7558  
    1616if ( !defined( 'ABSPATH' ) ) exit;
    1717
     18/**
     19 * Create a new friendship.
     20 *
     21 * @param int $initiator_userid ID of the "initiator" user (the user who is
     22 *        sending the friendship request).
     23 * @param int $friend_userid ID of the "friend" user (the user whose friendship
     24 *        is being requested).
     25 * @param bool $force_accept Optional. Whether to force acceptance. When false,
     26 *        running friends_add_friend() will result in a friendship request.
     27 *        When true, running friends_add_friend() will result in an accepted
     28 *        friendship, with no notifications being sent. Default: false.
     29 * @return bool True on success, false on failure.
     30 */
    1831function friends_add_friend( $initiator_userid, $friend_userid, $force_accept = false ) {
    1932    global $bp;
    … …  
    5669}
    5770
     71/**
     72 * Remove a friendship.
     73 *
     74 * Will also delete the related "friendship_accepted" activity item.
     75 *
     76 * @param int $initiator_userid ID of the friendship initiator.
     77 * @param int $friend_userid ID of the friend user.
     78 * @return bool True on success, false on failure.
     79 */
    5880function friends_remove_friend( $initiator_userid, $friend_userid ) {
    5981
    … …  
    81103}
    82104
     105/**
     106 * Mark a friendship request as accepted.
     107 *
     108 * Also initiates a "friendship_accepted" activity item.
     109 *
     110 * @param int $friendship_id ID of the pending friendship object.
     111 * @return bool True on success, false on failure.
     112 */
    83113function friends_accept_friendship( $friendship_id ) {
    84114    global $bp;
    … …  
    128158}
    129159
     160/**
     161 * Mark a friendship request as rejected.
     162 *
     163 * @param int $friendship_id ID of the pending friendship object.
     164 * @return bool True on success, false on failure.
     165 */
    130166function friends_reject_friendship( $friendship_id ) {
    131167    global $bp;
    … …  
    145181}
    146182
     183/**
     184 * Withdraw a friendship request.
     185 *
     186 * @param int $initiator_userid ID of the friendship initiator - this is the
     187 *            user who requested the friendship, and is doing the withdrawing.
     188 * @param int $friend_userid ID of the requested friend.
     189 * @return bool True on success, false on failure.
     190 */
    147191function friends_withdraw_friendship( $initiator_userid, $friend_userid ) {
    148192    global $bp;
    … …  
    162206}
    163207
     208/**
     209 * Check whether two users are friends.
     210 *
     211 * @param int $user_id ID of the first user.
     212 * @param int $possible_friend_id ID of the other user.
     213 * @return bool Returns true if the two users are friends, otherwise false.
     214 */
    164215function friends_check_friendship( $user_id, $possible_friend_id ) {
    165216
    … …  
    170221}
    171222
    172 // Returns - 'is_friend', 'not_friends', 'pending'
     223/**
     224 * Get the friendship status of two friends.
     225 *
     226 * Will return 'is_friends', 'not_friends', or 'pending'.
     227 *
     228 * @param int $user_id ID of the first user.
     229 * @param int $possible_friend_id ID of the other user.
     230 * @return string Friend status of the two users.
     231 */
    173232function friends_check_friendship_status( $user_id, $possible_friend_id ) {
    174233    return BP_Friends_Friendship::check_is_friend( $user_id, $possible_friend_id );
    175234}
    176235
     236/**
     237 * Get the friend count of a given user.
     238 *
     239 * @param int $user_id ID of the user whose friends are being counted.
     240 * @return int Friend count of the user.
     241 */
    177242function friends_get_total_friend_count( $user_id = 0 ) {
    178243    if ( empty( $user_id ) )
    … …  
    186251}
    187252
     253/**
     254 * Check whether a given user has any friends.
     255 *
     256 * @param int $user_id ID of the user whose friends are being checked.
     257 * @return bool True if the user has friends, otherwise false.
     258 */
    188259function friends_check_user_has_friends( $user_id ) {
    189260    $friend_count = friends_get_total_friend_count( $user_id );
    … …  
    198269}
    199270
     271/**
     272 * Get the ID of two users' friendship, if it exists.
     273 *
     274 * @param int $initiator_user_id ID of the first user.
     275 * @param int $friend_user_id ID of the second user.
     276 * @return int|bool ID of the friendship if found, otherwise false.
     277 */
    200278function friends_get_friendship_id( $initiator_user_id, $friend_user_id ) {
    201279    return BP_Friends_Friendship::get_friendship_id( $initiator_user_id, $friend_user_id );
    202280}
    203281
     282/**
     283 * Get the IDs of a given user's friends.
     284 *
     285 * @param int $user_id ID of the user whose friends are being retreived.
     286 * @param bool $friend_requests_only Optional. Whether to fetch unaccepted
     287 *        requests only. Default: false.
     288 * @param bool $assoc_arr Optional. True to receive an array of arrays keyed as
     289 *        'user_id' => $user_id; false to get a one-dimensional array of user
     290 *        IDs. Default: false.
     291 */
    204292function friends_get_friend_user_ids( $user_id, $friend_requests_only = false, $assoc_arr = false ) {
    205293    return BP_Friends_Friendship::get_friend_user_ids( $user_id, $friend_requests_only, $assoc_arr );
    206294}
    207295
     296/**
     297 * Search the friends of a user by a search string.
     298 *
     299 * @param string $filter The search string, matched against xprofile fields (if
     300 *        available), or usermeta 'nickname' field.
     301 * @param int $user_id ID of the user whose friends are being searched.
     302 * @param int $limit Optional. Max number of friends to return.
     303 * @param int $page Optional. The page of results to return. Default: null (no
     304 *        pagination - return all results).
     305 * @return array|bool On success, an array: {
     306 *     @type array $friends IDs of friends returned by the query.
     307 *     @type int $count Total number of friends (disregarding
     308 *           pagination) who match the search.
     309 * }. Returns false on failure.
     310 */
    208311function friends_search_friends( $search_terms, $user_id, $pag_num = 10, $pag_page = 1 ) {
    209312    return BP_Friends_Friendship::search_friends( $search_terms, $user_id, $pag_num, $pag_page );
    210313}
    211314
     315/**
     316 * Get a list of IDs of users who have requested friendship of a given user.
     317 *
     318 * @param int $user_id The ID of the user who has received the friendship
     319 *        requests.
     320 * @return array|bool An array of user IDs, or false if none are found.
     321 */
    212322function friends_get_friendship_request_user_ids( $user_id ) {
    213323    return BP_Friends_Friendship::get_friendship_request_user_ids( $user_id );
    214324}
    215325
     326/**
     327 * Get a user's most recently active friends.
     328 *
     329 * @see BP_Core_User::get_users() for a description of return value.
     330 *
     331 * @param int $user_id ID of the user whose friends are being retreived.
     332 * @param int $per_page Optional. Number of results to return per page.
     333 *        Default: 0 (no pagination; show all results).
     334 * @param int $page Optional. Number of the page of results to return.
     335 *        Default: 0 (no pagination; show all results).
     336 * @param string $filter Optional. Limit results to those matching a search
     337 *        string.
     338 * @return array See {@link BP_Core_User::get_users()}.
     339 */
    216340function friends_get_recently_active( $user_id, $per_page = 0, $page = 0, $filter = '' ) {
    217341    return apply_filters( 'friends_get_recently_active', BP_Core_User::get_users( 'active', $per_page, $page, $user_id, $filter ) );
    218342}
    219343
     344/**
     345 * Get a user's friends, in alphabetical order.
     346 *
     347 * @see BP_Core_User::get_users() for a description of return value.
     348 *
     349 * @param int $user_id ID of the user whose friends are being retreived.
     350 * @param int $per_page Optional. Number of results to return per page.
     351 *        Default: 0 (no pagination; show all results).
     352 * @param int $page Optional. Number of the page of results to return.
     353 *        Default: 0 (no pagination; show all results).
     354 * @param string $filter Optional. Limit results to those matching a search
     355 *        string.
     356 * @return array See {@link BP_Core_User::get_users()}.
     357 */
    220358function friends_get_alphabetically( $user_id, $per_page = 0, $page = 0, $filter = '' ) {
    221359    return apply_filters( 'friends_get_alphabetically', BP_Core_User::get_users( 'alphabetical', $per_page, $page, $user_id, $filter ) );
    222360}
    223361
     362/**
     363 * Get a user's friends, in the order in which they joined the site.
     364 *
     365 * @see BP_Core_User::get_users() for a description of return value.
     366 *
     367 * @param int $user_id ID of the user whose friends are being retreived.
     368 * @param int $per_page Optional. Number of results to return per page.
     369 *        Default: 0 (no pagination; show all results).
     370 * @param int $page Optional. Number of the page of results to return.
     371 *        Default: 0 (no pagination; show all results).
     372 * @param string $filter Optional. Limit results to those matching a search
     373 *        string.
     374 * @return array See {@link BP_Core_User::get_users()}.
     375 */
    224376function friends_get_newest( $user_id, $per_page = 0, $page = 0, $filter = '' ) {
    225377    return apply_filters( 'friends_get_newest', BP_Core_User::get_users( 'newest', $per_page, $page, $user_id, $filter ) );
    226378}
    227379
     380/**
     381 * Get the last active date of many users at once.
     382 *
     383 * @see BP_Friends_Friendship::get_bulk_last_active() for a description of
     384 *      arguments and return value.
     385 *
     386 * @param array $user_ids See BP_Friends_Friendship::get_bulk_last_active().
     387 * @return array $user_ids See BP_Friends_Friendship::get_bulk_last_active().
     388 */
    228389function friends_get_bulk_last_active( $friend_ids ) {
    229390    return BP_Friends_Friendship::get_bulk_last_active( $friend_ids );
    … …  
    236397 * user is not a group admin.
    237398 *
    238  * @since BuddyPress (1.0)
    239  * @param int $user_id User ID whose friends to see can be invited
    240  * @param int $group_id Group to check possible invitations against
    241  * @return mixed False if no friends, array of users if friends
     399 * @since BuddyPress (1.0.0)
     400 *
     401 * @param int $user_id User ID whose friends to see can be invited. Default:
     402 *        ID of the logged-in user.
     403 * @param int $group_id Group to check possible invitations against.
     404 * @return mixed False if no friends, array of users if friends.
    242405 */
    243406function friends_get_friends_invite_list( $user_id = 0, $group_id = 0 ) {
    … …  
    304467}
    305468
     469/**
     470 * Get a count of a user's friends who can be invited to a given group.
     471 *
     472 * Users can invite any of their friends except:
     473 *
     474 * - users who are already in the group
     475 * - users who have a pending invite to the group
     476 * - users who have been banned from the group
     477 *
     478 * @param int $user_id ID of the user whose friends are being counted.
     479 * @param int $group_id ID of the group friends are being invited to.
     480 * @return int $invitable_count Eligible friend count.
     481 */
    306482function friends_count_invitable_friends( $user_id, $group_id ) {
    307483    return BP_Friends_Friendship::get_invitable_friend_count( $user_id, $group_id );
    308484}
    309485
     486/**
     487 * Get a total friend count for a given user.
     488 *
     489 * @param int $user_id Optional. ID of the user whose friendships you are
     490 *        counting. Default: displayed user (if any), otherwise logged-in user.
     491 * @return int Friend count for the user.
     492 */
    310493function friends_get_friend_count_for_user( $user_id ) {
    311494    return BP_Friends_Friendship::total_friend_count( $user_id );
    312495}
    313496
     497/**
     498 * Return a list of a user's friends, filtered by a search term.
     499 *
     500 * @param string $search_terms Search term to filter on.
     501 * @param int $user_id ID of the user whose friends are being searched.
     502 * @param int $pag_num Number of results to return per page. Default: 0 (no
     503 *        pagination - show all results).
     504 * @param int $pag_num Number of the page being requested. Default: 0 (no
     505 *        pagination - show all results).
     506 * @return array Array of BP_Core_User objects corresponding to friends.
     507 */
    314508function friends_search_users( $search_terms, $user_id, $pag_num = 0, $pag_page = 0 ) {
    315509
    … …  
    326520}
    327521
     522/**
     523 * Has a friendship been confirmed (accepted)?
     524 *
     525 * @param int $friendship_id The ID of the friendship being checked.
     526 * @return bool True if the friendship is confirmed, otherwise false.
     527 */
    328528function friends_is_friendship_confirmed( $friendship_id ) {
    329529    $friendship = new BP_Friends_Friendship( $friendship_id );
    … …  
    331531}
    332532
     533/**
     534 * Update user friend counts.
     535 *
     536 * Friend counts are cached in usermeta for performance reasons. After a
     537 * friendship event (acceptance, deletion), call this function to regenerate
     538 * the cached values.
     539 *
     540 * @param int $initiator_user_id ID of the first user.
     541 * @param int $friend_user_id ID of the second user.
     542 * @param string $status Optional. The friendship event that's been triggered.
     543 *        'add' will ++ each user's friend counts, while any other string
     544 *        will --.
     545 */
    333546function friends_update_friend_totals( $initiator_user_id, $friend_user_id, $status = 'add' ) {
    334547
    … …  
    342555}
    343556
     557/**
     558 * Remove all friends-related data concerning a given user.
     559 *
     560 * Removes the following:
     561 *
     562 * - Friendships of which the user is a member
     563 * - Cached friend count for the user
     564 * - Notifications of friendship requests sent by the user
     565 *
     566 * @param int $user_id ID of the user whose friend data is being removed.
     567 */
    344568function friends_remove_data( $user_id ) {
    345569    global $bp;

  • trunk/bp-friends/bp-friends-loader.php

    r7494 r7558  
    33 * BuddyPress Friends Streams Loader
    44 *
    5  * The friends component is for users to create relationships with each other
     5 * The friends component is for users to create relationships with each other.
    66 *
    77 * @package BuddyPress
    8  * @subpackage Friends Core
     8 * @subpackage Friends
    99 */
    1010
    … …  
    1515
    1616    /**
    17      * Start the friends component creation process
    18      *
    19      * @since BuddyPress (1.5)
     17     * Start the friends component creation process.
     18     *
     19     * @since BuddyPress (1.5.0)
    2020     */
    2121    function __construct() {
    … …  
    3131
    3232    /**
    33      * Include files
     33     * Include bp-friends files.
     34     *
     35     * @see BP_Component::includes() for description of parameters.
     36     *
     37     * @param array $includes See {@link BP_Component::includes()}.
    3438     */
    3539    public function includes( $includes = array() ) {
    … …  
    5054
    5155    /**
    52      * Setup globals
     56     * Set up bp-friends global settings.
    5357     *
    5458     * The BP_FRIENDS_SLUG constant is deprecated, and only used here for
    5559     * backwards compatibility.
    5660     *
    57      * @since BuddyPress (1.5)
     61     * @since BuddyPress (1.5.0)
     62     *
     63     * @see BP_Component::setup_globals() for description of parameters.
     64     *
     65     * @param array $args See {@link BP_Component::setup_globals()}.
    5866     */
    5967    public function setup_globals( $args = array() ) {
    … …  
    9098
    9199    /**
    92      * Setup BuddyBar navigation
     100     * Set up component navigation.
     101     *
     102     * @since BuddyPress (1.5.0)
     103     *
     104     * @see BP_Component::setup_nav() for a description of arguments.
     105     *
     106     * @param array $main_nav Optional. See BP_Component::setup_nav() for
     107     *        description.
     108     * @param array $sub_nav Optional. See BP_Component::setup_nav() for
     109     *        description.
    93110     */
    94111    public function setup_nav( $main_nav = array(), $sub_nav = array() ) {
    … …  
    141158
    142159    /**
    143      * Set up the Toolbar
     160     * Set up bp-friends integration with the WordPress admin bar.
     161     *
     162     * @since BuddyPress (1.5.0)
     163     *
     164     * @see BP_Component::setup_admin_bar() for a description of arguments.
     165     *
     166     * @param array $wp_admin_nav See BP_Component::setup_admin_bar()
     167     *        for description.
    144168     */
    145169    public function setup_admin_bar( $wp_admin_nav = array() ) {
    … …  
    192216
    193217    /**
    194      * Sets up the title for pages and <title>
     218     * Set up the title for pages and <title>.
    195219     */
    196220    function setup_title() {
    … …  
    215239}
    216240
     241/**
     242 * Set up the bp-forums component.
     243 */
    217244function bp_setup_friends() {
    218245    buddypress()->friends = new BP_Friends_Component();

  • trunk/bp-friends/bp-friends-notifications.php

    r6917 r7558  
    1414if ( !defined( 'ABSPATH' ) ) exit;
    1515
     16/**
     17 * Send notifications related to a new friendship request.
     18 *
     19 * When a friendship is requested, an email and a BP notification are sent to
     20 * the user of whom friendship has been requested ($friend_id).
     21 *
     22 * @param int $friendship_id ID of the friendship object.
     23 * @param int $initiator_id ID of the user who initiated the request.
     24 * @param int $friend_id ID of the request recipient.
     25 */
    1626function friends_notification_new_request( $friendship_id, $initiator_id, $friend_id ) {
    1727
    … …  
    5565}
    5666
     67/**
     68 * Send notifications related to the acceptance of a friendship request.
     69 *
     70 * When a friendship request is accepted, an email and a BP notification are
     71 * sent to the user who requested the friendship ($initiator_id).
     72 *
     73 * @param int $friendship_id ID of the friendship object.
     74 * @param int $initiator_id ID of the user who initiated the request.
     75 * @param int $friend_id ID of the request recipient.
     76 */
    5777function friends_notification_accepted_request( $friendship_id, $initiator_id, $friend_id ) {
    5878
Note: See TracChangeset for help on using the changeset viewer.