/bp-friends/bp-friends-functions.php

  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. // Check if already friends, and bail if so. 
  40. if ( friends_check_friendship( $initiator_userid, $friend_userid ) ) { 
  41. return true; 
  42.  
  43. // Setup the friendship data. 
  44. $friendship = new BP_Friends_Friendship; 
  45. $friendship->initiator_user_id = $initiator_userid; 
  46. $friendship->friend_user_id = $friend_userid; 
  47. $friendship->is_confirmed = 0; 
  48. $friendship->is_limited = 0; 
  49. $friendship->date_created = bp_core_current_time(); 
  50.  
  51. if ( ! empty( $force_accept ) ) { 
  52. $friendship->is_confirmed = 1; 
  53.  
  54. // Bail if friendship could not be saved (how sad!). 
  55. if ( ! $friendship->save() ) { 
  56. return false; 
  57.  
  58. // Send notifications. 
  59. if ( empty( $force_accept ) ) { 
  60. $action = 'requested'; 
  61.  
  62. // Update friend totals. 
  63. } else { 
  64. $action = 'accepted'; 
  65. friends_update_friend_totals( $friendship->initiator_user_id, $friendship->friend_user_id, 'add' ); 
  66.  
  67. /** 
  68. * Fires at the end of initiating a new friendship connection. 
  69. * 
  70. * This is a variable hook, depending on context. 
  71. * The two potential hooks are: friends_friendship_requested, friends_friendship_accepted. 
  72. * 
  73. * @since 1.0.0 
  74. * 
  75. * @param int $id ID of the pending friendship connection. 
  76. * @param int $initiator_user_id ID of the friendship initiator. 
  77. * @param int $friend_user_id ID of the friend user. 
  78. * @param object $friendship BuddyPress Friendship Object. 
  79. */ 
  80. do_action( 'friends_friendship_' . $action, $friendship->id, $friendship->initiator_user_id, $friendship->friend_user_id, $friendship ); 
  81.  
  82. return true; 
  83.  
  84. /** 
  85. * Remove a friendship. 
  86. * 
  87. * Will also delete the related "friendship_accepted" activity item. 
  88. * 
  89. * @since 1.0.0 
  90. * 
  91. * @param int $initiator_userid ID of the friendship initiator. 
  92. * @param int $friend_userid ID of the friend user. 
  93. * @return bool True on success, false on failure. 
  94. */ 
  95. function friends_remove_friend( $initiator_userid, $friend_userid ) { 
  96.  
  97. $friendship_id = BP_Friends_Friendship::get_friendship_id( $initiator_userid, $friend_userid ); 
  98. $friendship = new BP_Friends_Friendship( $friendship_id ); 
  99.  
  100. /** 
  101. * Fires before the deletion of a friendship activity item 
  102. * for the user who canceled the friendship. 
  103. * 
  104. * @since 1.5.0 
  105. * 
  106. * @param int $friendship_id ID of the friendship object, if any, between a pair of users. 
  107. * @param int $initiator_userid ID of the friendship initiator. 
  108. * @param int $friend_userid ID of the friend user. 
  109. */ 
  110. do_action( 'friends_before_friendship_delete', $friendship_id, $initiator_userid, $friend_userid ); 
  111.  
  112. // Remove the activity stream items about the friendship id. 
  113. friends_delete_activity( array( 'item_id' => $friendship_id, 'type' => 'friendship_created', 'user_id' => 0 ) ); 
  114.  
  115. /** 
  116. * Fires before the friendship connection is removed. 
  117. * 
  118. * This hook is misleadingly named - the friendship is not yet deleted. 
  119. * This is your last chance to do something while the friendship exists. 
  120. * 
  121. * @since 1.0.0 
  122. * 
  123. * @param int $friendship_id ID of the friendship object, if any, between a pair of users. 
  124. * @param int $initiator_userid ID of the friendship initiator. 
  125. * @param int $friend_userid ID of the friend user. 
  126. */ 
  127. do_action( 'friends_friendship_deleted', $friendship_id, $initiator_userid, $friend_userid ); 
  128.  
  129. if ( $friendship->delete() ) { 
  130. friends_update_friend_totals( $initiator_userid, $friend_userid, 'remove' ); 
  131.  
  132. /** 
  133. * Fires after the friendship connection is removed. 
  134. * 
  135. * @since 1.8.0 
  136. * 
  137. * @param int $initiator_userid ID of the friendship initiator. 
  138. * @param int $friend_userid ID of the friend user. 
  139. */ 
  140. do_action( 'friends_friendship_post_delete', $initiator_userid, $friend_userid ); 
  141.  
  142. return true; 
  143.  
  144. return false; 
  145.  
  146. /** 
  147. * Mark a friendship request as accepted. 
  148. * 
  149. * Also initiates a "friendship_accepted" activity item. 
  150. * 
  151. * @since 1.0.0 
  152. * 
  153. * @param int $friendship_id ID of the pending friendship object. 
  154. * @return bool True on success, false on failure. 
  155. */ 
  156. function friends_accept_friendship( $friendship_id ) { 
  157.  
  158. // Get the friendship data. 
  159. $friendship = new BP_Friends_Friendship( $friendship_id, true, false ); 
  160.  
  161. // Accepting friendship. 
  162. if ( empty( $friendship->is_confirmed ) && BP_Friends_Friendship::accept( $friendship_id ) ) { 
  163.  
  164. // Bump the friendship counts. 
  165. friends_update_friend_totals( $friendship->initiator_user_id, $friendship->friend_user_id ); 
  166.  
  167. /** 
  168. * Fires after a friendship is accepted. 
  169. * 
  170. * @since 1.0.0 
  171. * 
  172. * @param int $id ID of the pending friendship object. 
  173. * @param int $initiator_user_id ID of the friendship initiator. 
  174. * @param int $friend_user_id ID of the user requested friendship with. 
  175. * @param object $friendship BuddyPress Friendship Object. 
  176. */ 
  177. do_action( 'friends_friendship_accepted', $friendship->id, $friendship->initiator_user_id, $friendship->friend_user_id, $friendship ); 
  178.  
  179. return true; 
  180.  
  181. return false; 
  182.  
  183. /** 
  184. * Mark a friendship request as rejected. 
  185. * 
  186. * @since 1.0.0 
  187. * 
  188. * @param int $friendship_id ID of the pending friendship object. 
  189. * @return bool True on success, false on failure. 
  190. */ 
  191. function friends_reject_friendship( $friendship_id ) { 
  192. $friendship = new BP_Friends_Friendship( $friendship_id, true, false ); 
  193.  
  194. if ( empty( $friendship->is_confirmed ) && BP_Friends_Friendship::reject( $friendship_id ) ) { 
  195.  
  196. /** 
  197. * Fires after a friendship request is rejected. 
  198. * 
  199. * @since 1.0.0 
  200. * 
  201. * @param int $friendship_id ID of the pending friendship. 
  202. * @param BP_Friends_Friendship $friendships Friendship object. Passed by reference. 
  203. */ 
  204. do_action_ref_array( 'friends_friendship_rejected', array( $friendship_id, &$friendship ) ); 
  205. return true; 
  206.  
  207. return false; 
  208.  
  209. /** 
  210. * Withdraw a friendship request. 
  211. * 
  212. * @since 1.6.0 
  213. * 
  214. * @param int $initiator_userid ID of the friendship initiator - this is the 
  215. * user who requested the friendship, and is doing the withdrawing. 
  216. * @param int $friend_userid ID of the requested friend. 
  217. * @return bool True on success, false on failure. 
  218. */ 
  219. function friends_withdraw_friendship( $initiator_userid, $friend_userid ) { 
  220. $friendship_id = BP_Friends_Friendship::get_friendship_id( $initiator_userid, $friend_userid ); 
  221. $friendship = new BP_Friends_Friendship( $friendship_id, true, false ); 
  222.  
  223. if ( empty( $friendship->is_confirmed ) && BP_Friends_Friendship::withdraw( $friendship_id ) ) { 
  224.  
  225. // @deprecated Since 1.9 
  226. do_action_ref_array( 'friends_friendship_whithdrawn', array( $friendship_id, &$friendship ) ); 
  227.  
  228. /** 
  229. * Fires after a friendship request has been withdrawn. 
  230. * 
  231. * @since 1.9.0 
  232. * 
  233. * @param int $friendship_id ID of the friendship. 
  234. * @param BP_Friends_Friendship $friendship Friendship object. Passed by reference. 
  235. */ 
  236. do_action_ref_array( 'friends_friendship_withdrawn', array( $friendship_id, &$friendship ) ); 
  237.  
  238. return true; 
  239.  
  240. return false; 
  241.  
  242. /** 
  243. * Check whether two users are friends. 
  244. * 
  245. * @since 1.0.0 
  246. * 
  247. * @param int $user_id ID of the first user. 
  248. * @param int $possible_friend_id ID of the other user. 
  249. * @return bool Returns true if the two users are friends, otherwise false. 
  250. */ 
  251. function friends_check_friendship( $user_id, $possible_friend_id ) { 
  252.  
  253. if ( 'is_friend' == BP_Friends_Friendship::check_is_friend( $user_id, $possible_friend_id ) ) 
  254. return true; 
  255.  
  256. return false; 
  257.  
  258. /** 
  259. * Get the friendship status of two friends. 
  260. * 
  261. * Will return 'is_friends', 'not_friends', 'pending' or 'awaiting_response'. 
  262. * 
  263. * @since 1.2.0 
  264. * 
  265. * @param int $user_id ID of the first user. 
  266. * @param int $possible_friend_id ID of the other user. 
  267. * @return string Friend status of the two users. 
  268. */ 
  269. function friends_check_friendship_status( $user_id, $possible_friend_id ) { 
  270. global $members_template; 
  271.  
  272. // Check the BP_User_Query first 
  273. // @see bp_friends_filter_user_query_populate_extras(). 
  274. if ( ! empty( $members_template->in_the_loop ) ) { 
  275. if ( isset( $members_template->member->friendship_status ) ) { 
  276. return $members_template->member->friendship_status; 
  277.  
  278. return BP_Friends_Friendship::check_is_friend( $user_id, $possible_friend_id ); 
  279.  
  280. /** 
  281. * Get the friend count of a given user. 
  282. * 
  283. * @since 1.2.0 
  284. * 
  285. * @param int $user_id ID of the user whose friends are being counted. 
  286. * @return int Friend count of the user. 
  287. */ 
  288. function friends_get_total_friend_count( $user_id = 0 ) { 
  289. if ( empty( $user_id ) ) 
  290. $user_id = ( bp_displayed_user_id() ) ? bp_displayed_user_id() : bp_loggedin_user_id(); 
  291.  
  292. $count = bp_get_user_meta( $user_id, 'total_friend_count', true ); 
  293. if ( empty( $count ) ) 
  294. $count = 0; 
  295.  
  296. /** 
  297. * Filters the total friend count for a given user. 
  298. * 
  299. * @since 1.2.0 
  300. * 
  301. * @param int $count Total friend count for a given user. 
  302. */ 
  303. return apply_filters( 'friends_get_total_friend_count', $count ); 
  304.  
  305. /** 
  306. * Check whether a given user has any friends. 
  307. * 
  308. * @since 1.0.0 
  309. * 
  310. * @param int $user_id ID of the user whose friends are being checked. 
  311. * @return bool True if the user has friends, otherwise false. 
  312. */ 
  313. function friends_check_user_has_friends( $user_id ) { 
  314. $friend_count = friends_get_total_friend_count( $user_id ); 
  315.  
  316. if ( empty( $friend_count ) ) 
  317. return false; 
  318.  
  319. if ( !(int) $friend_count ) 
  320. return false; 
  321.  
  322. return true; 
  323.  
  324. /** 
  325. * Get the ID of two users' friendship, if it exists. 
  326. * 
  327. * @since 1.2.0 
  328. * 
  329. * @param int $initiator_user_id ID of the first user. 
  330. * @param int $friend_user_id ID of the second user. 
  331. * @return int|bool ID of the friendship if found, otherwise false. 
  332. */ 
  333. function friends_get_friendship_id( $initiator_user_id, $friend_user_id ) { 
  334. return BP_Friends_Friendship::get_friendship_id( $initiator_user_id, $friend_user_id ); 
  335.  
  336. /** 
  337. * Get the IDs of a given user's friends. 
  338. * 
  339. * @since 1.0.0 
  340. * 
  341. * @param int $user_id ID of the user whose friends are being retrieved. 
  342. * @param bool $friend_requests_only Optional. Whether to fetch unaccepted 
  343. * requests only. Default: false. 
  344. * @param bool $assoc_arr Optional. True to receive an array of arrays keyed as 
  345. * 'user_id' => $user_id; false to get a one-dimensional 
  346. * array of user IDs. Default: false. 
  347. * @return array 
  348. */ 
  349. function friends_get_friend_user_ids( $user_id, $friend_requests_only = false, $assoc_arr = false ) { 
  350. return BP_Friends_Friendship::get_friend_user_ids( $user_id, $friend_requests_only, $assoc_arr ); 
  351.  
  352. /** 
  353. * Search the friends of a user by a search string. 
  354. * 
  355. * @since 1.0.0 
  356. * 
  357. * @param string $search_terms The search string, matched against xprofile fields (if 
  358. * available), or usermeta 'nickname' field. 
  359. * @param int $user_id ID of the user whose friends are being searched. 
  360. * @param int $pag_num Optional. Max number of friends to return. 
  361. * @param int $pag_page Optional. The page of results to return. Default: null (no 
  362. * pagination - return all results). 
  363. * @return array|bool On success, an array: { 
  364. * @type array $friends IDs of friends returned by the query. 
  365. * @type int $count Total number of friends (disregarding 
  366. * pagination) who match the search. 
  367. * }. Returns false on failure. 
  368. */ 
  369. function friends_search_friends( $search_terms, $user_id, $pag_num = 10, $pag_page = 1 ) { 
  370. return BP_Friends_Friendship::search_friends( $search_terms, $user_id, $pag_num, $pag_page ); 
  371.  
  372. /** 
  373. * Get a list of IDs of users who have requested friendship of a given user. 
  374. * 
  375. * @since 1.2.0 
  376. * 
  377. * @param int $user_id The ID of the user who has received the friendship requests. 
  378. * @return array|bool An array of user IDs, or false if none are found. 
  379. */ 
  380. function friends_get_friendship_request_user_ids( $user_id ) { 
  381. return BP_Friends_Friendship::get_friendship_request_user_ids( $user_id ); 
  382.  
  383. /** 
  384. * Get a user's most recently active friends. 
  385. * 
  386. * @since 1.0.0 
  387. * 
  388. * @see BP_Core_User::get_users() for a description of return value. 
  389. * 
  390. * @param int $user_id ID of the user whose friends are being retrieved. 
  391. * @param int $per_page Optional. Number of results to return per page. 
  392. * Default: 0 (no pagination; show all results). 
  393. * @param int $page Optional. Number of the page of results to return. 
  394. * Default: 0 (no pagination; show all results). 
  395. * @param string $filter Optional. Limit results to those matching a search 
  396. * string. 
  397. * @return array See {@link BP_Core_User::get_users()}. 
  398. */ 
  399. function friends_get_recently_active( $user_id, $per_page = 0, $page = 0, $filter = '' ) { 
  400.  
  401. /** 
  402. * Filters a user's most recently active friends. 
  403. * 
  404. * @since 1.2.0 
  405. * 
  406. * @param array { 
  407. * @type int $total_users Total number of users matched by query params. 
  408. * @type array $paged_users The current page of users matched by query params. 
  409. * } 
  410. */ 
  411. return apply_filters( 'friends_get_recently_active', BP_Core_User::get_users( 'active', $per_page, $page, $user_id, $filter ) ); 
  412.  
  413. /** 
  414. * Get a user's friends, in alphabetical order. 
  415. * 
  416. * @since 1.0.0 
  417. * 
  418. * @see BP_Core_User::get_users() for a description of return value. 
  419. * 
  420. * @param int $user_id ID of the user whose friends are being retrieved. 
  421. * @param int $per_page Optional. Number of results to return per page. 
  422. * Default: 0 (no pagination; show all results). 
  423. * @param int $page Optional. Number of the page of results to return. 
  424. * Default: 0 (no pagination; show all results). 
  425. * @param string $filter Optional. Limit results to those matching a search 
  426. * string. 
  427. * @return array See {@link BP_Core_User::get_users()}. 
  428. */ 
  429. function friends_get_alphabetically( $user_id, $per_page = 0, $page = 0, $filter = '' ) { 
  430.  
  431. /** 
  432. * Filters a user's friends listed in alphabetical order. 
  433. * 
  434. * @since 1.2.0 
  435. * 
  436. * @return array { 
  437. * @type int $total_users Total number of users matched by query params. 
  438. * @type array $paged_users The current page of users matched by query params. 
  439. * } 
  440. */ 
  441. return apply_filters( 'friends_get_alphabetically', BP_Core_User::get_users( 'alphabetical', $per_page, $page, $user_id, $filter ) ); 
  442.  
  443. /** 
  444. * Get a user's friends, in the order in which they joined the site. 
  445. * 
  446. * @since 1.0.0 
  447. * 
  448. * @see BP_Core_User::get_users() for a description of return value. 
  449. * 
  450. * @param int $user_id ID of the user whose friends are being retrieved. 
  451. * @param int $per_page Optional. Number of results to return per page. 
  452. * Default: 0 (no pagination; show all results). 
  453. * @param int $page Optional. Number of the page of results to return. 
  454. * Default: 0 (no pagination; show all results). 
  455. * @param string $filter Optional. Limit results to those matching a search 
  456. * string. 
  457. * @return array See {@link BP_Core_User::get_users()}. 
  458. */ 
  459. function friends_get_newest( $user_id, $per_page = 0, $page = 0, $filter = '' ) { 
  460.  
  461. /** 
  462. * Filters a user's friends listed from newest to oldest. 
  463. * 
  464. * @since 1.2.0 
  465. * 
  466. * @param array { 
  467. * @type int $total_users Total number of users matched by query params. 
  468. * @type array $paged_users The current page of users matched by query params. 
  469. * } 
  470. */ 
  471. return apply_filters( 'friends_get_newest', BP_Core_User::get_users( 'newest', $per_page, $page, $user_id, $filter ) ); 
  472.  
  473. /** 
  474. * Get the last active date of many users at once. 
  475. * 
  476. * @since 1.0.0 
  477. * 
  478. * @see BP_Friends_Friendship::get_bulk_last_active() for a description of 
  479. * arguments and return value. 
  480. * 
  481. * @param array $friend_ids See BP_Friends_Friendship::get_bulk_last_active(). 
  482. * @return array $user_ids See BP_Friends_Friendship::get_bulk_last_active(). 
  483. */ 
  484. function friends_get_bulk_last_active( $friend_ids ) { 
  485. return BP_Friends_Friendship::get_bulk_last_active( $friend_ids ); 
  486.  
  487. /** 
  488. * Get a list of friends that a user can invite into this group. 
  489. * 
  490. * Excludes friends that are already in the group, and banned friends if the 
  491. * user is not a group admin. 
  492. * 
  493. * @since 1.0.0 
  494. * 
  495. * @param int $user_id User ID whose friends to see can be invited. Default: 
  496. * ID of the logged-in user. 
  497. * @param int $group_id Group to check possible invitations against. 
  498. * @return mixed False if no friends, array of users if friends. 
  499. */ 
  500. function friends_get_friends_invite_list( $user_id = 0, $group_id = 0 ) { 
  501.  
  502. // Default to logged in user id. 
  503. if ( empty( $user_id ) ) 
  504. $user_id = bp_loggedin_user_id(); 
  505.  
  506. // Only group admins can invited previously banned users. 
  507. $user_is_admin = (bool) groups_is_user_admin( $user_id, $group_id ); 
  508.  
  509. // Assume no friends. 
  510. $friends = array(); 
  511.  
  512. /** 
  513. * Filters default arguments for list of friends a user can invite into this group. 
  514. * 
  515. * @since 1.5.4 
  516. * 
  517. * @param array $value Array of default parameters for invite list. 
  518. */ 
  519. $args = apply_filters( 'bp_friends_pre_get_invite_list', array( 
  520. 'user_id' => $user_id,  
  521. 'type' => 'alphabetical',  
  522. 'per_page' => 0 
  523. ) ); 
  524.  
  525. // User has friends. 
  526. if ( bp_has_members( $args ) ) { 
  527.  
  528. /** 
  529. * Loop through all friends and try to add them to the invitation list. 
  530. * 
  531. * Exclude friends that: 
  532. * 1. are already members of the group 
  533. * 2. are banned from this group if the current user is also not a 
  534. * group admin. 
  535. */ 
  536. while ( bp_members() ) : 
  537.  
  538. // Load the member. 
  539. bp_the_member(); 
  540.  
  541. // Get the user ID of the friend. 
  542. $friend_user_id = bp_get_member_user_id(); 
  543.  
  544. // Skip friend if already in the group. 
  545. if ( groups_is_user_member( $friend_user_id, $group_id ) ) 
  546. continue; 
  547.  
  548. // Skip friend if not group admin and user banned from group. 
  549. if ( ( false === $user_is_admin ) && groups_is_user_banned( $friend_user_id, $group_id ) ) 
  550. continue; 
  551.  
  552. // Friend is safe, so add it to the array of possible friends. 
  553. $friends[] = array( 
  554. 'id' => $friend_user_id,  
  555. 'full_name' => bp_get_member_name() 
  556. ); 
  557.  
  558. endwhile; 
  559.  
  560. // If no friends, explicitly set to false. 
  561. if ( empty( $friends ) ) 
  562. $friends = false; 
  563.  
  564. /** 
  565. * Filters the list of potential friends that can be invited to this group. 
  566. * 
  567. * @since 1.5.4 
  568. * 
  569. * @param array|bool $friends Array friends available to invite or false for no friends. 
  570. * @param int $user_id ID of the user checked for who they can invite. 
  571. * @param int $group_id ID of the group being checked on. 
  572. */ 
  573. return apply_filters( 'bp_friends_get_invite_list', $friends, $user_id, $group_id ); 
  574.  
  575. /** 
  576. * Get a count of a user's friends who can be invited to a given group. 
  577. * 
  578. * Users can invite any of their friends except: 
  579. * 
  580. * - users who are already in the group 
  581. * - users who have a pending invite to the group 
  582. * - users who have been banned from the group 
  583. * 
  584. * @since 1.0.0 
  585. * 
  586. * @param int $user_id ID of the user whose friends are being counted. 
  587. * @param int $group_id ID of the group friends are being invited to. 
  588. * @return int $invitable_count Eligible friend count. 
  589. */ 
  590. function friends_count_invitable_friends( $user_id, $group_id ) { 
  591. return BP_Friends_Friendship::get_invitable_friend_count( $user_id, $group_id ); 
  592.  
  593. /** 
  594. * Get a total friend count for a given user. 
  595. * 
  596. * @since 1.0.0 
  597. * 
  598. * @param int $user_id Optional. ID of the user whose friendships you are 
  599. * counting. Default: displayed user (if any), otherwise logged-in user. 
  600. * @return int Friend count for the user. 
  601. */ 
  602. function friends_get_friend_count_for_user( $user_id ) { 
  603. return BP_Friends_Friendship::total_friend_count( $user_id ); 
  604.  
  605. /** 
  606. * Return a list of a user's friends, filtered by a search term. 
  607. * 
  608. * @since 1.0.0 
  609. * 
  610. * @param string $search_terms Search term to filter on. 
  611. * @param int $user_id ID of the user whose friends are being searched. 
  612. * @param int $pag_num Number of results to return per page. Default: 0 (no 
  613. * pagination - show all results). 
  614. * @param int $pag_page Number of the page being requested. Default: 0 (no 
  615. * pagination - show all results). 
  616. * @return array Array of BP_Core_User objects corresponding to friends. 
  617. */ 
  618. function friends_search_users( $search_terms, $user_id, $pag_num = 0, $pag_page = 0 ) { 
  619.  
  620. $user_ids = BP_Friends_Friendship::search_users( $search_terms, $user_id, $pag_num, $pag_page ); 
  621.  
  622. if ( empty( $user_ids ) ) 
  623. return false; 
  624.  
  625. $users = array(); 
  626. for ( $i = 0, $count = count( $user_ids ); $i < $count; ++$i ) 
  627. $users[] = new BP_Core_User( $user_ids[$i] ); 
  628.  
  629. return array( 'users' => $users, 'count' => BP_Friends_Friendship::search_users_count( $search_terms ) ); 
  630.  
  631. /** 
  632. * Has a friendship been confirmed (accepted)? 
  633. * 
  634. * @since 1.0.0 
  635. * 
  636. * @param int $friendship_id The ID of the friendship being checked. 
  637. * @return bool True if the friendship is confirmed, otherwise false. 
  638. */ 
  639. function friends_is_friendship_confirmed( $friendship_id ) { 
  640. $friendship = new BP_Friends_Friendship( $friendship_id ); 
  641. return $friendship->is_confirmed; 
  642.  
  643. /** 
  644. * Update user friend counts. 
  645. * 
  646. * Friend counts are cached in usermeta for performance reasons. After a 
  647. * friendship event (acceptance, deletion), call this function to regenerate 
  648. * the cached values. 
  649. * 
  650. * @since 1.0.0 
  651. * 
  652. * @param int $initiator_user_id ID of the first user. 
  653. * @param int $friend_user_id ID of the second user. 
  654. * @param string $status Optional. The friendship event that's been triggered. 
  655. * 'add' will ++ each user's friend counts, while any other string 
  656. * will --. 
  657. */ 
  658. function friends_update_friend_totals( $initiator_user_id, $friend_user_id, $status = 'add' ) { 
  659.  
  660. if ( 'add' == $status ) { 
  661. bp_update_user_meta( $initiator_user_id, 'total_friend_count', (int)bp_get_user_meta( $initiator_user_id, 'total_friend_count', true ) + 1 ); 
  662. bp_update_user_meta( $friend_user_id, 'total_friend_count', (int)bp_get_user_meta( $friend_user_id, 'total_friend_count', true ) + 1 ); 
  663. } else { 
  664. bp_update_user_meta( $initiator_user_id, 'total_friend_count', (int)bp_get_user_meta( $initiator_user_id, 'total_friend_count', true ) - 1 ); 
  665. bp_update_user_meta( $friend_user_id, 'total_friend_count', (int)bp_get_user_meta( $friend_user_id, 'total_friend_count', true ) - 1 ); 
  666.  
  667. /** 
  668. * Remove all friends-related data concerning a given user. 
  669. * 
  670. * Removes the following: 
  671. * 
  672. * - Friendships of which the user is a member. 
  673. * - Cached friend count for the user. 
  674. * - Notifications of friendship requests sent by the user. 
  675. * 
  676. * @since 1.0.0 
  677. * 
  678. * @param int $user_id ID of the user whose friend data is being removed. 
  679. */ 
  680. function friends_remove_data( $user_id ) { 
  681.  
  682. /** 
  683. * Fires before deletion of friend-related data for a given user. 
  684. * 
  685. * @since 1.5.0 
  686. * 
  687. * @param int $user_id ID for the user whose friend data is being removed. 
  688. */ 
  689. do_action( 'friends_before_remove_data', $user_id ); 
  690.  
  691. BP_Friends_Friendship::delete_all_for_user( $user_id ); 
  692.  
  693. // Remove usermeta. 
  694. bp_delete_user_meta( $user_id, 'total_friend_count' ); 
  695.  
  696. /** 
  697. * Fires after deletion of friend-related data for a given user. 
  698. * 
  699. * @since 1.0.0 
  700. * 
  701. * @param int $user_id ID for the user whose friend data is being removed. 
  702. */ 
  703. do_action( 'friends_remove_data', $user_id ); 
  704. add_action( 'wpmu_delete_user', 'friends_remove_data' ); 
  705. add_action( 'delete_user', 'friends_remove_data' ); 
  706. add_action( 'bp_make_spam_user', 'friends_remove_data' ); 
  707.  
  708. /** 
  709. * Used by the Activity component's @mentions to print a JSON list of the current user's friends. 
  710. * 
  711. * This is intended to speed up @mentions lookups for a majority of use cases. 
  712. * 
  713. * @since 2.1.0 
  714. * 
  715. * @see bp_activity_mentions_script() 
  716. */ 
  717. function bp_friends_prime_mentions_results() { 
  718. if ( ! bp_activity_maybe_load_mentions_scripts() ) { 
  719. return; 
  720.  
  721. // Bail out if the site has a ton of users. 
  722. if ( is_multisite() && wp_is_large_network( 'users' ) ) { 
  723. return; 
  724.  
  725. if ( friends_get_total_friend_count( get_current_user_id() ) > 150 ) { 
  726. return; 
  727.  
  728. $friends_query = array( 
  729. 'count_total' => '', // Prevents total count. 
  730. 'populate_extras' => false,  
  731.  
  732. 'type' => 'alphabetical',  
  733. 'user_id' => get_current_user_id(),  
  734. ); 
  735.  
  736. $friends_query = new BP_User_Query( $friends_query ); 
  737. $results = array(); 
  738.  
  739. foreach ( $friends_query->results as $user ) { 
  740. $result = new stdClass(); 
  741. $result->ID = $user->user_nicename; 
  742. $result->image = bp_core_fetch_avatar( array( 'html' => false, 'item_id' => $user->ID ) ); 
  743.  
  744. if ( ! empty( $user->display_name ) && ! bp_disable_profile_sync() ) { 
  745. $result->name = $user->display_name; 
  746. } else { 
  747. $result->name = bp_core_get_user_displayname( $user->ID ); 
  748.  
  749. $results[] = $result; 
  750.  
  751. wp_localize_script( 'bp-mentions', 'BP_Suggestions', array( 
  752. 'friends' => $results,  
  753. ) ); 
  754. add_action( 'bp_activity_mentions_prime_results', 'bp_friends_prime_mentions_results' ); 
  755.  
  756. /** Emails ********************************************************************/ 
  757.  
  758. /** 
  759. * Send notifications related to a new friendship request. 
  760. * 
  761. * When a friendship is requested, an email and a BP notification are sent to 
  762. * the user of whom friendship has been requested ($friend_id). 
  763. * 
  764. * @since 1.0.0 
  765. * 
  766. * @param int $friendship_id ID of the friendship object. 
  767. * @param int $initiator_id ID of the user who initiated the request. 
  768. * @param int $friend_id ID of the request recipient. 
  769. */ 
  770. function friends_notification_new_request( $friendship_id, $initiator_id, $friend_id ) { 
  771. if ( 'no' == bp_get_user_meta( (int) $friend_id, 'notification_friends_friendship_request', true ) ) { 
  772. return; 
  773.  
  774. $unsubscribe_args = array( 
  775. 'user_id' => $friend_id,  
  776. 'notification_type' => 'friends-request',  
  777. ); 
  778.  
  779. $args = array( 
  780. 'tokens' => array( 
  781. 'friend-requests.url' => esc_url( bp_core_get_user_domain( $friend_id ) . bp_get_friends_slug() . '/requests/' ),  
  782. 'friend.id' => $friend_id,  
  783. 'friendship.id' => $friendship_id,  
  784. 'initiator.id' => $initiator_id,  
  785. 'initiator.url' => esc_url( bp_core_get_user_domain( $initiator_id ) ),  
  786. 'initiator.name' => bp_core_get_user_displayname( $initiator_id ),  
  787. 'unsubscribe' => esc_url( bp_email_get_unsubscribe_link( $unsubscribe_args ) ),  
  788. ),  
  789. ); 
  790. bp_send_email( 'friends-request', $friend_id, $args ); 
  791. add_action( 'friends_friendship_requested', 'friends_notification_new_request', 10, 3 ); 
  792.  
  793. /** 
  794. * Send notifications related to the acceptance of a friendship request. 
  795. * 
  796. * When a friendship request is accepted, an email and a BP notification are 
  797. * sent to the user who requested the friendship ($initiator_id). 
  798. * 
  799. * @since 1.0.0 
  800. * 
  801. * @param int $friendship_id ID of the friendship object. 
  802. * @param int $initiator_id ID of the user who initiated the request. 
  803. * @param int $friend_id ID of the request recipient. 
  804. */ 
  805. function friends_notification_accepted_request( $friendship_id, $initiator_id, $friend_id ) { 
  806. if ( 'no' == bp_get_user_meta( (int) $initiator_id, 'notification_friends_friendship_accepted', true ) ) { 
  807. return; 
  808.  
  809. $unsubscribe_args = array( 
  810. 'user_id' => $initiator_id,  
  811. 'notification_type' => 'friends-request-accepted',  
  812. ); 
  813.  
  814. $args = array( 
  815. 'tokens' => array( 
  816. 'friend.id' => $friend_id,  
  817. 'friendship.url' => esc_url( bp_core_get_user_domain( $friend_id ) ),  
  818. 'friend.name' => bp_core_get_user_displayname( $friend_id ),  
  819. 'friendship.id' => $friendship_id,  
  820. 'initiator.id' => $initiator_id,  
  821. 'unsubscribe' => esc_url( bp_email_get_unsubscribe_link( $unsubscribe_args ) ),  
  822. ),  
  823. ); 
  824. bp_send_email( 'friends-request-accepted', $initiator_id, $args ); 
  825. add_action( 'friends_friendship_accepted', 'friends_notification_accepted_request', 10, 3 ); 
.