[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * BuddyPress Friends Functions.
   4   *
   5   * Functions are where all the magic happens in BuddyPress. They will
   6   * handle the actual saving or manipulation of information. Usually they will
   7   * hand off to a database class for data access, then return
   8   * true or false on success or failure.
   9   *
  10   * @package BuddyPress
  11   * @subpackage FriendsFunctions
  12   * @since 1.5.0
  13   */
  14  
  15  // Exit if accessed directly.
  16  defined( 'ABSPATH' ) || exit;
  17  
  18  /**
  19   * Create a new friendship.
  20   *
  21   * @since 1.0.0
  22   *
  23   * @param int  $initiator_userid ID of the "initiator" user (the user who is
  24   *                               sending the friendship request).
  25   * @param int  $friend_userid    ID of the "friend" user (the user whose friendship
  26   *                               is being requested).
  27   * @param bool $force_accept     Optional. Whether to force acceptance. When false,
  28   *                               running friends_add_friend() will result in a friendship request.
  29   *                               When true, running friends_add_friend() will result in an accepted
  30   *                               friendship, with no notifications being sent. Default: false.
  31   * @return bool True on success, false on failure.
  32   */
  33  function friends_add_friend( $initiator_userid, $friend_userid, $force_accept = false ) {
  34  
  35      // You cannot be friends with yourself!
  36      if ( $initiator_userid == $friend_userid ) {
  37          return false;
  38      }
  39  
  40      // Check if already friends, and bail if so.
  41      if ( friends_check_friendship( $initiator_userid, $friend_userid ) ) {
  42          return true;
  43      }
  44  
  45      // Setup the friendship data.
  46      $friendship = new BP_Friends_Friendship;
  47      $friendship->initiator_user_id = (int) $initiator_userid;
  48      $friendship->friend_user_id    = (int) $friend_userid;
  49      $friendship->is_confirmed      = 0;
  50      $friendship->is_limited        = 0;
  51      $friendship->date_created      = bp_core_current_time();
  52  
  53      if ( ! empty( $force_accept ) ) {
  54          $friendship->is_confirmed = 1;
  55      }
  56  
  57      // Bail if friendship could not be saved (how sad!).
  58      if ( ! $friendship->save() ) {
  59          return false;
  60      }
  61  
  62      // Send notifications.
  63      if ( empty( $force_accept ) ) {
  64          $action = 'requested';
  65  
  66      // Update friend totals.
  67      } else {
  68          $action = 'accepted';
  69          friends_update_friend_totals( $friendship->initiator_user_id, $friendship->friend_user_id, 'add' );
  70      }
  71  
  72      /**
  73       * Fires at the end of initiating a new friendship connection.
  74       *
  75       * This is a variable hook, depending on context.
  76       * The two potential hooks are: friends_friendship_requested, friends_friendship_accepted.
  77       *
  78       * @since 1.0.0
  79       *
  80       * @param int    $id                ID of the pending friendship connection.
  81       * @param int    $initiator_user_id ID of the friendship initiator.
  82       * @param int    $friend_user_id    ID of the friend user.
  83       * @param object $friendship        BuddyPress Friendship Object.
  84       */
  85      do_action( 'friends_friendship_' . $action, $friendship->id, $friendship->initiator_user_id, $friendship->friend_user_id, $friendship );
  86  
  87      return true;
  88  }
  89  
  90  /**
  91   * Remove a friendship.
  92   *
  93   * Will also delete the related "friendship_accepted" activity item.
  94   *
  95   * @since 1.0.0
  96   *
  97   * @param int $initiator_userid ID of the friendship initiator.
  98   * @param int $friend_userid    ID of the friend user.
  99   * @return bool True on success, false on failure.
 100   */
 101  function friends_remove_friend( $initiator_userid, $friend_userid ) {
 102  
 103      $friendship_id = BP_Friends_Friendship::get_friendship_id( $initiator_userid, $friend_userid );
 104      $friendship    = new BP_Friends_Friendship( $friendship_id );
 105  
 106      /**
 107       * Fires before the deletion of a friendship activity item
 108       * for the user who canceled the friendship.
 109       *
 110       * @since 1.5.0
 111       *
 112       * @param int $friendship_id    ID of the friendship object, if any, between a pair of users.
 113       * @param int $initiator_userid ID of the friendship initiator.
 114       * @param int $friend_userid    ID of the friend user.
 115       */
 116      do_action( 'friends_before_friendship_delete', $friendship_id, $initiator_userid, $friend_userid );
 117  
 118      /**
 119       * Fires before the friendship connection is removed.
 120       *
 121       * This hook is misleadingly named - the friendship is not yet deleted.
 122       * This is your last chance to do something while the friendship exists.
 123       *
 124       * @since 1.0.0
 125       *
 126       * @param int $friendship_id    ID of the friendship object, if any, between a pair of users.
 127       * @param int $initiator_userid ID of the friendship initiator.
 128       * @param int $friend_userid    ID of the friend user.
 129       */
 130      do_action( 'friends_friendship_deleted', $friendship_id, $initiator_userid, $friend_userid );
 131  
 132      if ( $friendship->delete() ) {
 133          friends_update_friend_totals( $initiator_userid, $friend_userid, 'remove' );
 134  
 135          /**
 136           * Fires after the friendship connection is removed.
 137           *
 138           * @since 1.8.0
 139           *
 140           * @param int $initiator_userid ID of the friendship initiator.
 141           * @param int $friend_userid    ID of the friend user.
 142           */
 143          do_action( 'friends_friendship_post_delete', $initiator_userid, $friend_userid );
 144  
 145          return true;
 146      }
 147  
 148      return false;
 149  }
 150  
 151  /**
 152   * Mark a friendship request as accepted.
 153   *
 154   * Also initiates a "friendship_accepted" activity item.
 155   *
 156   * @since 1.0.0
 157   *
 158   * @param int $friendship_id ID of the pending friendship object.
 159   * @return bool True on success, false on failure.
 160   */
 161  function friends_accept_friendship( $friendship_id ) {
 162  
 163      // Get the friendship data.
 164      $friendship = new BP_Friends_Friendship( $friendship_id, true, false );
 165  
 166      // Accepting friendship.
 167      if ( empty( $friendship->is_confirmed ) && BP_Friends_Friendship::accept( $friendship_id ) ) {
 168  
 169          // Bump the friendship counts.
 170          friends_update_friend_totals( $friendship->initiator_user_id, $friendship->friend_user_id );
 171  
 172          /**
 173           * Fires after a friendship is accepted.
 174           *
 175           * @since 1.0.0
 176           *
 177           * @param int    $id                ID of the pending friendship object.
 178           * @param int    $initiator_user_id ID of the friendship initiator.
 179           * @param int    $friend_user_id    ID of the user requested friendship with.
 180           * @param object $friendship        BuddyPress Friendship Object.
 181           */
 182          do_action( 'friends_friendship_accepted', $friendship->id, $friendship->initiator_user_id, $friendship->friend_user_id, $friendship );
 183  
 184          return true;
 185      }
 186  
 187      return false;
 188  }
 189  
 190  /**
 191   * Mark a friendship request as rejected.
 192   *
 193   * @since 1.0.0
 194   *
 195   * @param int $friendship_id ID of the pending friendship object.
 196   * @return bool True on success, false on failure.
 197   */
 198  function friends_reject_friendship( $friendship_id ) {
 199      $friendship = new BP_Friends_Friendship( $friendship_id, true, false );
 200  
 201      if ( empty( $friendship->is_confirmed ) && BP_Friends_Friendship::reject( $friendship_id ) ) {
 202  
 203          /**
 204           * Fires after a friendship request is rejected.
 205           *
 206           * @since 1.0.0
 207           *
 208           * @param int                   $friendship_id ID of the pending friendship.
 209           * @param BP_Friends_Friendship $friendships Friendship object. Passed by reference.
 210           */
 211          do_action_ref_array( 'friends_friendship_rejected', array( $friendship_id, &$friendship ) );
 212          return true;
 213      }
 214  
 215      return false;
 216  }
 217  
 218  /**
 219   * Withdraw a friendship request.
 220   *
 221   * @since 1.6.0
 222   *
 223   * @param int $initiator_userid ID of the friendship initiator - this is the
 224   *                              user who requested the friendship, and is doing the withdrawing.
 225   * @param int $friend_userid    ID of the requested friend.
 226   * @return bool True on success, false on failure.
 227   */
 228  function friends_withdraw_friendship( $initiator_userid, $friend_userid ) {
 229      $friendship_id = BP_Friends_Friendship::get_friendship_id( $initiator_userid, $friend_userid );
 230      $friendship    = new BP_Friends_Friendship( $friendship_id, true, false );
 231  
 232      if ( empty( $friendship->is_confirmed ) && BP_Friends_Friendship::withdraw( $friendship_id ) ) {
 233  
 234          // @deprecated Since 1.9
 235          do_action_ref_array( 'friends_friendship_whithdrawn', array( $friendship_id, &$friendship ) );
 236  
 237          /**
 238           * Fires after a friendship request has been withdrawn.
 239           *
 240           * @since 1.9.0
 241           *
 242           * @param int                   $friendship_id ID of the friendship.
 243           * @param BP_Friends_Friendship $friendship    Friendship object. Passed by reference.
 244           */
 245          do_action_ref_array( 'friends_friendship_withdrawn',  array( $friendship_id, &$friendship ) );
 246  
 247          return true;
 248      }
 249  
 250      return false;
 251  }
 252  
 253  /**
 254   * Check whether two users are friends.
 255   *
 256   * @since 1.0.0
 257   *
 258   * @param int $user_id            ID of the first user.
 259   * @param int $possible_friend_id ID of the other user.
 260   * @return bool Returns true if the two users are friends, otherwise false.
 261   */
 262  function friends_check_friendship( $user_id, $possible_friend_id ) {
 263  
 264      if ( 'is_friend' == BP_Friends_Friendship::check_is_friend( $user_id, $possible_friend_id ) )
 265          return true;
 266  
 267      return false;
 268  }
 269  
 270  /**
 271   * Get the friendship status of two friends.
 272   *
 273   * Will return 'is_friends', 'not_friends', 'pending' or 'awaiting_response'.
 274   *
 275   * @since 1.2.0
 276   *
 277   * @param int $user_id            ID of the first user.
 278   * @param int $possible_friend_id ID of the other user.
 279   * @return string Friend status of the two users.
 280   */
 281  function friends_check_friendship_status( $user_id, $possible_friend_id ) {
 282      global $members_template;
 283  
 284      // Check the BP_User_Query first
 285      // @see bp_friends_filter_user_query_populate_extras().
 286      if ( ! empty( $members_template->in_the_loop ) ) {
 287          if ( isset( $members_template->member->friendship_status ) ) {
 288              return $members_template->member->friendship_status;
 289          }
 290      }
 291  
 292      return BP_Friends_Friendship::check_is_friend( $user_id, $possible_friend_id );
 293  }
 294  
 295  /**
 296   * Get the friend count of a given user.
 297   *
 298   * @since 1.2.0
 299   *
 300   * @param int $user_id ID of the user whose friends are being counted.
 301   * @return int Friend count of the user.
 302   */
 303  function friends_get_total_friend_count( $user_id = 0 ) {
 304      if ( empty( $user_id ) )
 305          $user_id = ( bp_displayed_user_id() ) ? bp_displayed_user_id() : bp_loggedin_user_id();
 306  
 307      $count = bp_get_user_meta( $user_id, 'total_friend_count', true );
 308      if ( empty( $count ) )
 309          $count = 0;
 310  
 311      /**
 312       * Filters the total friend count for a given user.
 313       *
 314       * @since 1.2.0
 315       *
 316       * @param int $count Total friend count for a given user.
 317       */
 318      return apply_filters( 'friends_get_total_friend_count', $count );
 319  }
 320  
 321  /**
 322   * Check whether a given user has any friends.
 323   *
 324   * @since 1.0.0
 325   *
 326   * @param int $user_id ID of the user whose friends are being checked.
 327   * @return bool True if the user has friends, otherwise false.
 328   */
 329  function friends_check_user_has_friends( $user_id ) {
 330      $friend_count = friends_get_total_friend_count( $user_id );
 331  
 332      if ( empty( $friend_count ) )
 333          return false;
 334  
 335      if ( !(int) $friend_count )
 336          return false;
 337  
 338      return true;
 339  }
 340  
 341  /**
 342   * Get the ID of two users' friendship, if it exists.
 343   *
 344   * @since 1.2.0
 345   *
 346   * @param int $initiator_user_id ID of the first user.
 347   * @param int $friend_user_id    ID of the second user.
 348   * @return int|null ID of the friendship if found, otherwise false.
 349   */
 350  function friends_get_friendship_id( $initiator_user_id, $friend_user_id ) {
 351      return BP_Friends_Friendship::get_friendship_id( $initiator_user_id, $friend_user_id );
 352  }
 353  
 354  /**
 355   * Get the IDs of a given user's friends.
 356   *
 357   * @since 1.0.0
 358   *
 359   * @param int  $user_id              ID of the user whose friends are being retrieved.
 360   * @param bool $friend_requests_only Optional. Whether to fetch unaccepted
 361   *                                   requests only. Default: false.
 362   * @param bool $assoc_arr            Optional. True to receive an array of arrays keyed as
 363   *                                   'user_id' => $user_id; false to get a one-dimensional
 364   *                                   array of user IDs. Default: false.
 365   * @return array
 366   */
 367  function friends_get_friend_user_ids( $user_id, $friend_requests_only = false, $assoc_arr = false ) {
 368      return BP_Friends_Friendship::get_friend_user_ids( $user_id, $friend_requests_only, $assoc_arr );
 369  }
 370  
 371  /**
 372   * Search the friends of a user by a search string.
 373   *
 374   * @since 1.0.0
 375   *
 376   * @param string $search_terms The search string, matched against xprofile fields (if
 377   *                             available), or usermeta 'nickname' field.
 378   * @param int    $user_id      ID of the user whose friends are being searched.
 379   * @param int    $pag_num      Optional. Max number of friends to return.
 380   * @param int    $pag_page     Optional. The page of results to return. Default: null (no
 381   *                             pagination - return all results).
 382   * @return array|bool On success, an array: {
 383   *     @type array $friends IDs of friends returned by the query.
 384   *     @type int   $count   Total number of friends (disregarding
 385   *                          pagination) who match the search.
 386   * }. Returns false on failure.
 387   */
 388  function friends_search_friends( $search_terms, $user_id, $pag_num = 10, $pag_page = 1 ) {
 389      return BP_Friends_Friendship::search_friends( $search_terms, $user_id, $pag_num, $pag_page );
 390  }
 391  
 392  /**
 393   * Get a list of IDs of users who have requested friendship of a given user.
 394   *
 395   * @since 1.2.0
 396   *
 397   * @param int $user_id The ID of the user who has received the friendship requests.
 398   * @return array|bool An array of user IDs, or false if none are found.
 399   */
 400  function friends_get_friendship_request_user_ids( $user_id ) {
 401      return BP_Friends_Friendship::get_friendship_request_user_ids( $user_id );
 402  }
 403  
 404  /**
 405   * Get a user's most recently active friends.
 406   *
 407   * @since 1.0.0
 408   *
 409   * @see BP_Core_User::get_users() for a description of return value.
 410   *
 411   * @param int    $user_id  ID of the user whose friends are being retrieved.
 412   * @param int    $per_page Optional. Number of results to return per page.
 413   *                         Default: 0 (no pagination; show all results).
 414   * @param int    $page     Optional. Number of the page of results to return.
 415   *                         Default: 0 (no pagination; show all results).
 416   * @param string $filter   Optional. Limit results to those matching a search
 417   *                         string.
 418   * @return array See {@link BP_Core_User::get_users()}.
 419   */
 420  function friends_get_recently_active( $user_id, $per_page = 0, $page = 0, $filter = '' ) {
 421      $friends = bp_core_get_users( array(
 422          'type'         => 'active',
 423          'per_page'     => $per_page,
 424          'page'         => $page,
 425          'user_id'      => $user_id,
 426          'search_terms' => $filter,
 427      ) );
 428  
 429      /**
 430       * Filters a user's most recently active friends.
 431       *
 432       * @since 1.2.0
 433       *
 434       * @param array $friends {
 435       *     @type int   $total_users Total number of users matched by query params.
 436       *     @type array $paged_users The current page of users matched by query params.
 437       * }
 438       */
 439      return apply_filters( 'friends_get_recently_active', $friends );
 440  }
 441  
 442  /**
 443   * Get a user's friends, in alphabetical order.
 444   *
 445   * @since 1.0.0
 446   *
 447   * @see BP_Core_User::get_users() for a description of return value.
 448   *
 449   * @param int    $user_id  ID of the user whose friends are being retrieved.
 450   * @param int    $per_page Optional. Number of results to return per page.
 451   *                         Default: 0 (no pagination; show all results).
 452   * @param int    $page     Optional. Number of the page of results to return.
 453   *                         Default: 0 (no pagination; show all results).
 454   * @param string $filter   Optional. Limit results to those matching a search
 455   *                         string.
 456   * @return array See {@link BP_Core_User::get_users()}.
 457   */
 458  function friends_get_alphabetically( $user_id, $per_page = 0, $page = 0, $filter = '' ) {
 459      $friends = bp_core_get_users( array(
 460          'type'         => 'alphabetical',
 461          'per_page'     => $per_page,
 462          'page'         => $page,
 463          'user_id'      => $user_id,
 464          'search_terms' => $filter,
 465      ) );
 466  
 467      /**
 468       * Filters a user's friends listed in alphabetical order.
 469       *
 470       * @since 1.2.0
 471       *
 472       * @return array $friends {
 473       *     @type int   $total_users Total number of users matched by query params.
 474       *     @type array $paged_users The current page of users matched by query params.
 475       * }
 476       */
 477      return apply_filters( 'friends_get_alphabetically', $friends );
 478  }
 479  
 480  /**
 481   * Get a user's friends, in the order in which they joined the site.
 482   *
 483   * @since 1.0.0
 484   *
 485   * @see BP_Core_User::get_users() for a description of return value.
 486   *
 487   * @param int    $user_id  ID of the user whose friends are being retrieved.
 488   * @param int    $per_page Optional. Number of results to return per page.
 489   *                         Default: 0 (no pagination; show all results).
 490   * @param int    $page     Optional. Number of the page of results to return.
 491   *                         Default: 0 (no pagination; show all results).
 492   * @param string $filter   Optional. Limit results to those matching a search
 493   *                         string.
 494   * @return array See {@link BP_Core_User::get_users()}.
 495   */
 496  function friends_get_newest( $user_id, $per_page = 0, $page = 0, $filter = '' ) {
 497      $friends = bp_core_get_users( array(
 498          'type'         => 'newest',
 499          'per_page'     => $per_page,
 500          'page'         => $page,
 501          'user_id'      => $user_id,
 502          'search_terms' => $filter,
 503      ) );
 504  
 505      /**
 506       * Filters a user's friends listed from newest to oldest.
 507       *
 508       * @since 1.2.0
 509       *
 510       * @param array $friends {
 511       *     @type int   $total_users Total number of users matched by query params.
 512       *     @type array $paged_users The current page of users matched by query params.
 513       * }
 514       */
 515      return apply_filters( 'friends_get_newest', $friends );
 516  }
 517  
 518  /**
 519   * Get the last active date of many users at once.
 520   *
 521   * @since 1.0.0
 522   *
 523   * @see BP_Friends_Friendship::get_bulk_last_active() for a description of
 524   *      arguments and return value.
 525   *
 526   * @param array $friend_ids See BP_Friends_Friendship::get_bulk_last_active().
 527   * @return array $user_ids See BP_Friends_Friendship::get_bulk_last_active().
 528   */
 529  function friends_get_bulk_last_active( $friend_ids ) {
 530      return BP_Friends_Friendship::get_bulk_last_active( $friend_ids );
 531  }
 532  
 533  /**
 534   * Get a list of friends that a user can invite into this group.
 535   *
 536   * Excludes friends that are already in the group, and banned friends if the
 537   * user is not a group admin.
 538   *
 539   * @since 1.0.0
 540   *
 541   * @param int $user_id  User ID whose friends to see can be invited. Default:
 542   *                      ID of the logged-in user.
 543   * @param int $group_id Group to check possible invitations against.
 544   * @return mixed False if no friends, array of users if friends.
 545   */
 546  function friends_get_friends_invite_list( $user_id = 0, $group_id = 0 ) {
 547  
 548      // Default to logged in user id.
 549      if ( empty( $user_id ) )
 550          $user_id = bp_loggedin_user_id();
 551  
 552      // Only group admins can invited previously banned users.
 553      $user_is_admin = (bool) groups_is_user_admin( $user_id, $group_id );
 554  
 555      // Assume no friends.
 556      $friends = array();
 557  
 558      /**
 559       * Filters default arguments for list of friends a user can invite into this group.
 560       *
 561       * @since 1.5.4
 562       *
 563       * @param array $value Array of default parameters for invite list.
 564       */
 565      $args = apply_filters( 'bp_friends_pre_get_invite_list', array(
 566          'user_id'  => $user_id,
 567          'type'     => 'alphabetical',
 568          'per_page' => 0
 569      ) );
 570  
 571      // User has friends.
 572      if ( bp_has_members( $args ) ) {
 573  
 574          /**
 575           * Loop through all friends and try to add them to the invitation list.
 576           *
 577           * Exclude friends that:
 578           *     1. are already members of the group
 579           *     2. are banned from this group if the current user is also not a
 580           *        group admin.
 581           */
 582          while ( bp_members() ) :
 583  
 584              // Load the member.
 585              bp_the_member();
 586  
 587              // Get the user ID of the friend.
 588              $friend_user_id = bp_get_member_user_id();
 589  
 590              // Skip friend if already in the group.
 591              if ( groups_is_user_member( $friend_user_id, $group_id ) )
 592                  continue;
 593  
 594              // Skip friend if not group admin and user banned from group.
 595              if ( ( false === $user_is_admin ) && groups_is_user_banned( $friend_user_id, $group_id ) )
 596                  continue;
 597  
 598              // Friend is safe, so add it to the array of possible friends.
 599              $friends[] = array(
 600                  'id'        => $friend_user_id,
 601                  'full_name' => bp_get_member_name()
 602              );
 603  
 604          endwhile;
 605      }
 606  
 607      // If no friends, explicitly set to false.
 608      if ( empty( $friends ) )
 609          $friends = false;
 610  
 611      /**
 612       * Filters the list of potential friends that can be invited to this group.
 613       *
 614       * @since 1.5.4
 615       *
 616       * @param array|bool $friends  Array friends available to invite or false for no friends.
 617       * @param int        $user_id  ID of the user checked for who they can invite.
 618       * @param int        $group_id ID of the group being checked on.
 619       */
 620      return apply_filters( 'bp_friends_get_invite_list', $friends, $user_id, $group_id );
 621  }
 622  
 623  /**
 624   * Get a count of a user's friends who can be invited to a given group.
 625   *
 626   * Users can invite any of their friends except:
 627   *
 628   * - users who are already in the group
 629   * - users who have a pending invite to the group
 630   * - users who have been banned from the group
 631   *
 632   * @since 1.0.0
 633   *
 634   * @param int $user_id  ID of the user whose friends are being counted.
 635   * @param int $group_id ID of the group friends are being invited to.
 636   * @return int $invitable_count Eligible friend count.
 637   */
 638  function friends_count_invitable_friends( $user_id, $group_id ) {
 639      return BP_Friends_Friendship::get_invitable_friend_count( $user_id, $group_id );
 640  }
 641  
 642  /**
 643   * Get a total friend count for a given user.
 644   *
 645   * @since 1.0.0
 646   *
 647   * @param int $user_id Optional. ID of the user whose friendships you are
 648   *                     counting. Default: displayed user (if any), otherwise logged-in user.
 649   * @return int Friend count for the user.
 650   */
 651  function friends_get_friend_count_for_user( $user_id ) {
 652      return BP_Friends_Friendship::total_friend_count( $user_id );
 653  }
 654  
 655  /**
 656   * Return a list of a user's friends, filtered by a search term.
 657   *
 658   * @since 1.0.0
 659   *
 660   * @param string $search_terms Search term to filter on.
 661   * @param int    $user_id      ID of the user whose friends are being searched.
 662   * @param int    $pag_num      Number of results to return per page. Default: 0 (no
 663   *                             pagination - show all results).
 664   * @param int    $pag_page     Number of the page being requested. Default: 0 (no
 665   *                             pagination - show all results).
 666   * @return array Array of BP_Core_User objects corresponding to friends.
 667   */
 668  function friends_search_users( $search_terms, $user_id, $pag_num = 0, $pag_page = 0 ) {
 669  
 670      $user_ids = BP_Friends_Friendship::search_users( $search_terms, $user_id, $pag_num, $pag_page );
 671  
 672      if ( empty( $user_ids ) )
 673          return false;
 674  
 675      $users = array();
 676      for ( $i = 0, $count = count( $user_ids ); $i < $count; ++$i )
 677          $users[] = new BP_Core_User( $user_ids[$i] );
 678  
 679      return array( 'users' => $users, 'count' => BP_Friends_Friendship::search_users_count( $search_terms ) );
 680  }
 681  
 682  /**
 683   * Has a friendship been confirmed (accepted)?
 684   *
 685   * @since 1.0.0
 686   *
 687   * @param int $friendship_id The ID of the friendship being checked.
 688   * @return bool True if the friendship is confirmed, otherwise false.
 689   */
 690  function friends_is_friendship_confirmed( $friendship_id ) {
 691      $friendship = new BP_Friends_Friendship( $friendship_id );
 692      return $friendship->is_confirmed;
 693  }
 694  
 695  /**
 696   * Update user friend counts.
 697   *
 698   * Friend counts are cached in usermeta for performance reasons. After a
 699   * friendship event (acceptance, deletion), call this function to regenerate
 700   * the cached values.
 701   *
 702   * @since 1.0.0
 703   *
 704   * @param int    $initiator_user_id ID of the first user.
 705   * @param int    $friend_user_id    ID of the second user.
 706   * @param string $status            Optional. The friendship event that's been triggered.
 707   *                                  'add' will ++ each user's friend counts, while any other string
 708   *                                  will --.
 709   */
 710  function friends_update_friend_totals( $initiator_user_id, $friend_user_id, $status = 'add' ) {
 711  
 712      if ( 'add' == $status ) {
 713          bp_update_user_meta( $initiator_user_id, 'total_friend_count', (int)bp_get_user_meta( $initiator_user_id, 'total_friend_count', true ) + 1 );
 714          bp_update_user_meta( $friend_user_id, 'total_friend_count', (int)bp_get_user_meta( $friend_user_id, 'total_friend_count', true ) + 1 );
 715      } else {
 716          bp_update_user_meta( $initiator_user_id, 'total_friend_count', (int)bp_get_user_meta( $initiator_user_id, 'total_friend_count', true ) - 1 );
 717          bp_update_user_meta( $friend_user_id, 'total_friend_count', (int)bp_get_user_meta( $friend_user_id, 'total_friend_count', true ) - 1 );
 718      }
 719  }
 720  
 721  /**
 722   * Remove all friends-related data concerning a given user.
 723   *
 724   * Removes the following:
 725   *
 726   * - Friendships of which the user is a member.
 727   * - Cached friend count for the user.
 728   * - Notifications of friendship requests sent by the user.
 729   *
 730   * @since 1.0.0
 731   *
 732   * @param int $user_id ID of the user whose friend data is being removed.
 733   */
 734  function friends_remove_data( $user_id ) {
 735  
 736      /**
 737       * Fires before deletion of friend-related data for a given user.
 738       *
 739       * @since 1.5.0
 740       *
 741       * @param int $user_id ID for the user whose friend data is being removed.
 742       */
 743      do_action( 'friends_before_remove_data', $user_id );
 744  
 745      BP_Friends_Friendship::delete_all_for_user( $user_id );
 746  
 747      // Remove usermeta.
 748      bp_delete_user_meta( $user_id, 'total_friend_count' );
 749  
 750      /**
 751       * Fires after deletion of friend-related data for a given user.
 752       *
 753       * @since 1.0.0
 754       *
 755       * @param int $user_id ID for the user whose friend data is being removed.
 756       */
 757      do_action( 'friends_remove_data', $user_id );
 758  }
 759  add_action( 'wpmu_delete_user',  'friends_remove_data' );
 760  add_action( 'bp_make_spam_user', 'friends_remove_data' );
 761  
 762  /**
 763   * Deletes user Friends data on the 'delete_user' hook.
 764   *
 765   * @since 6.0.0
 766   *
 767   * @param int $user_id The ID of the deleted user.
 768   */
 769  function bp_friends_remove_data_on_delete_user( $user_id ) {
 770      if ( ! bp_remove_user_data_on_delete_user_hook( 'friends', $user_id ) ) {
 771          return;
 772      }
 773  
 774      friends_remove_data( $user_id );
 775  }
 776  add_action( 'delete_user', 'bp_friends_remove_data_on_delete_user' );
 777  
 778  /**
 779   * Used by the Activity component's @mentions to print a JSON list of the current user's friends.
 780   *
 781   * This is intended to speed up @mentions lookups for a majority of use cases.
 782   *
 783   * @since 2.1.0
 784   *
 785   * @see bp_activity_mentions_script()
 786   */
 787  function bp_friends_prime_mentions_results() {
 788  
 789      // Stop here if user is not logged in.
 790      if ( ! is_user_logged_in() ) {
 791          return;
 792      }
 793  
 794      if ( ! bp_activity_maybe_load_mentions_scripts() ) {
 795          return;
 796      }
 797  
 798      // Bail out if the site has a ton of users.
 799      if ( bp_is_large_install() ) {
 800          return;
 801      }
 802  
 803      if ( friends_get_total_friend_count( get_current_user_id() ) > 30 ) {
 804          return;
 805      }
 806  
 807      $friends_query = array(
 808          'count_total'     => '',                    // Prevents total count.
 809          'populate_extras' => false,
 810  
 811          'type'            => 'alphabetical',
 812          'user_id'         => get_current_user_id(),
 813      );
 814  
 815      $friends_query = new BP_User_Query( $friends_query );
 816      $results       = array();
 817  
 818      foreach ( $friends_query->results as $user ) {
 819          $result        = new stdClass();
 820          $result->ID    = $user->user_nicename;
 821          $result->image = bp_core_fetch_avatar( array( 'html' => false, 'item_id' => $user->ID ) );
 822  
 823          if ( ! empty( $user->display_name ) && ! bp_disable_profile_sync() ) {
 824              $result->name = $user->display_name;
 825          } else {
 826              $result->name = bp_core_get_user_displayname( $user->ID );
 827          }
 828  
 829          $results[] = $result;
 830      }
 831  
 832      wp_localize_script( 'bp-mentions', 'BP_Suggestions', array(
 833          'friends' => $results,
 834      ) );
 835  }
 836  add_action( 'bp_activity_mentions_prime_results', 'bp_friends_prime_mentions_results' );
 837  
 838  /** Emails ********************************************************************/
 839  
 840  /**
 841   * Send notifications related to a new friendship request.
 842   *
 843   * When a friendship is requested, an email and a BP notification are sent to
 844   * the user of whom friendship has been requested ($friend_id).
 845   *
 846   * @since 1.0.0
 847   *
 848   * @param int $friendship_id ID of the friendship object.
 849   * @param int $initiator_id  ID of the user who initiated the request.
 850   * @param int $friend_id     ID of the request recipient.
 851   */
 852  function friends_notification_new_request( $friendship_id, $initiator_id, $friend_id ) {
 853      if ( 'no' == bp_get_user_meta( (int) $friend_id, 'notification_friends_friendship_request', true ) ) {
 854          return;
 855      }
 856  
 857      $unsubscribe_args = array(
 858          'user_id'           => $friend_id,
 859          'notification_type' => 'friends-request',
 860      );
 861  
 862      $args = array(
 863          'tokens' => array(
 864              'friend-requests.url' => esc_url( bp_core_get_user_domain( $friend_id ) . bp_get_friends_slug() . '/requests/' ),
 865              'friend.id'           => $friend_id,
 866              'friendship.id'       => $friendship_id,
 867              'initiator.id'        => $initiator_id,
 868              'initiator.url'       => esc_url( bp_core_get_user_domain( $initiator_id ) ),
 869              'initiator.name'      => bp_core_get_user_displayname( $initiator_id ),
 870              'unsubscribe'         => esc_url( bp_email_get_unsubscribe_link( $unsubscribe_args ) ),
 871          ),
 872      );
 873      bp_send_email( 'friends-request', $friend_id, $args );
 874  }
 875  add_action( 'friends_friendship_requested', 'friends_notification_new_request', 10, 3 );
 876  
 877  /**
 878   * Send notifications related to the acceptance of a friendship request.
 879   *
 880   * When a friendship request is accepted, an email and a BP notification are
 881   * sent to the user who requested the friendship ($initiator_id).
 882   *
 883   * @since 1.0.0
 884   *
 885   * @param int $friendship_id ID of the friendship object.
 886   * @param int $initiator_id  ID of the user who initiated the request.
 887   * @param int $friend_id     ID of the request recipient.
 888   */
 889  function friends_notification_accepted_request( $friendship_id, $initiator_id, $friend_id ) {
 890      if ( 'no' == bp_get_user_meta( (int) $initiator_id, 'notification_friends_friendship_accepted', true ) ) {
 891          return;
 892      }
 893  
 894      $unsubscribe_args = array(
 895          'user_id'           => $initiator_id,
 896          'notification_type' => 'friends-request-accepted',
 897      );
 898  
 899      $args = array(
 900          'tokens' => array(
 901              'friend.id'      => $friend_id,
 902              'friendship.url' => esc_url( bp_core_get_user_domain( $friend_id ) ),
 903              'friend.name'    => bp_core_get_user_displayname( $friend_id ),
 904              'friendship.id'  => $friendship_id,
 905              'initiator.id'   => $initiator_id,
 906              'unsubscribe'       => esc_url( bp_email_get_unsubscribe_link( $unsubscribe_args ) ),
 907          ),
 908      );
 909      bp_send_email( 'friends-request-accepted', $initiator_id, $args );
 910  }
 911  add_action( 'friends_friendship_accepted', 'friends_notification_accepted_request', 10, 3 );
 912  
 913  /**
 914   * Finds and exports friendship data associated with an email address.
 915   *
 916   * @since 4.0.0
 917   *
 918   * @param string $email_address  The user's email address.
 919   * @param int    $page           Batch number.
 920   * @return array An array of personal data.
 921   */
 922  function bp_friends_personal_data_exporter( $email_address, $page ) {
 923      $number = 50;
 924  
 925      $email_address = trim( $email_address );
 926  
 927      $data_to_export = array();
 928  
 929      $user = get_user_by( 'email', $email_address );
 930  
 931      if ( ! $user ) {
 932          return array(
 933              'data' => array(),
 934              'done' => true,
 935          );
 936      }
 937  
 938      $friendships = BP_Friends_Friendship::get_friendships( $user->ID, array(
 939          'is_confirmed' => true,
 940          'page'         => $page,
 941          'per_page'     => $number,
 942      ) );
 943  
 944      $user_data_to_export = array();
 945  
 946      foreach ( $friendships as $friendship ) {
 947          if ( (int) $user->ID === (int) $friendship->initiator_user_id ) {
 948              $friend_id         = $friendship->friend_user_id;
 949              $user_is_initiator = true;
 950          } else {
 951              $friend_id         = $friendship->initiator_user_id;
 952              $user_is_initiator = false;
 953          }
 954  
 955          $item_data = array(
 956              array(
 957                  'name'  => __( 'Friend', 'buddypress' ),
 958                  'value' => bp_core_get_userlink( $friend_id ),
 959              ),
 960              array(
 961                  'name'  => __( 'Initiated By Me', 'buddypress' ),
 962                  'value' => $user_is_initiator ? __( 'Yes', 'buddypress' ) : __( 'No', 'buddypress' ),
 963              ),
 964              array(
 965                  'name'  => __( 'Friendship Date', 'buddypress' ),
 966                  'value' => $friendship->date_created,
 967              ),
 968          );
 969  
 970          $data_to_export[] = array(
 971              'group_id'    => 'bp_friends',
 972              'group_label' => __( 'Friends', 'buddypress' ),
 973              'item_id'     => "bp-friends-{$friend_id}",
 974              'data'        => $item_data,
 975          );
 976      }
 977  
 978      // Tell core if we have more items to process.
 979      $done = count( $friendships ) < $number;
 980  
 981      return array(
 982          'data' => $data_to_export,
 983          'done' => $done,
 984      );
 985  }
 986  
 987  /**
 988   * Finds and exports pending sent friendship request data associated with an email address.
 989   *
 990   * @since 4.0.0
 991   *
 992   * @param string $email_address  The user's email address.
 993   * @param int    $page           Batch number.
 994   * @return array An array of personal data.
 995   */
 996  function bp_friends_pending_sent_requests_personal_data_exporter( $email_address, $page ) {
 997      $number = 50;
 998  
 999      $email_address = trim( $email_address );
1000  
1001      $data_to_export = array();
1002  
1003      $user = get_user_by( 'email', $email_address );
1004  
1005      if ( ! $user ) {
1006          return array(
1007              'data' => array(),
1008              'done' => true,
1009          );
1010      }
1011  
1012      $friendships = BP_Friends_Friendship::get_friendships( $user->ID, array(
1013          'is_confirmed'      => false,
1014          'initiator_user_id' => $user->ID,
1015          'page'              => $page,
1016          'per_page'          => $number,
1017      ) );
1018  
1019      $user_data_to_export = array();
1020  
1021      foreach ( $friendships as $friendship ) {
1022          $item_data = array(
1023              array(
1024                  'name'  => __( 'Recipient', 'buddypress' ),
1025                  'value' => bp_core_get_userlink( $friendship->friend_user_id ),
1026              ),
1027              array(
1028                  'name'  => __( 'Date Sent', 'buddypress' ),
1029                  'value' => $friendship->date_created,
1030              ),
1031          );
1032  
1033          $data_to_export[] = array(
1034              'group_id'    => 'bp_friends_pending_sent_requests',
1035              'group_label' => __( 'Pending Friend Requests (Sent)', 'buddypress' ),
1036              'item_id'     => "bp-friends-pending-sent-request-{$friendship->friend_user_id}",
1037              'data'        => $item_data,
1038          );
1039      }
1040  
1041      // Tell core if we have more items to process.
1042      $done = count( $friendships ) < $number;
1043  
1044      return array(
1045          'data' => $data_to_export,
1046          'done' => $done,
1047      );
1048  }
1049  
1050  /**
1051   * Finds and exports pending received friendship request data associated with an email address.
1052   *
1053   * @since 4.0.0
1054   *
1055   * @param string $email_address  The user's email address.
1056   * @param int    $page           Batch number.
1057   * @return array An array of personal data.
1058   */
1059  function bp_friends_pending_received_requests_personal_data_exporter( $email_address, $page ) {
1060      $number = 50;
1061  
1062      $email_address = trim( $email_address );
1063  
1064      $data_to_export = array();
1065  
1066      $user = get_user_by( 'email', $email_address );
1067  
1068      if ( ! $user ) {
1069          return array(
1070              'data' => array(),
1071              'done' => true,
1072          );
1073      }
1074  
1075      $friendships = BP_Friends_Friendship::get_friendships( $user->ID, array(
1076          'is_confirmed'   => false,
1077          'friend_user_id' => $user->ID,
1078          'page'           => $page,
1079          'per_page'       => $number,
1080      ) );
1081  
1082      $user_data_to_export = array();
1083  
1084      foreach ( $friendships as $friendship ) {
1085          $item_data = array(
1086              array(
1087                  'name'  => __( 'Requester', 'buddypress' ),
1088                  'value' => bp_core_get_userlink( $friendship->initiator_user_id ),
1089              ),
1090              array(
1091                  'name'  => __( 'Date Sent', 'buddypress' ),
1092                  'value' => $friendship->date_created,
1093              ),
1094          );
1095  
1096          $data_to_export[] = array(
1097              'group_id'    => 'bp_friends_pending_received_requests',
1098              'group_label' => __( 'Pending Friend Requests (Received)', 'buddypress' ),
1099              'item_id'     => "bp-friends-pending-received-request-{$friendship->initiator_user_id}",
1100              'data'        => $item_data,
1101          );
1102      }
1103  
1104      // Tell core if we have more items to process.
1105      $done = count( $friendships ) < $number;
1106  
1107      return array(
1108          'data' => $data_to_export,
1109          'done' => $done,
1110      );
1111  }