[ Index ]

PHP Cross Reference of BuddyPress

title

Body

[close]

/src/bp-friends/ -> bp-friends-functions.php (source)

   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( 'delete_user',       'friends_remove_data' );
 761  add_action( 'bp_make_spam_user', 'friends_remove_data' );
 762  
 763  /**
 764   * Used by the Activity component's @mentions to print a JSON list of the current user's friends.
 765   *
 766   * This is intended to speed up @mentions lookups for a majority of use cases.
 767   *
 768   * @since 2.1.0
 769   *
 770   * @see bp_activity_mentions_script()
 771   */
 772  function bp_friends_prime_mentions_results() {
 773  
 774      // Stop here if user is not logged in.
 775      if ( ! is_user_logged_in() ) {
 776          return;
 777      }
 778  
 779      if ( ! bp_activity_maybe_load_mentions_scripts() ) {
 780          return;
 781      }
 782  
 783      // Bail out if the site has a ton of users.
 784      if ( bp_is_large_install() ) {
 785          return;
 786      }
 787  
 788      if ( friends_get_total_friend_count( get_current_user_id() ) > 30 ) {
 789          return;
 790      }
 791  
 792      $friends_query = array(
 793          'count_total'     => '',                    // Prevents total count.
 794          'populate_extras' => false,
 795  
 796          'type'            => 'alphabetical',
 797          'user_id'         => get_current_user_id(),
 798      );
 799  
 800      $friends_query = new BP_User_Query( $friends_query );
 801      $results       = array();
 802  
 803      foreach ( $friends_query->results as $user ) {
 804          $result        = new stdClass();
 805          $result->ID    = $user->user_nicename;
 806          $result->image = bp_core_fetch_avatar( array( 'html' => false, 'item_id' => $user->ID ) );
 807  
 808          if ( ! empty( $user->display_name ) && ! bp_disable_profile_sync() ) {
 809              $result->name = $user->display_name;
 810          } else {
 811              $result->name = bp_core_get_user_displayname( $user->ID );
 812          }
 813  
 814          $results[] = $result;
 815      }
 816  
 817      wp_localize_script( 'bp-mentions', 'BP_Suggestions', array(
 818          'friends' => $results,
 819      ) );
 820  }
 821  add_action( 'bp_activity_mentions_prime_results', 'bp_friends_prime_mentions_results' );
 822  
 823  /** Emails ********************************************************************/
 824  
 825  /**
 826   * Send notifications related to a new friendship request.
 827   *
 828   * When a friendship is requested, an email and a BP notification are sent to
 829   * the user of whom friendship has been requested ($friend_id).
 830   *
 831   * @since 1.0.0
 832   *
 833   * @param int $friendship_id ID of the friendship object.
 834   * @param int $initiator_id  ID of the user who initiated the request.
 835   * @param int $friend_id     ID of the request recipient.
 836   */
 837  function friends_notification_new_request( $friendship_id, $initiator_id, $friend_id ) {
 838      if ( 'no' == bp_get_user_meta( (int) $friend_id, 'notification_friends_friendship_request', true ) ) {
 839          return;
 840      }
 841  
 842      $unsubscribe_args = array(
 843          'user_id'           => $friend_id,
 844          'notification_type' => 'friends-request',
 845      );
 846  
 847      $args = array(
 848          'tokens' => array(
 849              'friend-requests.url' => esc_url( bp_core_get_user_domain( $friend_id ) . bp_get_friends_slug() . '/requests/' ),
 850              'friend.id'           => $friend_id,
 851              'friendship.id'       => $friendship_id,
 852              'initiator.id'        => $initiator_id,
 853              'initiator.url'       => esc_url( bp_core_get_user_domain( $initiator_id ) ),
 854              'initiator.name'      => bp_core_get_user_displayname( $initiator_id ),
 855              'unsubscribe'         => esc_url( bp_email_get_unsubscribe_link( $unsubscribe_args ) ),
 856          ),
 857      );
 858      bp_send_email( 'friends-request', $friend_id, $args );
 859  }
 860  add_action( 'friends_friendship_requested', 'friends_notification_new_request', 10, 3 );
 861  
 862  /**
 863   * Send notifications related to the acceptance of a friendship request.
 864   *
 865   * When a friendship request is accepted, an email and a BP notification are
 866   * sent to the user who requested the friendship ($initiator_id).
 867   *
 868   * @since 1.0.0
 869   *
 870   * @param int $friendship_id ID of the friendship object.
 871   * @param int $initiator_id  ID of the user who initiated the request.
 872   * @param int $friend_id     ID of the request recipient.
 873   */
 874  function friends_notification_accepted_request( $friendship_id, $initiator_id, $friend_id ) {
 875      if ( 'no' == bp_get_user_meta( (int) $initiator_id, 'notification_friends_friendship_accepted', true ) ) {
 876          return;
 877      }
 878  
 879      $unsubscribe_args = array(
 880          'user_id'           => $initiator_id,
 881          'notification_type' => 'friends-request-accepted',
 882      );
 883  
 884      $args = array(
 885          'tokens' => array(
 886              'friend.id'      => $friend_id,
 887              'friendship.url' => esc_url( bp_core_get_user_domain( $friend_id ) ),
 888              'friend.name'    => bp_core_get_user_displayname( $friend_id ),
 889              'friendship.id'  => $friendship_id,
 890              'initiator.id'   => $initiator_id,
 891              'unsubscribe'       => esc_url( bp_email_get_unsubscribe_link( $unsubscribe_args ) ),
 892          ),
 893      );
 894      bp_send_email( 'friends-request-accepted', $initiator_id, $args );
 895  }
 896  add_action( 'friends_friendship_accepted', 'friends_notification_accepted_request', 10, 3 );
 897  
 898  /**
 899   * Finds and exports friendship data associated with an email address.
 900   *
 901   * @since 4.0.0
 902   *
 903   * @param string $email_address  The user's email address.
 904   * @param int    $page           Batch number.
 905   * @return array An array of personal data.
 906   */
 907  function bp_friends_personal_data_exporter( $email_address, $page ) {
 908      $number = 50;
 909  
 910      $email_address = trim( $email_address );
 911  
 912      $data_to_export = array();
 913  
 914      $user = get_user_by( 'email', $email_address );
 915  
 916      if ( ! $user ) {
 917          return array(
 918              'data' => array(),
 919              'done' => true,
 920          );
 921      }
 922  
 923      $friendships = BP_Friends_Friendship::get_friendships( $user->ID, array(
 924          'is_confirmed' => true,
 925          'page'         => $page,
 926          'per_page'     => $number,
 927      ) );
 928  
 929      $user_data_to_export = array();
 930  
 931      foreach ( $friendships as $friendship ) {
 932          if ( (int) $user->ID === (int) $friendship->initiator_user_id ) {
 933              $friend_id         = $friendship->friend_user_id;
 934              $user_is_initiator = true;
 935          } else {
 936              $friend_id         = $friendship->initiator_user_id;
 937              $user_is_initiator = false;
 938          }
 939  
 940          $item_data = array(
 941              array(
 942                  'name'  => __( 'Friend', 'buddypress' ),
 943                  'value' => bp_core_get_userlink( $friend_id ),
 944              ),
 945              array(
 946                  'name'  => __( 'Initiated By Me', 'buddypress' ),
 947                  'value' => $user_is_initiator ? __( 'Yes', 'buddypress' ) : __( 'No', 'buddypress' ),
 948              ),
 949              array(
 950                  'name'  => __( 'Friendship Date', 'buddypress' ),
 951                  'value' => $friendship->date_created,
 952              ),
 953          );
 954  
 955          $data_to_export[] = array(
 956              'group_id'    => 'bp_friends',
 957              'group_label' => __( 'Friends', 'buddypress' ),
 958              'item_id'     => "bp-friends-{$friend_id}",
 959              'data'        => $item_data,
 960          );
 961      }
 962  
 963      // Tell core if we have more items to process.
 964      $done = count( $friendships ) < $number;
 965  
 966      return array(
 967          'data' => $data_to_export,
 968          'done' => $done,
 969      );
 970  }
 971  
 972  /**
 973   * Finds and exports pending sent friendship request data associated with an email address.
 974   *
 975   * @since 4.0.0
 976   *
 977   * @param string $email_address  The user's email address.
 978   * @param int    $page           Batch number.
 979   * @return array An array of personal data.
 980   */
 981  function bp_friends_pending_sent_requests_personal_data_exporter( $email_address, $page ) {
 982      $number = 50;
 983  
 984      $email_address = trim( $email_address );
 985  
 986      $data_to_export = array();
 987  
 988      $user = get_user_by( 'email', $email_address );
 989  
 990      if ( ! $user ) {
 991          return array(
 992              'data' => array(),
 993              'done' => true,
 994          );
 995      }
 996  
 997      $friendships = BP_Friends_Friendship::get_friendships( $user->ID, array(
 998          'is_confirmed'      => false,
 999          'initiator_user_id' => $user->ID,
1000          'page'              => $page,
1001          'per_page'          => $number,
1002      ) );
1003  
1004      $user_data_to_export = array();
1005  
1006      foreach ( $friendships as $friendship ) {
1007          $item_data = array(
1008              array(
1009                  'name'  => __( 'Recipient', 'buddypress' ),
1010                  'value' => bp_core_get_userlink( $friendship->friend_user_id ),
1011              ),
1012              array(
1013                  'name'  => __( 'Date Sent', 'buddypress' ),
1014                  'value' => $friendship->date_created,
1015              ),
1016          );
1017  
1018          $data_to_export[] = array(
1019              'group_id'    => 'bp_friends_pending_sent_requests',
1020              'group_label' => __( 'Pending Friend Requests (Sent)', 'buddypress' ),
1021              'item_id'     => "bp-friends-pending-sent-request-{$friendship->friend_user_id}",
1022              'data'        => $item_data,
1023          );
1024      }
1025  
1026      // Tell core if we have more items to process.
1027      $done = count( $friendships ) < $number;
1028  
1029      return array(
1030          'data' => $data_to_export,
1031          'done' => $done,
1032      );
1033  }
1034  
1035  /**
1036   * Finds and exports pending received friendship request data associated with an email address.
1037   *
1038   * @since 4.0.0
1039   *
1040   * @param string $email_address  The user's email address.
1041   * @param int    $page           Batch number.
1042   * @return array An array of personal data.
1043   */
1044  function bp_friends_pending_received_requests_personal_data_exporter( $email_address, $page ) {
1045      $number = 50;
1046  
1047      $email_address = trim( $email_address );
1048  
1049      $data_to_export = array();
1050  
1051      $user = get_user_by( 'email', $email_address );
1052  
1053      if ( ! $user ) {
1054          return array(
1055              'data' => array(),
1056              'done' => true,
1057          );
1058      }
1059  
1060      $friendships = BP_Friends_Friendship::get_friendships( $user->ID, array(
1061          'is_confirmed'   => false,
1062          'friend_user_id' => $user->ID,
1063          'page'           => $page,
1064          'per_page'       => $number,
1065      ) );
1066  
1067      $user_data_to_export = array();
1068  
1069      foreach ( $friendships as $friendship ) {
1070          $item_data = array(
1071              array(
1072                  'name'  => __( 'Requester', 'buddypress' ),
1073                  'value' => bp_core_get_userlink( $friendship->initiator_user_id ),
1074              ),
1075              array(
1076                  'name'  => __( 'Date Sent', 'buddypress' ),
1077                  'value' => $friendship->date_created,
1078              ),
1079          );
1080  
1081          $data_to_export[] = array(
1082              'group_id'    => 'bp_friends_pending_received_requests',
1083              'group_label' => __( 'Pending Friend Requests (Received)', 'buddypress' ),
1084              'item_id'     => "bp-friends-pending-received-request-{$friendship->initiator_user_id}",
1085              'data'        => $item_data,
1086          );
1087      }
1088  
1089      // Tell core if we have more items to process.
1090      $done = count( $friendships ) < $number;
1091  
1092      return array(
1093          'data' => $data_to_export,
1094          'done' => $done,
1095      );
1096  }


Generated: Thu Sep 19 01:01:39 2019 Cross-referenced by PHPXref 0.7.1