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


Generated: Fri Dec 6 01:00:58 2024 Cross-referenced by PHPXref 0.7.1