/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. $friends = bp_core_get_users( array( 
  401. 'type' => 'active',  
  402. 'per_page' => $per_page,  
  403. 'page' => $page,  
  404. 'user_id' => $user_id,  
  405. 'search_terms' => $filter,  
  406. ) ); 
  407.  
  408. /** 
  409. * Filters a user's most recently active friends. 
  410. * 
  411. * @since 1.2.0 
  412. * 
  413. * @param array $friends { 
  414. * @type int $total_users Total number of users matched by query params. 
  415. * @type array $paged_users The current page of users matched by query params. 
  416. * } 
  417. */ 
  418. return apply_filters( 'friends_get_recently_active', $friends ); 
  419.  
  420. /** 
  421. * Get a user's friends, in alphabetical order. 
  422. * 
  423. * @since 1.0.0 
  424. * 
  425. * @see BP_Core_User::get_users() for a description of return value. 
  426. * 
  427. * @param int $user_id ID of the user whose friends are being retrieved. 
  428. * @param int $per_page Optional. Number of results to return per page. 
  429. * Default: 0 (no pagination; show all results). 
  430. * @param int $page Optional. Number of the page of results to return. 
  431. * Default: 0 (no pagination; show all results). 
  432. * @param string $filter Optional. Limit results to those matching a search 
  433. * string. 
  434. * @return array See {@link BP_Core_User::get_users()}. 
  435. */ 
  436. function friends_get_alphabetically( $user_id, $per_page = 0, $page = 0, $filter = '' ) { 
  437. $friends = bp_core_get_users( array( 
  438. 'type' => 'alphabetical',  
  439. 'per_page' => $per_page,  
  440. 'page' => $page,  
  441. 'user_id' => $user_id,  
  442. 'search_terms' => $filter,  
  443. ) ); 
  444.  
  445. /** 
  446. * Filters a user's friends listed in alphabetical order. 
  447. * 
  448. * @since 1.2.0 
  449. * 
  450. * @return array $friends { 
  451. * @type int $total_users Total number of users matched by query params. 
  452. * @type array $paged_users The current page of users matched by query params. 
  453. * } 
  454. */ 
  455. return apply_filters( 'friends_get_alphabetically', $friends ); 
  456.  
  457. /** 
  458. * Get a user's friends, in the order in which they joined the site. 
  459. * 
  460. * @since 1.0.0 
  461. * 
  462. * @see BP_Core_User::get_users() for a description of return value. 
  463. * 
  464. * @param int $user_id ID of the user whose friends are being retrieved. 
  465. * @param int $per_page Optional. Number of results to return per page. 
  466. * Default: 0 (no pagination; show all results). 
  467. * @param int $page Optional. Number of the page of results to return. 
  468. * Default: 0 (no pagination; show all results). 
  469. * @param string $filter Optional. Limit results to those matching a search 
  470. * string. 
  471. * @return array See {@link BP_Core_User::get_users()}. 
  472. */ 
  473. function friends_get_newest( $user_id, $per_page = 0, $page = 0, $filter = '' ) { 
  474. $friends = bp_core_get_users( array( 
  475. 'type' => 'newest',  
  476. 'per_page' => $per_page,  
  477. 'page' => $page,  
  478. 'user_id' => $user_id,  
  479. 'search_terms' => $filter,  
  480. ) ); 
  481.  
  482. /** 
  483. * Filters a user's friends listed from newest to oldest. 
  484. * 
  485. * @since 1.2.0 
  486. * 
  487. * @param array $friends { 
  488. * @type int $total_users Total number of users matched by query params. 
  489. * @type array $paged_users The current page of users matched by query params. 
  490. * } 
  491. */ 
  492. return apply_filters( 'friends_get_newest', $friends ); 
  493.  
  494. /** 
  495. * Get the last active date of many users at once. 
  496. * 
  497. * @since 1.0.0 
  498. * 
  499. * @see BP_Friends_Friendship::get_bulk_last_active() for a description of 
  500. * arguments and return value. 
  501. * 
  502. * @param array $friend_ids See BP_Friends_Friendship::get_bulk_last_active(). 
  503. * @return array $user_ids See BP_Friends_Friendship::get_bulk_last_active(). 
  504. */ 
  505. function friends_get_bulk_last_active( $friend_ids ) { 
  506. return BP_Friends_Friendship::get_bulk_last_active( $friend_ids ); 
  507.  
  508. /** 
  509. * Get a list of friends that a user can invite into this group. 
  510. * 
  511. * Excludes friends that are already in the group, and banned friends if the 
  512. * user is not a group admin. 
  513. * 
  514. * @since 1.0.0 
  515. * 
  516. * @param int $user_id User ID whose friends to see can be invited. Default: 
  517. * ID of the logged-in user. 
  518. * @param int $group_id Group to check possible invitations against. 
  519. * @return mixed False if no friends, array of users if friends. 
  520. */ 
  521. function friends_get_friends_invite_list( $user_id = 0, $group_id = 0 ) { 
  522.  
  523. // Default to logged in user id. 
  524. if ( empty( $user_id ) ) 
  525. $user_id = bp_loggedin_user_id(); 
  526.  
  527. // Only group admins can invited previously banned users. 
  528. $user_is_admin = (bool) groups_is_user_admin( $user_id, $group_id ); 
  529.  
  530. // Assume no friends. 
  531. $friends = array(); 
  532.  
  533. /** 
  534. * Filters default arguments for list of friends a user can invite into this group. 
  535. * 
  536. * @since 1.5.4 
  537. * 
  538. * @param array $value Array of default parameters for invite list. 
  539. */ 
  540. $args = apply_filters( 'bp_friends_pre_get_invite_list', array( 
  541. 'user_id' => $user_id,  
  542. 'type' => 'alphabetical',  
  543. 'per_page' => 0 
  544. ) ); 
  545.  
  546. // User has friends. 
  547. if ( bp_has_members( $args ) ) { 
  548.  
  549. /** 
  550. * Loop through all friends and try to add them to the invitation list. 
  551. * 
  552. * Exclude friends that: 
  553. * 1. are already members of the group 
  554. * 2. are banned from this group if the current user is also not a 
  555. * group admin. 
  556. */ 
  557. while ( bp_members() ) : 
  558.  
  559. // Load the member. 
  560. bp_the_member(); 
  561.  
  562. // Get the user ID of the friend. 
  563. $friend_user_id = bp_get_member_user_id(); 
  564.  
  565. // Skip friend if already in the group. 
  566. if ( groups_is_user_member( $friend_user_id, $group_id ) ) 
  567. continue; 
  568.  
  569. // Skip friend if not group admin and user banned from group. 
  570. if ( ( false === $user_is_admin ) && groups_is_user_banned( $friend_user_id, $group_id ) ) 
  571. continue; 
  572.  
  573. // Friend is safe, so add it to the array of possible friends. 
  574. $friends[] = array( 
  575. 'id' => $friend_user_id,  
  576. 'full_name' => bp_get_member_name() 
  577. ); 
  578.  
  579. endwhile; 
  580.  
  581. // If no friends, explicitly set to false. 
  582. if ( empty( $friends ) ) 
  583. $friends = false; 
  584.  
  585. /** 
  586. * Filters the list of potential friends that can be invited to this group. 
  587. * 
  588. * @since 1.5.4 
  589. * 
  590. * @param array|bool $friends Array friends available to invite or false for no friends. 
  591. * @param int $user_id ID of the user checked for who they can invite. 
  592. * @param int $group_id ID of the group being checked on. 
  593. */ 
  594. return apply_filters( 'bp_friends_get_invite_list', $friends, $user_id, $group_id ); 
  595.  
  596. /** 
  597. * Get a count of a user's friends who can be invited to a given group. 
  598. * 
  599. * Users can invite any of their friends except: 
  600. * 
  601. * - users who are already in the group 
  602. * - users who have a pending invite to the group 
  603. * - users who have been banned from the group 
  604. * 
  605. * @since 1.0.0 
  606. * 
  607. * @param int $user_id ID of the user whose friends are being counted. 
  608. * @param int $group_id ID of the group friends are being invited to. 
  609. * @return int $invitable_count Eligible friend count. 
  610. */ 
  611. function friends_count_invitable_friends( $user_id, $group_id ) { 
  612. return BP_Friends_Friendship::get_invitable_friend_count( $user_id, $group_id ); 
  613.  
  614. /** 
  615. * Get a total friend count for a given user. 
  616. * 
  617. * @since 1.0.0 
  618. * 
  619. * @param int $user_id Optional. ID of the user whose friendships you are 
  620. * counting. Default: displayed user (if any), otherwise logged-in user. 
  621. * @return int Friend count for the user. 
  622. */ 
  623. function friends_get_friend_count_for_user( $user_id ) { 
  624. return BP_Friends_Friendship::total_friend_count( $user_id ); 
  625.  
  626. /** 
  627. * Return a list of a user's friends, filtered by a search term. 
  628. * 
  629. * @since 1.0.0 
  630. * 
  631. * @param string $search_terms Search term to filter on. 
  632. * @param int $user_id ID of the user whose friends are being searched. 
  633. * @param int $pag_num Number of results to return per page. Default: 0 (no 
  634. * pagination - show all results). 
  635. * @param int $pag_page Number of the page being requested. Default: 0 (no 
  636. * pagination - show all results). 
  637. * @return array Array of BP_Core_User objects corresponding to friends. 
  638. */ 
  639. function friends_search_users( $search_terms, $user_id, $pag_num = 0, $pag_page = 0 ) { 
  640.  
  641. $user_ids = BP_Friends_Friendship::search_users( $search_terms, $user_id, $pag_num, $pag_page ); 
  642.  
  643. if ( empty( $user_ids ) ) 
  644. return false; 
  645.  
  646. $users = array(); 
  647. for ( $i = 0, $count = count( $user_ids ); $i < $count; ++$i ) 
  648. $users[] = new BP_Core_User( $user_ids[$i] ); 
  649.  
  650. return array( 'users' => $users, 'count' => BP_Friends_Friendship::search_users_count( $search_terms ) ); 
  651.  
  652. /** 
  653. * Has a friendship been confirmed (accepted)? 
  654. * 
  655. * @since 1.0.0 
  656. * 
  657. * @param int $friendship_id The ID of the friendship being checked. 
  658. * @return bool True if the friendship is confirmed, otherwise false. 
  659. */ 
  660. function friends_is_friendship_confirmed( $friendship_id ) { 
  661. $friendship = new BP_Friends_Friendship( $friendship_id ); 
  662. return $friendship->is_confirmed; 
  663.  
  664. /** 
  665. * Update user friend counts. 
  666. * 
  667. * Friend counts are cached in usermeta for performance reasons. After a 
  668. * friendship event (acceptance, deletion), call this function to regenerate 
  669. * the cached values. 
  670. * 
  671. * @since 1.0.0 
  672. * 
  673. * @param int $initiator_user_id ID of the first user. 
  674. * @param int $friend_user_id ID of the second user. 
  675. * @param string $status Optional. The friendship event that's been triggered. 
  676. * 'add' will ++ each user's friend counts, while any other string 
  677. * will --. 
  678. */ 
  679. function friends_update_friend_totals( $initiator_user_id, $friend_user_id, $status = 'add' ) { 
  680.  
  681. if ( 'add' == $status ) { 
  682. bp_update_user_meta( $initiator_user_id, 'total_friend_count', (int)bp_get_user_meta( $initiator_user_id, 'total_friend_count', true ) + 1 ); 
  683. bp_update_user_meta( $friend_user_id, 'total_friend_count', (int)bp_get_user_meta( $friend_user_id, 'total_friend_count', true ) + 1 ); 
  684. } else { 
  685. bp_update_user_meta( $initiator_user_id, 'total_friend_count', (int)bp_get_user_meta( $initiator_user_id, 'total_friend_count', true ) - 1 ); 
  686. bp_update_user_meta( $friend_user_id, 'total_friend_count', (int)bp_get_user_meta( $friend_user_id, 'total_friend_count', true ) - 1 ); 
  687.  
  688. /** 
  689. * Remove all friends-related data concerning a given user. 
  690. * 
  691. * Removes the following: 
  692. * 
  693. * - Friendships of which the user is a member. 
  694. * - Cached friend count for the user. 
  695. * - Notifications of friendship requests sent by the user. 
  696. * 
  697. * @since 1.0.0 
  698. * 
  699. * @param int $user_id ID of the user whose friend data is being removed. 
  700. */ 
  701. function friends_remove_data( $user_id ) { 
  702.  
  703. /** 
  704. * Fires before deletion of friend-related data for a given user. 
  705. * 
  706. * @since 1.5.0 
  707. * 
  708. * @param int $user_id ID for the user whose friend data is being removed. 
  709. */ 
  710. do_action( 'friends_before_remove_data', $user_id ); 
  711.  
  712. BP_Friends_Friendship::delete_all_for_user( $user_id ); 
  713.  
  714. // Remove usermeta. 
  715. bp_delete_user_meta( $user_id, 'total_friend_count' ); 
  716.  
  717. /** 
  718. * Fires after deletion of friend-related data for a given user. 
  719. * 
  720. * @since 1.0.0 
  721. * 
  722. * @param int $user_id ID for the user whose friend data is being removed. 
  723. */ 
  724. do_action( 'friends_remove_data', $user_id ); 
  725. add_action( 'wpmu_delete_user', 'friends_remove_data' ); 
  726. add_action( 'delete_user', 'friends_remove_data' ); 
  727. add_action( 'bp_make_spam_user', 'friends_remove_data' ); 
  728.  
  729. /** 
  730. * Used by the Activity component's @mentions to print a JSON list of the current user's friends. 
  731. * 
  732. * This is intended to speed up @mentions lookups for a majority of use cases. 
  733. * 
  734. * @since 2.1.0 
  735. * 
  736. * @see bp_activity_mentions_script() 
  737. */ 
  738. function bp_friends_prime_mentions_results() { 
  739. if ( ! bp_activity_maybe_load_mentions_scripts() ) { 
  740. return; 
  741.  
  742. // Bail out if the site has a ton of users. 
  743. if ( is_multisite() && wp_is_large_network( 'users' ) ) { 
  744. return; 
  745.  
  746. if ( friends_get_total_friend_count( get_current_user_id() ) > 150 ) { 
  747. return; 
  748.  
  749. $friends_query = array( 
  750. 'count_total' => '', // Prevents total count. 
  751. 'populate_extras' => false,  
  752.  
  753. 'type' => 'alphabetical',  
  754. 'user_id' => get_current_user_id(),  
  755. ); 
  756.  
  757. $friends_query = new BP_User_Query( $friends_query ); 
  758. $results = array(); 
  759.  
  760. foreach ( $friends_query->results as $user ) { 
  761. $result = new stdClass(); 
  762. $result->ID = $user->user_nicename; 
  763. $result->image = bp_core_fetch_avatar( array( 'html' => false, 'item_id' => $user->ID ) ); 
  764.  
  765. if ( ! empty( $user->display_name ) && ! bp_disable_profile_sync() ) { 
  766. $result->name = $user->display_name; 
  767. } else { 
  768. $result->name = bp_core_get_user_displayname( $user->ID ); 
  769.  
  770. $results[] = $result; 
  771.  
  772. wp_localize_script( 'bp-mentions', 'BP_Suggestions', array( 
  773. 'friends' => $results,  
  774. ) ); 
  775. add_action( 'bp_activity_mentions_prime_results', 'bp_friends_prime_mentions_results' ); 
  776.  
  777. /** Emails ********************************************************************/ 
  778.  
  779. /** 
  780. * Send notifications related to a new friendship request. 
  781. * 
  782. * When a friendship is requested, an email and a BP notification are sent to 
  783. * the user of whom friendship has been requested ($friend_id). 
  784. * 
  785. * @since 1.0.0 
  786. * 
  787. * @param int $friendship_id ID of the friendship object. 
  788. * @param int $initiator_id ID of the user who initiated the request. 
  789. * @param int $friend_id ID of the request recipient. 
  790. */ 
  791. function friends_notification_new_request( $friendship_id, $initiator_id, $friend_id ) { 
  792. if ( 'no' == bp_get_user_meta( (int) $friend_id, 'notification_friends_friendship_request', true ) ) { 
  793. return; 
  794.  
  795. $unsubscribe_args = array( 
  796. 'user_id' => $friend_id,  
  797. 'notification_type' => 'friends-request',  
  798. ); 
  799.  
  800. $args = array( 
  801. 'tokens' => array( 
  802. 'friend-requests.url' => esc_url( bp_core_get_user_domain( $friend_id ) . bp_get_friends_slug() . '/requests/' ),  
  803. 'friend.id' => $friend_id,  
  804. 'friendship.id' => $friendship_id,  
  805. 'initiator.id' => $initiator_id,  
  806. 'initiator.url' => esc_url( bp_core_get_user_domain( $initiator_id ) ),  
  807. 'initiator.name' => bp_core_get_user_displayname( $initiator_id ),  
  808. 'unsubscribe' => esc_url( bp_email_get_unsubscribe_link( $unsubscribe_args ) ),  
  809. ),  
  810. ); 
  811. bp_send_email( 'friends-request', $friend_id, $args ); 
  812. add_action( 'friends_friendship_requested', 'friends_notification_new_request', 10, 3 ); 
  813.  
  814. /** 
  815. * Send notifications related to the acceptance of a friendship request. 
  816. * 
  817. * When a friendship request is accepted, an email and a BP notification are 
  818. * sent to the user who requested the friendship ($initiator_id). 
  819. * 
  820. * @since 1.0.0 
  821. * 
  822. * @param int $friendship_id ID of the friendship object. 
  823. * @param int $initiator_id ID of the user who initiated the request. 
  824. * @param int $friend_id ID of the request recipient. 
  825. */ 
  826. function friends_notification_accepted_request( $friendship_id, $initiator_id, $friend_id ) { 
  827. if ( 'no' == bp_get_user_meta( (int) $initiator_id, 'notification_friends_friendship_accepted', true ) ) { 
  828. return; 
  829.  
  830. $unsubscribe_args = array( 
  831. 'user_id' => $initiator_id,  
  832. 'notification_type' => 'friends-request-accepted',  
  833. ); 
  834.  
  835. $args = array( 
  836. 'tokens' => array( 
  837. 'friend.id' => $friend_id,  
  838. 'friendship.url' => esc_url( bp_core_get_user_domain( $friend_id ) ),  
  839. 'friend.name' => bp_core_get_user_displayname( $friend_id ),  
  840. 'friendship.id' => $friendship_id,  
  841. 'initiator.id' => $initiator_id,  
  842. 'unsubscribe' => esc_url( bp_email_get_unsubscribe_link( $unsubscribe_args ) ),  
  843. ),  
  844. ); 
  845. bp_send_email( 'friends-request-accepted', $initiator_id, $args ); 
  846. add_action( 'friends_friendship_accepted', 'friends_notification_accepted_request', 10, 3 ); 
.