Skip to:
Content

BuddyPress.org

Changeset 7556


Ignore:
Timestamp:
11/10/2013 02:43:45 AM (11 years ago)
Author:
boonebgorges
Message:

Improve inline docs in bp-friends. See #5022

Location:
trunk/bp-friends
Files:
4 edited

Legend:

Unmodified
Added
Removed

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

    r6342 r7556  
    44 * BuddyPress Friends Actions
    55 *
    6  * Action functions are exactly the same as screen functions, however they do not
    7  * have a template screen associated with them. Usually they will send the user
    8  * back to the default screen after execution.
     6 * Action functions are exactly the same as screen functions, however they do
     7 * not have a template screen associated with them. Usually they will send the
     8 * user back to the default screen after execution.
    99 *
    1010 * @package BuddyPress
    … …  
    1515if ( !defined( 'ABSPATH' ) ) exit;
    1616
     17/**
     18 * Catch and process friendship requests.
     19 */
    1720function friends_action_add_friend() {
    1821    if ( !bp_is_friends_component() || !bp_is_current_action( 'add-friend' ) )
    … …  
    5053add_action( 'bp_init', 'friends_action_add_friend' );
    5154
     55/**
     56 * Catch and process Remove Friendship requests.
     57 */
    5258function friends_action_remove_friend() {
    5359    if ( !bp_is_friends_component() || !bp_is_current_action( 'remove-friend' ) )

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

    r7228 r7556  
    1414if ( !defined( 'ABSPATH' ) ) exit;
    1515
     16/**
     17 * Record an activity item related to the Friends component.
     18 *
     19 * A wrapper for {@link bp_activity_add()} that provides some Friends-specific
     20 * defaults.
     21 *
     22 * @see bp_activity_add() for more detailed description of parameters and
     23 *      return values.
     24 *
     25 * @param array $args {
     26 *     An array of arguments for the new activity item. Accepts all parameters
     27 *     of {@link bp_activity_add()}. The one difference is the following
     28 *     argument, which has a different default here:
     29 *     @type string $component Default: the id of your Friends component
     30 *           (usually 'friends').
     31 * }
     32 * @return bool See {@link bp_activity_add()}.
     33 */
    1634function friends_record_activity( $args = '' ) {
    1735    global $bp;
    … …  
    3957}
    4058
     59/**
     60 * Delete an activity item related to the Friends component.
     61 *
     62 * @param array $args {
     63 *     An array of arguments for the item to delete.
     64 *     @type int $item_id ID of the 'item' associated with the activity item.
     65 *           For Friends activity items, this is usually the user ID of one
     66 *           of the friends.
     67 *     @type string $type The 'type' of the activity item (eg
     68 *           'friendship_accepted').
     69 *     @type int $user_id ID of the user associated with the activity item.
     70 * }
     71 * @return bool True on success, false on failure.
     72 */
    4173function friends_delete_activity( $args ) {
    4274    global $bp;
    … …  
    4880}
    4981
     82/**
     83 * Register the activity actions for bp-friends.
     84 */
    5085function friends_register_activity_actions() {
    5186    global $bp;
    … …  
    66101
    67102/**
    68  * Format the BuddyBar/Toolbar notifications for the Friends component
     103 * Notification formatting callback for bp-friends notifications.
    69104 *
    70  * @package BuddyPress
    71  *
    72  * @param string $action The kind of notification being rendered
    73  * @param int $item_id The primary item id
    74  * @param int $secondary_item_id The secondary item id
    75  * @param int $total_items The total number of messaging-related notifications waiting for the user
    76  * @param string $format 'string' for BuddyBar-compatible notifications; 'array' for WP Toolbar
     105 * @param string $action The kind of notification being rendered.
     106 * @param int $item_id The primary item ID.
     107 * @param int $secondary_item_id The secondary item ID.
     108 * @param int $total_items The total number of messaging-related notifications
     109 *        waiting for the user.
     110 * @param string $format 'string' for BuddyBar-compatible notifications;
     111 *        'array' for WP Toolbar. Default: 'string'.
     112 * @return array|string
    77113 */
    78114function friends_format_notifications( $action, $item_id, $secondary_item_id, $total_items, $format = 'string' ) {

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

    r7537 r7556  
    22
    33/**
    4  * BuddyPress Friends Caching
     4 * BuddyPress Friends Caching.
    55 *
    66 * Caching functions handle the clearing of cached objects and pages on specific
    … …  
    1515if ( !defined( 'ABSPATH' ) ) exit;
    1616
     17/**
     18 * Clear friends-related cache for members of a specific friendship.
     19 *
     20 * @param int $friendship_id ID of the friendship whose two members should
     21 *        have their friends cache busted.
     22 */
    1723function friends_clear_friend_object_cache( $friendship_id ) {
    1824    if ( !$friendship = new BP_Friends_Friendship( $friendship_id ) )
    … …  
    2329}
    2430
     31/**
     32 * Clear friend-related notifications when ?new=1.
     33 */
    2534function friends_clear_friend_notifications() {
    2635    if ( isset( $_GET['new'] ) ) {

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

    r7521 r7556  
    1010if ( !defined( 'ABSPATH' ) ) exit;
    1111
     12/**
     13 * BuddyPress Friendship object.
     14 */
    1215class BP_Friends_Friendship {
     16
     17    /**
     18     * ID of the friendship.
     19     *
     20     * @access public
     21     * @var int
     22     */
    1323    public $id;
     24
     25    /**
     26     * User ID of the friendship initiator.
     27     *
     28     * @access public
     29     * @var int
     30     */
    1431    public $initiator_user_id;
     32
     33    /**
     34     * User ID of the 'friend' - the one invited to the friendship.
     35     *
     36     * @access public
     37     * @var int
     38     */
    1539    public $friend_user_id;
     40
     41    /**
     42     * Has the friendship been confirmed/accepted?
     43     *
     44     * @access public
     45     * @var int
     46     */
    1647    public $is_confirmed;
     48
     49    /**
     50     * Is this a "limited" friendship?
     51     *
     52     * Not currently used by BuddyPress.
     53     *
     54     * @access public
     55     * @var int
     56     */
    1757    public $is_limited;
     58
     59    /**
     60     * Date the friendship was created.
     61     *
     62     * @access public
     63     * @var string
     64     */
    1865    public $date_created;
    1966
     67    /**
     68     * Is this a request?
     69     *
     70     * Not currently used in BuddyPress.
     71     *
     72     * @access public
     73     * @var unknown
     74     */
    2075    public $is_request;
     76
     77    /**
     78     * Should additional friend details be queried?
     79     *
     80     * @access public
     81     * @var bool
     82     */
    2183    public $populate_friend_details;
    2284
     85    /**
     86     * Details about the friend.
     87     *
     88     * @access public
     89     * @var BP_Core_User
     90     */
    2391    public $friend;
    2492
     93    /**
     94     * Constructor method.
     95     *
     96     * @param int $id Optional. The ID of an existing friendship.
     97     * @param bool $is_request Deprecated.
     98     * @param bool $populate_friend_details True if friend details should
     99     *        be queried.
     100     */
    25101    public function __construct( $id = null, $is_request = false, $populate_friend_details = true ) {
    26102        $this->is_request = $is_request;
    … …  
    33109    }
    34110
     111    /**
     112     * Set up data about the current friendship.
     113     */
    35114    public function populate() {
    36115        global $wpdb, $bp;
    … …  
    53132    }
    54133
     134    /**
     135     * Save the current friendship to the database.
     136     *
     137     * @return bool True on success, false on failure.
     138     */
    55139    public function save() {
    56140        global $wpdb, $bp;
    … …  
    86170    /** Static Methods ********************************************************/
    87171
     172    /**
     173     * Get the IDs of a given user's friends.
     174     *
     175     * @param int $user_id ID of the user whose friends are being retreived.
     176     * @param bool $friend_requests_only Optional. Whether to fetch
     177     *        unaccepted requests only. Default: false.
     178     * @param bool $assoc_arr Optional. True to receive an array of arrays
     179     *        keyed as 'user_id' => $user_id; false to get a one-dimensional
     180     *        array of user IDs. Default: false.
     181     */
    88182    public static function get_friend_user_ids( $user_id, $friend_requests_only = false, $assoc_arr = false ) {
    89183        global $wpdb, $bp;
    … …  
    111205    }
    112206
     207    /**
     208     * Get the ID of the friendship object, if any, between a pair of users.
     209     *
     210     * @param int $user_id The ID of the first user.
     211     * @param int $friend_id The ID of the second user.
     212     * @return int|bool The ID of the friendship object if found, otherwise
     213     *         false.
     214     */
    113215    public static function get_friendship_id( $user_id, $friend_id ) {
    114216        global $wpdb, $bp;
    … …  
    117219    }
    118220
     221    /**
     222     * Get a list of IDs of users who have requested friendship of a given user.
     223     *
     224     * @param int $user_id The ID of the user who has received the
     225     *        friendship requests.
     226     * @return array|bool An array of user IDs, or false if none are found.
     227     */
    119228    public static function get_friendship_request_user_ids( $user_id ) {
    120229        global $wpdb, $bp;
    … …  
    123232    }
    124233
     234    /**
     235     * Get a total friend count for a given user.
     236     *
     237     * @param int $user_id Optional. ID of the user whose friendships you
     238     *        are counting. Default: displayed user (if any), otherwise
     239     *        logged-in user.
     240     * @return int Friend count for the user.
     241     */
    125242    public static function total_friend_count( $user_id = 0 ) {
    126243        global $wpdb, $bp;
    … …  
    143260    }
    144261
     262    /**
     263     * Search the friends of a user by a search string.
     264     *
     265     * @param string $filter The search string, matched against xprofile
     266     *        fields (if available), or usermeta 'nickname' field.
     267     * @param int $user_id ID of the user whose friends are being searched.
     268     * @param int $limit Optional. Max number of friends to return.
     269     * @param int $page Optional. The page of results to return. Default:
     270     *        null (no pagination - return all results).
     271     * @return array|bool On success, an array: {
     272     *     @type array $friends IDs of friends returned by the query.
     273     *     @type int $count Total number of friends (disregarding
     274     *           pagination) who match the search.
     275     * }. Returns false on failure.
     276     */
    145277    public static function search_friends( $filter, $user_id, $limit = null, $page = null ) {
    146278        global $wpdb, $bp;
    … …  
    185317
    186318    /**
    187      * Check friendship status between two users
     319     * Check friendship status between two users.
    188320     *
    189321     * Note that 'pending' means that $initiator_userid has sent a friend
    … …  
    192324     * sent the initial request)
    193325     *
    194      * @param int $initiator_userid The id of the user who is the initiator
    195      *   of the potential friendship/request.
    196      * @param int $possible_friend_userid The id of the user who is the
    197      *   recipient of the potential friendship/request.
     326     * @param int $initiator_userid The ID of the user who is the initiator
     327     *        of the potential friendship/request.
     328     * @param int $possible_friend_userid The ID of the user who is the
     329     *        recipient of the potential friendship/request.
    198330     * @return string The friendship status, from among 'not_friends',
    199      *   'is_friend', 'pending', and 'awaiting_response'
     331     *        'is_friend', 'pending', and 'awaiting_response'.
    200332     */
    201333    public static function check_is_friend( $initiator_userid, $possible_friend_userid ) {
    … …  
    221353    }
    222354
     355    /**
     356     * Get the last active date of many users at once.
     357     *
     358     * @todo Why is this in the Friends component?
     359     *
     360     * @param array $user_ids IDs of users whose last_active meta is
     361     *        being queried.
     362     * @return array Array of last_active values + user_ids.
     363     */
    223364    public static function get_bulk_last_active( $user_ids ) {
    224365        global $wpdb;
    … …  
    229370    }
    230371
     372    /**
     373     * Mark a friendship as accepted.
     374     *
     375     * @param int $friendship_id ID of the friendship to be accepted.
     376     * @return int Number of database rows updated.
     377     */
    231378    public static function accept($friendship_id) {
    232379        global $wpdb, $bp;
    … …  
    234381    }
    235382
     383    /**
     384     * Remove a friendship or a friendship request INITIATED BY the logged-in user.
     385     *
     386     * @param int $friendship_id ID of the friendship to be withdrawn.
     387     * @return int Number of database rows deleted.
     388     */
    236389    public static function withdraw($friendship_id) {
    237390        global $wpdb, $bp;
    … …  
    239392    }
    240393
     394    /**
     395     * Remove a friendship or a friendship request MADE OF the logged-in user.
     396     *
     397     * @param int $friendship_id ID of the friendship to be rejected.
     398     * @return int Number of database rows deleted.
     399     */
    241400    public static function reject($friendship_id) {
    242401        global $wpdb, $bp;
    … …  
    244403    }
    245404
     405    /**
     406     * Search users.
     407     *
     408     * @todo Why does this exist, and why is it in bp-friends?
     409     *
     410     * @param string $filter String to search by.
     411     * @param int $user_id A user ID param that is unused.
     412     * @param int $limit Optional. Max number of records to return.
     413     * @param int $page Optional. Number of the page to return. Default:
     414     *        false (no pagination - return all results).
     415     * @return array $filtered_ids IDs of users who match the query.
     416     */
    246417    public static function search_users( $filter, $user_id, $limit = null, $page = null ) {
    247418        global $wpdb, $bp;
    … …  
    271442    }
    272443
     444    /**
     445     * Get a count of users who match a search term.
     446     *
     447     * @todo Why does this exist, and why is it in bp-friends?
     448     *
     449     * @param string $filter Search term.
     450     * @return int Count of users matching the search term.
     451     */
    273452    public static function search_users_count( $filter ) {
    274453        global $wpdb, $bp;
    … …  
    294473    }
    295474
     475    /**
     476     * Sort a list of user IDs by their display names.
     477     *
     478     * @todo Why does this exist, and why is it in bp-friends?
     479     *
     480     * @param array $user_ids Array of user IDs.
     481     * @return array User IDs, sorted by the associated display names.
     482     */
    296483    public static function sort_by_name( $user_ids ) {
    297484        global $wpdb, $bp;
    … …  
    305492    }
    306493
     494    /**
     495     * Get a list of random friend IDs.
     496     *
     497     * @param int $user_id ID of the user whose friends are being retrieved.
     498     * @param int $total_friends Optional. Number of random friends to get.
     499     *        Default: 5.
     500     * @return array|bool An array of random friend user IDs on success;
     501     *         false if none are found.
     502     */
    307503    public static function get_random_friends( $user_id, $total_friends = 5 ) {
    308504        global $wpdb, $bp;
    … …  
    323519    }
    324520
     521    /**
     522     * Get a count of a user's friends who can be invited to a given group.
     523     *
     524     * Users can invite any of their friends except:
     525     *
     526     * - users who are already in the group
     527     * - users who have a pending invite to the group
     528     * - users who have been banned from the group
     529     *
     530     * @param int $user_id ID of the user whose friends are being counted.
     531     * @param int $group_id ID of the group friends are being invited to.
     532     * @return int $invitable_count Eligible friend count.
     533     */
    325534    public static function get_invitable_friend_count( $user_id, $group_id ) {
    326535
    … …  
    350559    }
    351560
     561    /**
     562     * Get the friend user IDs for a given friendship.
     563     *
     564     * @param int $friendship_id ID of the friendship.
     565     * @return object friend_user_id and initiator_user_id.
     566     */
    352567    public static function get_user_ids_for_friendship( $friendship_id ) {
    353568        global $wpdb, $bp;
    … …  
    355570    }
    356571
     572    /**
     573     * Delete all friendships and friend notifications related to a user.
     574     *
     575     * @param int $user_id ID of the user being expunged.
     576     */
    357577    public static function delete_all_for_user( $user_id ) {
    358578        global $wpdb, $bp;
Note: See TracChangeset for help on using the changeset viewer.