/bp-groups/bp-groups-functions.php

  1. <?php 
  2. /** 
  3. * BuddyPress Groups 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 GroupsFunctions 
  12. * @since 1.5.0 
  13. */ 
  14.  
  15. // Exit if accessed directly. 
  16. defined( 'ABSPATH' ) || exit; 
  17.  
  18. /** 
  19. * Check whether there is a Groups directory page in the $bp global. 
  20. * 
  21. * @since 1.5.0 
  22. * 
  23. * @return bool True if set, False if empty. 
  24. */ 
  25. function bp_groups_has_directory() { 
  26. $bp = buddypress(); 
  27.  
  28. return (bool) !empty( $bp->pages->groups->id ); 
  29.  
  30. /** 
  31. * Fetch a single group object. 
  32. * 
  33. * When calling up a group object, you should always use this function instead 
  34. * of instantiating BP_Groups_Group directly, so that you will inherit cache 
  35. * support and pass through the groups_get_group filter. 
  36. * 
  37. * @since 1.2.0 
  38. * @since 2.7.0 The function signature was changed to accept a group ID only,  
  39. * instead of an array containing the group ID. 
  40. * 
  41. * @param int $group_id ID of the group. 
  42. * @return BP_Groups_Group $group The group object. 
  43. */ 
  44. function groups_get_group( $group_id ) { 
  45. /** 
  46. * Backward compatibilty. 
  47. * Old-style arguments take the form of an array or a query string. 
  48. */ 
  49. if ( ! is_numeric( $group_id ) ) { 
  50. $r = wp_parse_args( $group_id, array( 
  51. 'group_id' => false,  
  52. 'load_users' => false,  
  53. 'populate_extras' => false,  
  54. ) ); 
  55.  
  56. $group_id = $r['group_id']; 
  57.  
  58. $group = new BP_Groups_Group( $group_id ); 
  59.  
  60. /** 
  61. * Filters a single group object. 
  62. * 
  63. * @since 1.2.0 
  64. * 
  65. * @param BP_Groups_Group $group Single group object. 
  66. */ 
  67. return apply_filters( 'groups_get_group', $group ); 
  68.  
  69. /** Group Creation, Editing & Deletion ****************************************/ 
  70.  
  71. /** 
  72. * Create a group. 
  73. * 
  74. * @since 1.0.0 
  75. * 
  76. * @param array|string $args { 
  77. * An array of arguments. 
  78. * @type int|bool $group_id Pass a group ID to update an existing item, or 
  79. * 0 / false to create a new group. Default: 0. 
  80. * @type int $creator_id The user ID that creates the group. 
  81. * @type string $name The group name. 
  82. * @type string $description Optional. The group's description. 
  83. * @type string $slug The group slug. 
  84. * @type string $status The group's status. Accepts 'public', 'private' or 
  85. * 'hidden'. Defaults to 'public'. 
  86. * @type int $parent_id The ID of the parent group. Default: 0. 
  87. * @type int $enable_forum Optional. Whether the group has a forum enabled. 
  88. * If the legacy forums are enabled for this group 
  89. * or if a bbPress forum is enabled for the group,  
  90. * set this to 1. Default: 0. 
  91. * @type string $date_created The GMT time, in Y-m-d h:i:s format, when the group 
  92. * was created. Defaults to the current time. 
  93. * } 
  94. * @return int|bool The ID of the group on success. False on error. 
  95. */ 
  96. function groups_create_group( $args = '' ) { 
  97.  
  98. $defaults = array( 
  99. 'group_id' => 0,  
  100. 'creator_id' => 0,  
  101. 'name' => '',  
  102. 'description' => '',  
  103. 'slug' => '',  
  104. 'status' => 'public',  
  105. 'parent_id' => 0,  
  106. 'enable_forum' => 0,  
  107. 'date_created' => bp_core_current_time() 
  108. ); 
  109.  
  110. $args = wp_parse_args( $args, $defaults ); 
  111. extract( $args, EXTR_SKIP ); 
  112.  
  113. // Pass an existing group ID. 
  114. if ( ! empty( $group_id ) ) { 
  115. $group = groups_get_group( $group_id ); 
  116. $name = ! empty( $name ) ? $name : $group->name; 
  117. $slug = ! empty( $slug ) ? $slug : $group->slug; 
  118. $description = ! empty( $description ) ? $description : $group->description; 
  119.  
  120. // Groups need at least a name. 
  121. if ( empty( $name ) ) { 
  122. return false; 
  123.  
  124. // Create a new group. 
  125. } else { 
  126. // Instantiate new group object. 
  127. $group = new BP_Groups_Group; 
  128.  
  129. // Set creator ID. 
  130. if ( $creator_id ) { 
  131. $group->creator_id = (int) $creator_id; 
  132. } elseif ( is_user_logged_in() ) { 
  133. $group->creator_id = bp_loggedin_user_id(); 
  134.  
  135. if ( ! $group->creator_id ) { 
  136. return false; 
  137.  
  138. // Validate status. 
  139. if ( ! groups_is_valid_status( $status ) ) { 
  140. return false; 
  141.  
  142. // Set group name. 
  143. $group->name = $name; 
  144. $group->description = $description; 
  145. $group->slug = $slug; 
  146. $group->status = $status; 
  147. $group->parent_id = $parent_id; 
  148. $group->enable_forum = (int) $enable_forum; 
  149. $group->date_created = $date_created; 
  150.  
  151. // Save group. 
  152. if ( ! $group->save() ) { 
  153. return false; 
  154.  
  155. // If this is a new group, set up the creator as the first member and admin. 
  156. if ( empty( $group_id ) ) { 
  157. $member = new BP_Groups_Member; 
  158. $member->group_id = $group->id; 
  159. $member->user_id = $group->creator_id; 
  160. $member->is_admin = 1; 
  161. $member->user_title = __( 'Group Admin', 'buddypress' ); 
  162. $member->is_confirmed = 1; 
  163. $member->date_modified = bp_core_current_time(); 
  164. $member->save(); 
  165.  
  166. /** 
  167. * Fires after the creation of a new group and a group creator needs to be made. 
  168. * 
  169. * @since 1.5.0 
  170. * 
  171. * @param int $id ID of the newly created group. 
  172. * @param BP_Groups_Member $member Instance of the member who is assigned 
  173. * as group creator. 
  174. * @param BP_Groups_Group $group Instance of the group being created. 
  175. */ 
  176. do_action( 'groups_create_group', $group->id, $member, $group ); 
  177.  
  178. } else { 
  179.  
  180. /** 
  181. * Fires after the update of a group. 
  182. * 
  183. * @since 1.5.0 
  184. * 
  185. * @param int $id ID of the updated group. 
  186. * @param BP_Groups_Group $group Instance of the group being updated. 
  187. */ 
  188. do_action( 'groups_update_group', $group->id, $group ); 
  189.  
  190. /** 
  191. * Fires after the creation or update of a group. 
  192. * 
  193. * @since 1.0.0 
  194. * 
  195. * @param int $id ID of the newly created group. 
  196. * @param BP_Groups_Group $group Instance of the group being updated. 
  197. */ 
  198. do_action( 'groups_created_group', $group->id, $group ); 
  199.  
  200. return $group->id; 
  201.  
  202. /** 
  203. * Edit the base details for a group. 
  204. * 
  205. * These are the settings that appear on the first page of the group's Admin 
  206. * section (Name, Description, and "Notify members..."). 
  207. * 
  208. * @since 1.0.0 
  209. * 
  210. * @param int $group_id ID of the group. 
  211. * @param string $group_name Name of the group. 
  212. * @param string $group_desc Description of the group. 
  213. * @param bool $notify_members Whether to send an email notification to group 
  214. * members about changes in these details. 
  215. * @return bool True on success, false on failure. 
  216. */ 
  217. function groups_edit_base_group_details( $group_id, $group_name, $group_desc, $notify_members ) { 
  218.  
  219. if ( empty( $group_name ) || empty( $group_desc ) ) 
  220. return false; 
  221.  
  222. $group = groups_get_group( $group_id ); 
  223. $old_group = clone $group; 
  224.  
  225. $group->name = $group_name; 
  226. $group->description = $group_desc; 
  227.  
  228. if ( !$group->save() ) 
  229. return false; 
  230.  
  231. if ( $notify_members ) { 
  232. groups_notification_group_updated( $group->id, $old_group ); 
  233.  
  234. /** 
  235. * Fired after a group's details are updated. 
  236. * 
  237. * @since 2.2.0 
  238. * 
  239. * @param int $value ID of the group. 
  240. * @param BP_Groups_Group $old_group Group object, before being modified. 
  241. * @param bool $notify_members Whether to send an email notification to members about the change. 
  242. */ 
  243. do_action( 'groups_details_updated', $group->id, $old_group, $notify_members ); 
  244.  
  245. return true; 
  246.  
  247. /** 
  248. * Edit the base details for a group. 
  249. * 
  250. * These are the settings that appear on the Settings page of the group's Admin 
  251. * section (privacy settings, "enable forum", invitation status). 
  252. * 
  253. * @since 1.0.0 
  254. * 
  255. * @param int $group_id ID of the group. 
  256. * @param bool $enable_forum Whether to enable a forum for the group. 
  257. * @param string $status Group status. 'public', 'private', 'hidden'. 
  258. * @param string|bool $invite_status Optional. Who is allowed to send invitations 
  259. * to the group. 'members', 'mods', or 'admins'. 
  260. * @return bool True on success, false on failure. 
  261. */ 
  262. function groups_edit_group_settings( $group_id, $enable_forum, $status, $invite_status = false, $parent_id = false ) { 
  263.  
  264. $group = groups_get_group( $group_id ); 
  265. $group->enable_forum = $enable_forum; 
  266.  
  267. /** 
  268. * Before we potentially switch the group status, if it has been changed to public 
  269. * from private and there are outstanding membership requests, auto-accept those requests. 
  270. */ 
  271. if ( 'private' == $group->status && 'public' == $status ) 
  272. groups_accept_all_pending_membership_requests( $group->id ); 
  273.  
  274. // Now update the status. 
  275. $group->status = $status; 
  276.  
  277. // Update the parent ID if necessary. 
  278. if ( false !== $parent_id ) { 
  279. $group->parent_id = $parent_id; 
  280.  
  281. if ( !$group->save() ) 
  282. return false; 
  283.  
  284. // If forums have been enabled, and a forum does not yet exist, we need to create one. 
  285. if ( $group->enable_forum ) { 
  286. if ( bp_is_active( 'forums' ) && !groups_get_groupmeta( $group->id, 'forum_id' ) ) { 
  287. groups_new_group_forum( $group->id, $group->name, $group->description ); 
  288.  
  289. // Set the invite status. 
  290. if ( $invite_status ) 
  291. groups_update_groupmeta( $group->id, 'invite_status', $invite_status ); 
  292.  
  293. groups_update_groupmeta( $group->id, 'last_activity', bp_core_current_time() ); 
  294.  
  295. /** 
  296. * Fires after the update of a groups settings. 
  297. * 
  298. * @since 1.0.0 
  299. * 
  300. * @param int $id ID of the group that was updated. 
  301. */ 
  302. do_action( 'groups_settings_updated', $group->id ); 
  303.  
  304. return true; 
  305.  
  306. /** 
  307. * Delete a group and all of its associated metadata. 
  308. * 
  309. * @since 1.0.0 
  310. * 
  311. * @param int $group_id ID of the group to delete. 
  312. * @return bool True on success, false on failure. 
  313. */ 
  314. function groups_delete_group( $group_id ) { 
  315.  
  316. /** 
  317. * Fires before the deletion of a group. 
  318. * 
  319. * @since 1.5.0 
  320. * 
  321. * @param int $group_id ID of the group to be deleted. 
  322. */ 
  323. do_action( 'groups_before_delete_group', $group_id ); 
  324.  
  325. // Get the group object. 
  326. $group = groups_get_group( $group_id ); 
  327.  
  328. // Bail if group cannot be deleted. 
  329. if ( ! $group->delete() ) { 
  330. return false; 
  331.  
  332. // Remove all outstanding invites for this group. 
  333. groups_delete_all_group_invites( $group_id ); 
  334.  
  335. /** 
  336. * Fires after the deletion of a group. 
  337. * 
  338. * @since 1.0.0 
  339. * 
  340. * @param int $group_id ID of the group that was deleted. 
  341. */ 
  342. do_action( 'groups_delete_group', $group_id ); 
  343.  
  344. return true; 
  345.  
  346. /** 
  347. * Check a group status (eg 'private') against the whitelist of registered statuses. 
  348. * 
  349. * @since 1.1.0 
  350. * 
  351. * @param string $status Status to check. 
  352. * @return bool True if status is allowed, otherwise false. 
  353. */ 
  354. function groups_is_valid_status( $status ) { 
  355. $bp = buddypress(); 
  356.  
  357. return in_array( $status, (array) $bp->groups->valid_status ); 
  358.  
  359. /** 
  360. * Provide a unique, sanitized version of a group slug. 
  361. * 
  362. * @since 1.0.0 
  363. * 
  364. * @param string $slug Group slug to check. 
  365. * @return string $slug A unique and sanitized slug. 
  366. */ 
  367. function groups_check_slug( $slug ) { 
  368. $bp = buddypress(); 
  369.  
  370. if ( 'wp' == substr( $slug, 0, 2 ) ) 
  371. $slug = substr( $slug, 2, strlen( $slug ) - 2 ); 
  372.  
  373. if ( in_array( $slug, (array) $bp->groups->forbidden_names ) ) 
  374. $slug = $slug . '-' . rand(); 
  375.  
  376. if ( BP_Groups_Group::check_slug( $slug ) ) { 
  377. do { 
  378. $slug = $slug . '-' . rand(); 
  379. while ( BP_Groups_Group::check_slug( $slug ) ); 
  380.  
  381. return $slug; 
  382.  
  383. /** 
  384. * Get a group slug by its ID. 
  385. * 
  386. * @since 1.0.0 
  387. * 
  388. * @param int $group_id The numeric ID of the group. 
  389. * @return string The group's slug. 
  390. */ 
  391. function groups_get_slug( $group_id ) { 
  392. $group = groups_get_group( $group_id ); 
  393. return !empty( $group->slug ) ? $group->slug : ''; 
  394.  
  395. /** 
  396. * Get a group ID by its slug. 
  397. * 
  398. * @since 1.6.0 
  399. * 
  400. * @param string $group_slug The group's slug. 
  401. * @return int|null The group ID on success; null on failure. 
  402. */ 
  403. function groups_get_id( $group_slug ) { 
  404. return BP_Groups_Group::group_exists( $group_slug ); 
  405.  
  406. /** User Actions **************************************************************/ 
  407.  
  408. /** 
  409. * Remove a user from a group. 
  410. * 
  411. * @since 1.0.0 
  412. * 
  413. * @param int $group_id ID of the group. 
  414. * @param int $user_id Optional. ID of the user. Defaults to the currently 
  415. * logged-in user. 
  416. * @return bool True on success, false on failure. 
  417. */ 
  418. function groups_leave_group( $group_id, $user_id = 0 ) { 
  419.  
  420. if ( empty( $user_id ) ) 
  421. $user_id = bp_loggedin_user_id(); 
  422.  
  423. // Don't let single admins leave the group. 
  424. if ( count( groups_get_group_admins( $group_id ) ) < 2 ) { 
  425. if ( groups_is_user_admin( $user_id, $group_id ) ) { 
  426. bp_core_add_message( __( 'As the only admin, you cannot leave the group.', 'buddypress' ), 'error' ); 
  427. return false; 
  428.  
  429. if ( ! BP_Groups_Member::delete( $user_id, $group_id ) ) { 
  430. return false; 
  431.  
  432. bp_core_add_message( __( 'You successfully left the group.', 'buddypress' ) ); 
  433.  
  434. /** 
  435. * Fires after a user leaves a group. 
  436. * 
  437. * @since 1.0.0 
  438. * 
  439. * @param int $group_id ID of the group. 
  440. * @param int $user_id ID of the user leaving the group. 
  441. */ 
  442. do_action( 'groups_leave_group', $group_id, $user_id ); 
  443.  
  444. return true; 
  445.  
  446. /** 
  447. * Add a user to a group. 
  448. * 
  449. * @since 1.0.0 
  450. * 
  451. * @param int $group_id ID of the group. 
  452. * @param int $user_id Optional. ID of the user. Defaults to the currently 
  453. * logged-in user. 
  454. * @return bool True on success, false on failure. 
  455. */ 
  456. function groups_join_group( $group_id, $user_id = 0 ) { 
  457.  
  458. if ( empty( $user_id ) ) 
  459. $user_id = bp_loggedin_user_id(); 
  460.  
  461. // Check if the user has an outstanding invite. If so, delete it. 
  462. if ( groups_check_user_has_invite( $user_id, $group_id ) ) 
  463. groups_delete_invite( $user_id, $group_id ); 
  464.  
  465. // Check if the user has an outstanding request. If so, delete it. 
  466. if ( groups_check_for_membership_request( $user_id, $group_id ) ) 
  467. groups_delete_membership_request( null, $user_id, $group_id ); 
  468.  
  469. // User is already a member, just return true. 
  470. if ( groups_is_user_member( $user_id, $group_id ) ) 
  471. return true; 
  472.  
  473. $new_member = new BP_Groups_Member; 
  474. $new_member->group_id = $group_id; 
  475. $new_member->user_id = $user_id; 
  476. $new_member->inviter_id = 0; 
  477. $new_member->is_admin = 0; 
  478. $new_member->user_title = ''; 
  479. $new_member->date_modified = bp_core_current_time(); 
  480. $new_member->is_confirmed = 1; 
  481.  
  482. if ( !$new_member->save() ) 
  483. return false; 
  484.  
  485. $bp = buddypress(); 
  486.  
  487. if ( !isset( $bp->groups->current_group ) || !$bp->groups->current_group || $group_id != $bp->groups->current_group->id ) 
  488. $group = groups_get_group( $group_id ); 
  489. else 
  490. $group = $bp->groups->current_group; 
  491.  
  492. // Record this in activity streams. 
  493. groups_record_activity( array( 
  494. 'type' => 'joined_group',  
  495. 'item_id' => $group_id,  
  496. 'user_id' => $user_id,  
  497. ) ); 
  498.  
  499. /** 
  500. * Fires after a user joins a group. 
  501. * 
  502. * @since 1.0.0 
  503. * 
  504. * @param int $group_id ID of the group. 
  505. * @param int $user_id ID of the user joining the group. 
  506. */ 
  507. do_action( 'groups_join_group', $group_id, $user_id ); 
  508.  
  509. return true; 
  510.  
  511. /** General Group Functions ***************************************************/ 
  512.  
  513. /** 
  514. * Get a list of group administrators. 
  515. * 
  516. * @since 1.0.0 
  517. * 
  518. * @param int $group_id ID of the group. 
  519. * @return array Info about group admins (user_id + date_modified). 
  520. */ 
  521. function groups_get_group_admins( $group_id ) { 
  522. return BP_Groups_Member::get_group_administrator_ids( $group_id ); 
  523.  
  524. /** 
  525. * Get a list of group moderators. 
  526. * 
  527. * @since 1.0.0 
  528. * 
  529. * @param int $group_id ID of the group. 
  530. * @return array Info about group admins (user_id + date_modified). 
  531. */ 
  532. function groups_get_group_mods( $group_id ) { 
  533. return BP_Groups_Member::get_group_moderator_ids( $group_id ); 
  534.  
  535. /** 
  536. * Fetch the members of a group. 
  537. * 
  538. * Since BuddyPress 1.8, a procedural wrapper for BP_Group_Member_Query. 
  539. * Previously called BP_Groups_Member::get_all_for_group(). 
  540. * 
  541. * To use the legacy query, filter 'bp_use_legacy_group_member_query',  
  542. * returning true. 
  543. * 
  544. * @since 1.0.0 
  545. * 
  546. * @param array $args { 
  547. * An array of optional arguments. 
  548. * @type int $group_id ID of the group whose members are being queried. 
  549. * Default: current group ID. 
  550. * @type int $page Page of results to be queried. Default: 1. 
  551. * @type int $per_page Number of items to return per page of results. 
  552. * Default: 20. 
  553. * @type int $max Optional. Max number of items to return. 
  554. * @type array $exclude Optional. Array of user IDs to exclude. 
  555. * @type bool|int $value True (or 1) to exclude admins and mods from results. 
  556. * Default: 1. 
  557. * @type bool|int $value True (or 1) to exclude banned users from results. 
  558. * Default: 1. 
  559. * @type array $group_role Optional. Array of group roles to include. 
  560. * @type string $search_terms Optional. Filter results by a search string. 
  561. * @type string $type Optional. Sort the order of results. 'last_joined',  
  562. * 'first_joined', or any of the $type params available 
  563. * in {@link BP_User_Query}. Default: 'last_joined'. 
  564. * } 
  565. * @return array Multi-d array of 'members' list and 'count'. 
  566. */ 
  567. function groups_get_group_members( $args = array() ) { 
  568.  
  569. // Backward compatibility with old method of passing arguments. 
  570. if ( ! is_array( $args ) || func_num_args() > 1 ) { 
  571. _deprecated_argument( __METHOD__, '2.0.0', sprintf( __( 'Arguments passed to %1$s should be in an associative array. See the inline documentation at %2$s for more details.', 'buddypress' ), __METHOD__, __FILE__ ) ); 
  572.  
  573. $old_args_keys = array( 
  574. 0 => 'group_id',  
  575. 1 => 'per_page',  
  576. 2 => 'page',  
  577. 3 => 'exclude_admins_mods',  
  578. 4 => 'exclude_banned',  
  579. 5 => 'exclude',  
  580. 6 => 'group_role',  
  581. ); 
  582.  
  583. $args = bp_core_parse_args_array( $old_args_keys, func_get_args() ); 
  584.  
  585. $r = wp_parse_args( $args, array( 
  586. 'group_id' => bp_get_current_group_id(),  
  587. 'per_page' => false,  
  588. 'page' => false,  
  589. 'exclude_admins_mods' => true,  
  590. 'exclude_banned' => true,  
  591. 'exclude' => false,  
  592. 'group_role' => array(),  
  593. 'search_terms' => false,  
  594. 'type' => 'last_joined',  
  595. ) ); 
  596.  
  597. // For legacy users. Use of BP_Groups_Member::get_all_for_group() is deprecated. 
  598. if ( apply_filters( 'bp_use_legacy_group_member_query', false, __FUNCTION__, func_get_args() ) ) { 
  599. $retval = BP_Groups_Member::get_all_for_group( $r['group_id'], $r['per_page'], $r['page'], $r['exclude_admins_mods'], $r['exclude_banned'], $r['exclude'] ); 
  600. } else { 
  601.  
  602. // Both exclude_admins_mods and exclude_banned are legacy arguments. 
  603. // Convert to group_role. 
  604. if ( empty( $r['group_role'] ) ) { 
  605. $r['group_role'] = array( 'member' ); 
  606.  
  607. if ( ! $r['exclude_admins_mods'] ) { 
  608. $r['group_role'][] = 'mod'; 
  609. $r['group_role'][] = 'admin'; 
  610.  
  611. if ( ! $r['exclude_banned'] ) { 
  612. $r['group_role'][] = 'banned'; 
  613.  
  614. // Perform the group member query (extends BP_User_Query). 
  615. $members = new BP_Group_Member_Query( array( 
  616. 'group_id' => $r['group_id'],  
  617. 'per_page' => $r['per_page'],  
  618. 'page' => $r['page'],  
  619. 'group_role' => $r['group_role'],  
  620. 'exclude' => $r['exclude'],  
  621. 'search_terms' => $r['search_terms'],  
  622. 'type' => $r['type'],  
  623. ) ); 
  624.  
  625. // Structure the return value as expected by the template functions. 
  626. $retval = array( 
  627. 'members' => array_values( $members->results ),  
  628. 'count' => $members->total_users,  
  629. ); 
  630.  
  631. return $retval; 
  632.  
  633. /** 
  634. * Get the member count for a group. 
  635. * 
  636. * @since 1.2.3 
  637. * 
  638. * @param int $group_id Group ID. 
  639. * @return int Count of confirmed members for the group. 
  640. */ 
  641. function groups_get_total_member_count( $group_id ) { 
  642. return BP_Groups_Group::get_total_member_count( $group_id ); 
  643.  
  644. /** Group Fetching, Filtering & Searching ************************************/ 
  645.  
  646. /** 
  647. * Get a collection of groups, based on the parameters passed. 
  648. * 
  649. * @since 1.2.0 
  650. * @since 2.6.0 Added `$group_type`, `$group_type__in`, and `$group_type__not_in` parameters. 
  651. * @since 2.7.0 Added `$update_admin_cache` and `$parent_id` parameters. 
  652. * 
  653. * @param array|string $args { 
  654. * Array of arguments. Supports all arguments of 
  655. * {@link BP_Groups_Group::get()}. Where the default values differ, they 
  656. * have been described here. 
  657. * @type int $per_page Default: 20. 
  658. * @type int $page Default: 1. 
  659. * } 
  660. * @return array See {@link BP_Groups_Group::get()}. 
  661. */ 
  662. function groups_get_groups( $args = '' ) { 
  663.  
  664. $defaults = array( 
  665. 'type' => false, // Active, newest, alphabetical, random, popular, most-forum-topics or most-forum-posts. 
  666. 'order' => 'DESC', // 'ASC' or 'DESC' 
  667. 'orderby' => 'date_created', // date_created, last_activity, total_member_count, name, random. 
  668. 'user_id' => false, // Pass a user_id to limit to only groups that this user is a member of. 
  669. 'include' => false, // Only include these specific groups (group_ids). 
  670. 'exclude' => false, // Do not include these specific groups (group_ids). 
  671. 'parent_id' => null, // Get groups that are children of the specified group(s). 
  672. 'search_terms' => false, // Limit to groups that match these search terms. 
  673. 'search_columns' => array(), // Select which columns to search. 
  674. 'group_type' => '', // Array or comma-separated list of group types to limit results to. 
  675. 'group_type__in' => '', // Array or comma-separated list of group types to limit results to. 
  676. 'group_type__not_in' => '', // Array or comma-separated list of group types that will be excluded from results. 
  677. 'meta_query' => false, // Filter by groupmeta. See WP_Meta_Query for syntax. 
  678. 'show_hidden' => false, // Show hidden groups to non-admins. 
  679. 'per_page' => 20, // The number of results to return per page. 
  680. 'page' => 1, // The page to return if limiting per page. 
  681. 'update_meta_cache' => true, // Pre-fetch groupmeta for queried groups. 
  682. 'update_admin_cache' => false,  
  683. ); 
  684.  
  685. $r = bp_parse_args( $args, $defaults, 'groups_get_groups' ); 
  686.  
  687. $groups = BP_Groups_Group::get( array( 
  688. 'type' => $r['type'],  
  689. 'user_id' => $r['user_id'],  
  690. 'include' => $r['include'],  
  691. 'exclude' => $r['exclude'],  
  692. 'parent_id' => $r['parent_id'],  
  693. 'search_terms' => $r['search_terms'],  
  694. 'search_columns' => $r['search_columns'],  
  695. 'group_type' => $r['group_type'],  
  696. 'group_type__in' => $r['group_type__in'],  
  697. 'group_type__not_in' => $r['group_type__not_in'],  
  698. 'meta_query' => $r['meta_query'],  
  699. 'show_hidden' => $r['show_hidden'],  
  700. 'per_page' => $r['per_page'],  
  701. 'page' => $r['page'],  
  702. 'update_meta_cache' => $r['update_meta_cache'],  
  703. 'update_admin_cache' => $r['update_admin_cache'],  
  704. 'order' => $r['order'],  
  705. 'orderby' => $r['orderby'],  
  706. ) ); 
  707.  
  708. /** 
  709. * Filters the collection of groups based on parsed parameters. 
  710. * 
  711. * @since 1.2.0 
  712. * 
  713. * @param BP_Groups_Group $groups Object of found groups based on parameters. 
  714. * Passed by reference. 
  715. * @param array $r Array of parsed arguments used for group query. 
  716. * Passed by reference. 
  717. */ 
  718. return apply_filters_ref_array( 'groups_get_groups', array( &$groups, &$r ) ); 
  719.  
  720. /** 
  721. * Get the total group count for the site. 
  722. * 
  723. * @since 1.2.0 
  724. * 
  725. * @return int 
  726. */ 
  727. function groups_get_total_group_count() { 
  728. $count = wp_cache_get( 'bp_total_group_count', 'bp' ); 
  729.  
  730. if ( false === $count ) { 
  731. $count = BP_Groups_Group::get_total_group_count(); 
  732. wp_cache_set( 'bp_total_group_count', $count, 'bp' ); 
  733.  
  734. return $count; 
  735.  
  736. /** 
  737. * Get the IDs of the groups of which a specified user is a member. 
  738. * 
  739. * @since 1.0.0 
  740. * 
  741. * @param int $user_id ID of the user. 
  742. * @param int $pag_num Optional. Max number of results to return. 
  743. * Default: false (no limit). 
  744. * @param int $pag_page Optional. Page offset of results to return. 
  745. * Default: false (no limit). 
  746. * @return array { 
  747. * @type array $groups Array of groups returned by paginated query. 
  748. * @type int $total Count of groups matching query. 
  749. * } 
  750. */ 
  751. function groups_get_user_groups( $user_id = 0, $pag_num = 0, $pag_page = 0 ) { 
  752.  
  753. if ( empty( $user_id ) ) 
  754. $user_id = bp_displayed_user_id(); 
  755.  
  756. return BP_Groups_Member::get_group_ids( $user_id, $pag_num, $pag_page ); 
  757.  
  758. /** 
  759. * Get a list of groups of which the specified user is a member. 
  760. * 
  761. * Get a list of the groups to which this member belongs,  
  762. * filtered by group membership status and role. 
  763. * Usage examples: Used with no arguments specified,  
  764. * 
  765. * bp_get_user_groups( bp_loggedin_user_id() ); 
  766. * 
  767. * returns an array of the groups in which the logged-in user 
  768. * is an unpromoted member. To fetch an array of all groups that 
  769. * the current user belongs to, in any membership role,  
  770. * member, moderator or administrator, use 
  771. * 
  772. * bp_get_user_groups( $user_id, array( 
  773. * 'is_admin' => null,  
  774. * 'is_mod' => null,  
  775. * ) ); 
  776. * 
  777. * @since 2.6.0 
  778. * 
  779. * @param int $user_id ID of the user. 
  780. * @param array $args { 
  781. * Array of optional args. 
  782. * @param bool|null $is_confirmed Whether to return only confirmed memberships. Pass `null` to disable this 
  783. * filter. Default: true. 
  784. * @param bool|null $is_banned Whether to return only banned memberships. Pass `null` to disable this filter. 
  785. * Default: false. 
  786. * @param bool|null $is_admin Whether to return only admin memberships. Pass `null` to disable this filter. 
  787. * Default: false. 
  788. * @param bool|null $is_mod Whether to return only mod memberships. Pass `null` to disable this filter. 
  789. * Default: false. 
  790. * @param bool|null $invite_sent Whether to return only memberships with 'invite_sent'. Pass `null` to disable 
  791. * this filter. Default: false. 
  792. * @param string $orderby Field to order by. Accepts 'id' (membership ID), 'group_id', 'date_modified'. 
  793. * Default: 'group_id'. 
  794. * @param string $order Sort order. Accepts 'ASC' or 'DESC'. Default: 'ASC'. 
  795. * } 
  796. * @return array Array of matching group memberships, keyed by group ID. 
  797. */ 
  798. function bp_get_user_groups( $user_id, $args = array() ) { 
  799. $r = bp_parse_args( $args, array( 
  800. 'is_confirmed' => true,  
  801. 'is_banned' => false,  
  802. 'is_admin' => false,  
  803. 'is_mod' => false,  
  804. 'invite_sent' => null,  
  805. 'orderby' => 'group_id',  
  806. 'order' => 'ASC',  
  807. ), 'get_user_groups' ); 
  808.  
  809. $user_id = intval( $user_id ); 
  810.  
  811. $membership_ids = wp_cache_get( $user_id, 'bp_groups_memberships_for_user' ); 
  812. if ( false === $membership_ids ) { 
  813. $membership_ids = BP_Groups_Member::get_membership_ids_for_user( $user_id ); 
  814. wp_cache_set( $user_id, $membership_ids, 'bp_groups_memberships_for_user' ); 
  815.  
  816. // Prime the membership cache. 
  817. $uncached_membership_ids = bp_get_non_cached_ids( $membership_ids, 'bp_groups_memberships' ); 
  818. if ( ! empty( $uncached_membership_ids ) ) { 
  819. $uncached_memberships = BP_Groups_Member::get_memberships_by_id( $uncached_membership_ids ); 
  820.  
  821. foreach ( $uncached_memberships as $uncached_membership ) { 
  822. wp_cache_set( $uncached_membership->id, $uncached_membership, 'bp_groups_memberships' ); 
  823.  
  824. // Assemble filter array for use in `wp_list_filter()`. 
  825. $filters = wp_array_slice_assoc( $r, array( 'is_confirmed', 'is_banned', 'is_admin', 'is_mod', 'invite_sent' ) ); 
  826. foreach ( $filters as $filter_name => $filter_value ) { 
  827. if ( is_null( $filter_value ) ) { 
  828. unset( $filters[ $filter_name ] ); 
  829.  
  830. // Populate group membership array from cache, and normalize. 
  831. $groups = array(); 
  832. $int_keys = array( 'id', 'group_id', 'user_id', 'inviter_id' ); 
  833. $bool_keys = array( 'is_admin', 'is_mod', 'is_confirmed', 'is_banned', 'invite_sent' ); 
  834. foreach ( $membership_ids as $membership_id ) { 
  835. $membership = wp_cache_get( $membership_id, 'bp_groups_memberships' ); 
  836.  
  837. // Sanity check. 
  838. if ( ! isset( $membership->group_id ) ) { 
  839. continue; 
  840.  
  841. // Integer values. 
  842. foreach ( $int_keys as $index ) { 
  843. $membership->{$index} = intval( $membership->{$index} ); 
  844.  
  845. // Boolean values. 
  846. foreach ( $bool_keys as $index ) { 
  847. $membership->{$index} = (bool) $membership->{$index}; 
  848.  
  849. foreach ( $filters as $filter_name => $filter_value ) { 
  850. if ( ! isset( $membership->{$filter_name} ) || $filter_value != $membership->{$filter_name} ) { 
  851. continue 2; 
  852.  
  853. $group_id = (int) $membership->group_id; 
  854.  
  855. $groups[ $group_id ] = $membership; 
  856.  
  857. // By default, results are ordered by membership id. 
  858. if ( 'group_id' === $r['orderby'] ) { 
  859. ksort( $groups ); 
  860. } elseif ( in_array( $r['orderby'], array( 'id', 'date_modified' ) ) ) { 
  861. $groups = bp_sort_by_key( $groups, $r['orderby'] ); 
  862.  
  863. // By default, results are ordered ASC. 
  864. if ( 'DESC' === strtoupper( $r['order'] ) ) { 
  865. // `true` to preserve keys. 
  866. $groups = array_reverse( $groups, true ); 
  867.  
  868. return $groups; 
  869.  
  870. /** 
  871. * Get the count of groups of which the specified user is a member. 
  872. * 
  873. * @since 1.0.0 
  874. * 
  875. * @param int $user_id Optional. Default: ID of the displayed user. 
  876. * @return int Group count. 
  877. */ 
  878. function groups_total_groups_for_user( $user_id = 0 ) { 
  879.  
  880. if ( empty( $user_id ) ) 
  881. $user_id = ( bp_displayed_user_id() ) ? bp_displayed_user_id() : bp_loggedin_user_id(); 
  882.  
  883. $count = wp_cache_get( 'bp_total_groups_for_user_' . $user_id, 'bp' ); 
  884.  
  885. if ( false === $count ) { 
  886. $count = BP_Groups_Member::total_group_count( $user_id ); 
  887. wp_cache_set( 'bp_total_groups_for_user_' . $user_id, $count, 'bp' ); 
  888.  
  889. return (int) $count; 
  890.  
  891. /** 
  892. * Get the BP_Groups_Group object corresponding to the current group. 
  893. * 
  894. * @since 1.5.0 
  895. * 
  896. * @return BP_Groups_Group The current group object. 
  897. */ 
  898. function groups_get_current_group() { 
  899. $bp = buddypress(); 
  900.  
  901. $current_group = isset( $bp->groups->current_group ) 
  902. ? $bp->groups->current_group 
  903. : false; 
  904.  
  905. /** 
  906. * Filters the BP_Groups_Group object corresponding to the current group. 
  907. * 
  908. * @since 1.5.0 
  909. * 
  910. * @param BP_Groups_Group $current_group Current BP_Groups_Group object. 
  911. */ 
  912. return apply_filters( 'groups_get_current_group', $current_group ); 
  913.  
  914. /** Group Avatars *************************************************************/ 
  915.  
  916. /** 
  917. * Generate the avatar upload directory path for a given group. 
  918. * 
  919. * @since 1.1.0 
  920. * 
  921. * @param int $group_id Optional. ID of the group. Default: ID of the current group. 
  922. * @return string 
  923. */ 
  924. function groups_avatar_upload_dir( $group_id = 0 ) { 
  925.  
  926. if ( empty( $group_id ) ) { 
  927. $group_id = bp_get_current_group_id(); 
  928.  
  929. $directory = 'group-avatars'; 
  930. $path = bp_core_avatar_upload_path() . '/' . $directory . '/' . $group_id; 
  931. $newbdir = $path; 
  932. $newurl = bp_core_avatar_url() . '/' . $directory . '/' . $group_id; 
  933. $newburl = $newurl; 
  934. $newsubdir = '/' . $directory . '/' . $group_id; 
  935.  
  936. /** 
  937. * Filters the avatar upload directory path for a given group. 
  938. * 
  939. * @since 1.1.0 
  940. * 
  941. * @param array $value Array of parts related to the groups avatar upload directory. 
  942. */ 
  943. return apply_filters( 'groups_avatar_upload_dir', array( 
  944. 'path' => $path,  
  945. 'url' => $newurl,  
  946. 'subdir' => $newsubdir,  
  947. 'basedir' => $newbdir,  
  948. 'baseurl' => $newburl,  
  949. 'error' => false 
  950. ) ); 
  951.  
  952. /** Group Member Status Checks ************************************************/ 
  953.  
  954. /** 
  955. * Check whether a user is an admin of a given group. 
  956. * 
  957. * @since 1.0.0 
  958. * 
  959. * @param int $user_id ID of the user. 
  960. * @param int $group_id ID of the group. 
  961. * @return int|bool ID of the membership if the user is admin, otherwise false. 
  962. */ 
  963. function groups_is_user_admin( $user_id, $group_id ) { 
  964. $is_admin = false; 
  965.  
  966. $user_groups = bp_get_user_groups( $user_id, array( 
  967. 'is_admin' => true,  
  968. ) ); 
  969.  
  970. if ( isset( $user_groups[ $group_id ] ) ) { 
  971. $is_admin = $user_groups[ $group_id ]->id; 
  972.  
  973. return $is_admin; 
  974.  
  975. /** 
  976. * Check whether a user is a mod of a given group. 
  977. * 
  978. * @since 1.0.0 
  979. * 
  980. * @param int $user_id ID of the user. 
  981. * @param int $group_id ID of the group. 
  982. * @return int|bool ID of the membership if the user is mod, otherwise false. 
  983. */ 
  984. function groups_is_user_mod( $user_id, $group_id ) { 
  985. $is_mod = false; 
  986.  
  987. $user_groups = bp_get_user_groups( $user_id, array( 
  988. 'is_mod' => true,  
  989. ) ); 
  990.  
  991. if ( isset( $user_groups[ $group_id ] ) ) { 
  992. $is_mod = $user_groups[ $group_id ]->id; 
  993.  
  994. return $is_mod; 
  995.  
  996. /** 
  997. * Check whether a user is a member of a given group. 
  998. * 
  999. * @since 1.0.0 
  1000. * 
  1001. * @param int $user_id ID of the user. 
  1002. * @param int $group_id ID of the group. 
  1003. * @return int|bool ID of the membership if the user is member, otherwise false. 
  1004. */ 
  1005. function groups_is_user_member( $user_id, $group_id ) { 
  1006. $is_member = false; 
  1007.  
  1008. $user_groups = bp_get_user_groups( $user_id, array( 
  1009. 'is_admin' => null,  
  1010. 'is_mod' => null,  
  1011. ) ); 
  1012.  
  1013. if ( isset( $user_groups[ $group_id ] ) ) { 
  1014. $is_member = $user_groups[ $group_id ]->id; 
  1015.  
  1016. return $is_member; 
  1017.  
  1018. /** 
  1019. * Check whether a user is banned from a given group. 
  1020. * 
  1021. * @since 1.0.0 
  1022. * 
  1023. * @param int $user_id ID of the user. 
  1024. * @param int $group_id ID of the group. 
  1025. * @return int|bool ID of the membership if the user is banned, otherwise false. 
  1026. */ 
  1027. function groups_is_user_banned( $user_id, $group_id ) { 
  1028. $is_banned = false; 
  1029.  
  1030. $user_groups = bp_get_user_groups( $user_id, array( 
  1031. 'is_confirmed' => null,  
  1032. 'is_banned' => true,  
  1033. ) ); 
  1034.  
  1035. if ( isset( $user_groups[ $group_id ] ) ) { 
  1036. $is_banned = $user_groups[ $group_id ]->id; 
  1037.  
  1038. return $is_banned; 
  1039.  
  1040. /** 
  1041. * Check whether a user has an outstanding invitation to a group. 
  1042. * 
  1043. * @since 2.6.0 
  1044. * 
  1045. * @param int $user_id ID of the user. 
  1046. * @param int $group_id ID of the group. 
  1047. * @return int|bool ID of the membership if the user is invited, otherwise false. 
  1048. */ 
  1049. function groups_is_user_invited( $user_id, $group_id ) { 
  1050. $is_invited = false; 
  1051.  
  1052. $user_groups = bp_get_user_groups( $user_id, array( 
  1053. 'invite_sent' => true,  
  1054. 'is_confirmed' => false,  
  1055. ) ); 
  1056.  
  1057. if ( isset( $user_groups[ $group_id ] ) ) { 
  1058. $is_invited = $user_groups[ $group_id ]->id; 
  1059.  
  1060. return $is_invited; 
  1061.  
  1062. /** 
  1063. * Check whether a user has a pending membership request for a group. 
  1064. * 
  1065. * @since 2.6.0 
  1066. * 
  1067. * @param int $user_id ID of the user. 
  1068. * @param int $group_id ID of the group. 
  1069. * @return int|bool ID of the membership if the user is pending, otherwise false. 
  1070. */ 
  1071. function groups_is_user_pending( $user_id, $group_id ) { 
  1072. $is_pending = false; 
  1073.  
  1074. $user_groups = bp_get_user_groups( $user_id, array( 
  1075. 'invite_sent' => false,  
  1076. 'is_confirmed' => false,  
  1077. ) ); 
  1078.  
  1079. if ( isset( $user_groups[ $group_id ] ) ) { 
  1080. $is_pending = $user_groups[ $group_id ]->id; 
  1081.  
  1082. return $is_pending; 
  1083.  
  1084. /** 
  1085. * Is the specified user the creator of the group? 
  1086. * 
  1087. * @since 1.2.6 
  1088. * 
  1089. * @param int $user_id ID of the user. 
  1090. * @param int $group_id ID of the group. 
  1091. * @return bool 
  1092. */ 
  1093. function groups_is_user_creator( $user_id, $group_id ) { 
  1094. return BP_Groups_Member::check_is_creator( $user_id, $group_id ); 
  1095.  
  1096. /** Group Activity Posting ****************************************************/ 
  1097.  
  1098. /** 
  1099. * Post an Activity status update affiliated with a group. 
  1100. * 
  1101. * @since 1.2.0 
  1102. * @since 2.6.0 Added 'error_type' parameter to $args. 
  1103. * 
  1104. * @param array|string $args { 
  1105. * Array of arguments. 
  1106. * @type string $content The content of the update. 
  1107. * @type int $user_id Optional. ID of the user posting the update. Default: 
  1108. * ID of the logged-in user. 
  1109. * @type int $group_id Optional. ID of the group to be affiliated with the 
  1110. * update. Default: ID of the current group. 
  1111. * } 
  1112. * @return int|bool Returns the ID of the new activity item on success, or false on failure. 
  1113. */ 
  1114. function groups_post_update( $args = '' ) { 
  1115. if ( ! bp_is_active( 'activity' ) ) { 
  1116. return false; 
  1117.  
  1118. $bp = buddypress(); 
  1119.  
  1120. $defaults = array( 
  1121. 'content' => false,  
  1122. 'user_id' => bp_loggedin_user_id(),  
  1123. 'group_id' => 0,  
  1124. 'error_type' => 'bool' 
  1125. ); 
  1126.  
  1127. $r = wp_parse_args( $args, $defaults ); 
  1128. extract( $r, EXTR_SKIP ); 
  1129.  
  1130. if ( empty( $group_id ) && !empty( $bp->groups->current_group->id ) ) 
  1131. $group_id = $bp->groups->current_group->id; 
  1132.  
  1133. if ( empty( $content ) || !strlen( trim( $content ) ) || empty( $user_id ) || empty( $group_id ) ) 
  1134. return false; 
  1135.  
  1136. $bp->groups->current_group = groups_get_group( $group_id ); 
  1137.  
  1138. // Be sure the user is a member of the group before posting. 
  1139. if ( !bp_current_user_can( 'bp_moderate' ) && !groups_is_user_member( $user_id, $group_id ) ) 
  1140. return false; 
  1141.  
  1142. // Record this in activity streams. 
  1143. $activity_action = sprintf( __( '%1$s posted an update in the group %2$s', 'buddypress'), bp_core_get_userlink( $user_id ), '<a href="' . bp_get_group_permalink( $bp->groups->current_group ) . '">' . esc_attr( $bp->groups->current_group->name ) . '</a>' ); 
  1144. $activity_content = $content; 
  1145.  
  1146. /** 
  1147. * Filters the action for the new group activity update. 
  1148. * 
  1149. * @since 1.2.0 
  1150. * 
  1151. * @param string $activity_action The new group activity update. 
  1152. */ 
  1153. $action = apply_filters( 'groups_activity_new_update_action', $activity_action ); 
  1154.  
  1155. /** 
  1156. * Filters the content for the new group activity update. 
  1157. * 
  1158. * @since 1.2.0 
  1159. * 
  1160. * @param string $activity_content The content of the update. 
  1161. */ 
  1162. $content_filtered = apply_filters( 'groups_activity_new_update_content', $activity_content ); 
  1163.  
  1164. $activity_id = groups_record_activity( array( 
  1165. 'user_id' => $user_id,  
  1166. 'action' => $action,  
  1167. 'content' => $content_filtered,  
  1168. 'type' => 'activity_update',  
  1169. 'item_id' => $group_id,  
  1170. 'error_type' => $error_type 
  1171. ) ); 
  1172.  
  1173. groups_update_groupmeta( $group_id, 'last_activity', bp_core_current_time() ); 
  1174.  
  1175. /** 
  1176. * Fires after posting of an Activity status update affiliated with a group. 
  1177. * 
  1178. * @since 1.2.0 
  1179. * 
  1180. * @param string $content The content of the update. 
  1181. * @param int $user_id ID of the user posting the update. 
  1182. * @param int $group_id ID of the group being posted to. 
  1183. * @param bool $activity_id Whether or not the activity recording succeeded. 
  1184. */ 
  1185. do_action( 'bp_groups_posted_update', $content, $user_id, $group_id, $activity_id ); 
  1186.  
  1187. return $activity_id; 
  1188.  
  1189. /** Group Invitations *********************************************************/ 
  1190.  
  1191. /** 
  1192. * Get IDs of users with outstanding invites to a given group from a specified user. 
  1193. * 
  1194. * @since 1.0.0 
  1195. * 
  1196. * @param int $user_id ID of the inviting user. 
  1197. * @param int|bool $limit Limit to restrict to. 
  1198. * @param int|bool $page Optional. Page offset of results to return. 
  1199. * @param string|array|bool $exclude Array of comma-separated list of group IDs 
  1200. * to exclude from results. 
  1201. * @return array $value IDs of users who have been invited to the group by the 
  1202. * user but have not yet accepted. 
  1203. */ 
  1204. function groups_get_invites_for_user( $user_id = 0, $limit = false, $page = false, $exclude = false ) { 
  1205.  
  1206. if ( empty( $user_id ) ) 
  1207. $user_id = bp_loggedin_user_id(); 
  1208.  
  1209. return BP_Groups_Member::get_invites( $user_id, $limit, $page, $exclude ); 
  1210.  
  1211. /** 
  1212. * Get the total group invite count for a user. 
  1213. * 
  1214. * @since 2.0.0 
  1215. * 
  1216. * @param int $user_id The user ID. 
  1217. * @return int 
  1218. */ 
  1219. function groups_get_invite_count_for_user( $user_id = 0 ) { 
  1220. if ( empty( $user_id ) ) { 
  1221. $user_id = bp_loggedin_user_id(); 
  1222.  
  1223. return BP_Groups_Member::get_invite_count_for_user( $user_id ); 
  1224.  
  1225. /** 
  1226. * Invite a user to a group. 
  1227. * 
  1228. * @since 1.0.0 
  1229. * 
  1230. * @param array|string $args { 
  1231. * Array of arguments. 
  1232. * @type int $user_id ID of the user being invited. 
  1233. * @type int $group_id ID of the group to which the user is being invited. 
  1234. * @type int $inviter_id Optional. ID of the inviting user. Default: 
  1235. * ID of the logged-in user. 
  1236. * @type string $date_modified Optional. Modified date for the invitation. 
  1237. * Default: current date/time. 
  1238. * @type bool $is_confirmed Optional. Whether the invitation should be 
  1239. * marked confirmed. Default: false. 
  1240. * } 
  1241. * @return bool True on success, false on failure. 
  1242. */ 
  1243. function groups_invite_user( $args = '' ) { 
  1244.  
  1245. $defaults = array( 
  1246. 'user_id' => false,  
  1247. 'group_id' => false,  
  1248. 'inviter_id' => bp_loggedin_user_id(),  
  1249. 'date_modified' => bp_core_current_time(),  
  1250. 'is_confirmed' => 0 
  1251. ); 
  1252.  
  1253. $args = wp_parse_args( $args, $defaults ); 
  1254. extract( $args, EXTR_SKIP ); 
  1255.  
  1256. if ( ! $user_id || ! $group_id || ! $inviter_id ) { 
  1257. return false; 
  1258.  
  1259. // If the user has already requested membership, accept the request. 
  1260. if ( $membership_id = groups_check_for_membership_request( $user_id, $group_id ) ) { 
  1261. groups_accept_membership_request( $membership_id, $user_id, $group_id ); 
  1262.  
  1263. // Otherwise, create a new invitation. 
  1264. } elseif ( ! groups_is_user_member( $user_id, $group_id ) && ! groups_check_user_has_invite( $user_id, $group_id, 'all' ) ) { 
  1265. $invite = new BP_Groups_Member; 
  1266. $invite->group_id = $group_id; 
  1267. $invite->user_id = $user_id; 
  1268. $invite->date_modified = $date_modified; 
  1269. $invite->inviter_id = $inviter_id; 
  1270. $invite->is_confirmed = $is_confirmed; 
  1271.  
  1272. if ( !$invite->save() ) 
  1273. return false; 
  1274.  
  1275. /** 
  1276. * Fires after the creation of a new group invite. 
  1277. * 
  1278. * @since 1.0.0 
  1279. * 
  1280. * @param array $args Array of parsed arguments for the group invite. 
  1281. */ 
  1282. do_action( 'groups_invite_user', $args ); 
  1283.  
  1284. return true; 
  1285.  
  1286. /** 
  1287. * Uninvite a user from a group. 
  1288. * 
  1289. * Functionally, this is equivalent to removing a user from a group. 
  1290. * 
  1291. * @since 1.0.0 
  1292. * 
  1293. * @param int $user_id ID of the user. 
  1294. * @param int $group_id ID of the group. 
  1295. * @return bool True on success, false on failure. 
  1296. */ 
  1297. function groups_uninvite_user( $user_id, $group_id ) { 
  1298.  
  1299. if ( ! BP_Groups_Member::delete_invite( $user_id, $group_id ) ) 
  1300. return false; 
  1301.  
  1302. /** 
  1303. * Fires after uninviting a user from a group. 
  1304. * 
  1305. * @since 1.0.0 
  1306. * 
  1307. * @param int $group_id ID of the group being uninvited from. 
  1308. * @param int $user_id ID of the user being uninvited. 
  1309. */ 
  1310. do_action( 'groups_uninvite_user', $group_id, $user_id ); 
  1311.  
  1312. return true; 
  1313.  
  1314. /** 
  1315. * Process the acceptance of a group invitation. 
  1316. * 
  1317. * Returns true if a user is already a member of the group. 
  1318. * 
  1319. * @since 1.0.0 
  1320. * 
  1321. * @param int $user_id ID of the user. 
  1322. * @param int $group_id ID of the group. 
  1323. * @return bool True when the user is a member of the group, otherwise false. 
  1324. */ 
  1325. function groups_accept_invite( $user_id, $group_id ) { 
  1326.  
  1327. // If the user is already a member (because BP at one point allowed two invitations to 
  1328. // slip through), delete all existing invitations/requests and return true. 
  1329. if ( groups_is_user_member( $user_id, $group_id ) ) { 
  1330. if ( groups_check_user_has_invite( $user_id, $group_id ) ) { 
  1331. groups_delete_invite( $user_id, $group_id ); 
  1332.  
  1333. if ( groups_check_for_membership_request( $user_id, $group_id ) ) { 
  1334. groups_delete_membership_request( null, $user_id, $group_id ); 
  1335.  
  1336. return true; 
  1337.  
  1338. $member = new BP_Groups_Member( $user_id, $group_id ); 
  1339.  
  1340. // Save the inviter ID so that we can pass it to the action below. 
  1341. $inviter_id = $member->inviter_id; 
  1342.  
  1343. $member->accept_invite(); 
  1344.  
  1345. if ( !$member->save() ) { 
  1346. return false; 
  1347.  
  1348. // Remove request to join. 
  1349. if ( $member->check_for_membership_request( $user_id, $group_id ) ) { 
  1350. $member->delete_request( $user_id, $group_id ); 
  1351.  
  1352. // Modify group meta. 
  1353. groups_update_groupmeta( $group_id, 'last_activity', bp_core_current_time() ); 
  1354.  
  1355. /** 
  1356. * Fires after a user has accepted a group invite. 
  1357. * 
  1358. * @since 1.0.0 
  1359. * @since 2.8.0 The $inviter_id arg was added. 
  1360. * 
  1361. * @param int $user_id ID of the user who accepted the group invite. 
  1362. * @param int $group_id ID of the group being accepted to. 
  1363. * @param int $inviter_id ID of the user who invited this user to the group. 
  1364. */ 
  1365. do_action( 'groups_accept_invite', $user_id, $group_id, $inviter_id ); 
  1366.  
  1367. return true; 
  1368.  
  1369. /** 
  1370. * Reject a group invitation. 
  1371. * 
  1372. * @since 1.0.0 
  1373. * 
  1374. * @param int $user_id ID of the user. 
  1375. * @param int $group_id ID of the group. 
  1376. * @return bool True on success, false on failure. 
  1377. */ 
  1378. function groups_reject_invite( $user_id, $group_id ) { 
  1379. if ( ! BP_Groups_Member::delete_invite( $user_id, $group_id ) ) 
  1380. return false; 
  1381.  
  1382. /** 
  1383. * Fires after a user rejects a group invitation. 
  1384. * 
  1385. * @since 1.0.0 
  1386. * 
  1387. * @param int $user_id ID of the user rejecting the invite. 
  1388. * @param int $group_id ID of the group being rejected. 
  1389. */ 
  1390. do_action( 'groups_reject_invite', $user_id, $group_id ); 
  1391.  
  1392. return true; 
  1393.  
  1394. /** 
  1395. * Delete a group invitation. 
  1396. * 
  1397. * @since 1.0.0 
  1398. * 
  1399. * @param int $user_id ID of the invited user. 
  1400. * @param int $group_id ID of the group. 
  1401. * @return bool True on success, false on failure. 
  1402. */ 
  1403. function groups_delete_invite( $user_id, $group_id ) { 
  1404. if ( ! BP_Groups_Member::delete_invite( $user_id, $group_id ) ) 
  1405. return false; 
  1406.  
  1407. /** 
  1408. * Fires after the deletion of a group invitation. 
  1409. * 
  1410. * @since 1.9.0 
  1411. * 
  1412. * @param int $user_id ID of the user whose invitation is being deleted. 
  1413. * @param int $group_id ID of the group whose invitation is being deleted. 
  1414. */ 
  1415. do_action( 'groups_delete_invite', $user_id, $group_id ); 
  1416.  
  1417. return true; 
  1418.  
  1419. /** 
  1420. * Send all pending invites by a single user to a specific group. 
  1421. * 
  1422. * @since 1.0.0 
  1423. * 
  1424. * @param int $user_id ID of the inviting user. 
  1425. * @param int $group_id ID of the group. 
  1426. */ 
  1427. function groups_send_invites( $user_id, $group_id ) { 
  1428.  
  1429. if ( empty( $user_id ) ) 
  1430. $user_id = bp_loggedin_user_id(); 
  1431.  
  1432. // Send friend invites. 
  1433. $invited_users = groups_get_invites_for_group( $user_id, $group_id ); 
  1434. $group = groups_get_group( $group_id ); 
  1435.  
  1436. for ( $i = 0, $count = count( $invited_users ); $i < $count; ++$i ) { 
  1437. $member = new BP_Groups_Member( $invited_users[$i], $group_id ); 
  1438.  
  1439. // Send the actual invite. 
  1440. groups_notification_group_invites( $group, $member, $user_id ); 
  1441.  
  1442. $member->invite_sent = 1; 
  1443. $member->save(); 
  1444.  
  1445. /** 
  1446. * Fires after the sending of invites for a group. 
  1447. * 
  1448. * @since 1.0.0 
  1449. * @since 2.5.0 Added $user_id to passed parameters. 
  1450. * 
  1451. * @param int $group_id ID of the group who's being invited to. 
  1452. * @param array $invited_users Array of users being invited to the group. 
  1453. * @param int $user_id ID of the inviting user. 
  1454. */ 
  1455. do_action( 'groups_send_invites', $group_id, $invited_users, $user_id ); 
  1456.  
  1457. /** 
  1458. * Get IDs of users with outstanding invites to a given group from a specified user. 
  1459. * 
  1460. * @since 1.0.0 
  1461. * 
  1462. * @param int $user_id ID of the inviting user. 
  1463. * @param int $group_id ID of the group. 
  1464. * @return array $value IDs of users who have been invited to the group by the 
  1465. * user but have not yet accepted. 
  1466. */ 
  1467. function groups_get_invites_for_group( $user_id, $group_id ) { 
  1468. return BP_Groups_Group::get_invites( $user_id, $group_id ); 
  1469.  
  1470. /** 
  1471. * Check to see whether a user has already been invited to a group. 
  1472. * 
  1473. * By default, the function checks for invitations that have been sent. 
  1474. * Entering 'all' as the $type parameter will return unsent invitations as 
  1475. * well (useful to make sure AJAX requests are not duplicated). 
  1476. * 
  1477. * @since 1.0.0 
  1478. * 
  1479. * @param int $user_id ID of potential group member. 
  1480. * @param int $group_id ID of potential group. 
  1481. * @param string $type Optional. Use 'sent' to check for sent invites,  
  1482. * 'all' to check for all. Default: 'sent'. 
  1483. * @return int|bool ID of the membership if found, otherwise false. 
  1484. */ 
  1485. function groups_check_user_has_invite( $user_id, $group_id, $type = 'sent' ) { 
  1486. $invite = false; 
  1487.  
  1488. $args = array( 
  1489. 'is_confirmed' => false,  
  1490. 'is_banned' => null,  
  1491. 'is_admin' => null,  
  1492. 'is_mod' => null,  
  1493. ); 
  1494.  
  1495. if ( 'sent' === $type ) { 
  1496. $args['invite_sent'] = true; 
  1497.  
  1498. $user_groups = bp_get_user_groups( $user_id, $args ); 
  1499.  
  1500. if ( isset( $user_groups[ $group_id ] ) && 0 !== $user_groups[ $group_id ]->inviter_id ) { 
  1501. $invite = $user_groups[ $group_id ]->id; 
  1502.  
  1503. return $invite; 
  1504.  
  1505. /** 
  1506. * Delete all invitations to a given group. 
  1507. * 
  1508. * @since 1.0.0 
  1509. * 
  1510. * @param int $group_id ID of the group whose invitations are being deleted. 
  1511. * @return int|null Number of rows records deleted on success, null on failure. 
  1512. */ 
  1513. function groups_delete_all_group_invites( $group_id ) { 
  1514. return BP_Groups_Group::delete_all_invites( $group_id ); 
  1515.  
  1516. /** Group Promotion & Banning *************************************************/ 
  1517.  
  1518. /** 
  1519. * Promote a member to a new status within a group. 
  1520. * 
  1521. * @since 1.0.0 
  1522. * 
  1523. * @param int $user_id ID of the user. 
  1524. * @param int $group_id ID of the group. 
  1525. * @param string $status The new status. 'mod' or 'admin'. 
  1526. * @return bool True on success, false on failure. 
  1527. */ 
  1528. function groups_promote_member( $user_id, $group_id, $status ) { 
  1529.  
  1530. if ( ! bp_is_item_admin() ) 
  1531. return false; 
  1532.  
  1533. $member = new BP_Groups_Member( $user_id, $group_id ); 
  1534.  
  1535. // Don't use this action. It's deprecated as of BuddyPress 1.6. 
  1536. do_action( 'groups_premote_member', $group_id, $user_id, $status ); 
  1537.  
  1538. /** 
  1539. * Fires before the promotion of a user to a new status. 
  1540. * 
  1541. * @since 1.6.0 
  1542. * 
  1543. * @param int $group_id ID of the group being promoted in. 
  1544. * @param int $user_id ID of the user being promoted. 
  1545. * @param string $status New status being promoted to. 
  1546. */ 
  1547. do_action( 'groups_promote_member', $group_id, $user_id, $status ); 
  1548.  
  1549. return $member->promote( $status ); 
  1550.  
  1551. /** 
  1552. * Demote a user to 'member' status within a group. 
  1553. * 
  1554. * @since 1.0.0 
  1555. * 
  1556. * @param int $user_id ID of the user. 
  1557. * @param int $group_id ID of the group. 
  1558. * @return bool True on success, false on failure. 
  1559. */ 
  1560. function groups_demote_member( $user_id, $group_id ) { 
  1561.  
  1562. if ( ! bp_is_item_admin() ) 
  1563. return false; 
  1564.  
  1565. $member = new BP_Groups_Member( $user_id, $group_id ); 
  1566.  
  1567. /** 
  1568. * Fires before the demotion of a user to 'member'. 
  1569. * 
  1570. * @since 1.0.0 
  1571. * 
  1572. * @param int $group_id ID of the group being demoted in. 
  1573. * @param int $user_id ID of the user being demoted. 
  1574. */ 
  1575. do_action( 'groups_demote_member', $group_id, $user_id ); 
  1576.  
  1577. return $member->demote(); 
  1578.  
  1579. /** 
  1580. * Ban a member from a group. 
  1581. * 
  1582. * @since 1.0.0 
  1583. * 
  1584. * @param int $user_id ID of the user. 
  1585. * @param int $group_id ID of the group. 
  1586. * @return bool True on success, false on failure. 
  1587. */ 
  1588. function groups_ban_member( $user_id, $group_id ) { 
  1589.  
  1590. if ( ! bp_is_item_admin() ) 
  1591. return false; 
  1592.  
  1593. $member = new BP_Groups_Member( $user_id, $group_id ); 
  1594.  
  1595. /** 
  1596. * Fires before the banning of a member from a group. 
  1597. * 
  1598. * @since 1.0.0 
  1599. * 
  1600. * @param int $group_id ID of the group being banned from. 
  1601. * @param int $user_id ID of the user being banned. 
  1602. */ 
  1603. do_action( 'groups_ban_member', $group_id, $user_id ); 
  1604.  
  1605. return $member->ban(); 
  1606.  
  1607. /** 
  1608. * Unban a member from a group. 
  1609. * 
  1610. * @since 1.0.0 
  1611. * 
  1612. * @param int $user_id ID of the user. 
  1613. * @param int $group_id ID of the group. 
  1614. * @return bool True on success, false on failure. 
  1615. */ 
  1616. function groups_unban_member( $user_id, $group_id ) { 
  1617.  
  1618. if ( ! bp_is_item_admin() ) 
  1619. return false; 
  1620.  
  1621. $member = new BP_Groups_Member( $user_id, $group_id ); 
  1622.  
  1623. /** 
  1624. * Fires before the unbanning of a member from a group. 
  1625. * 
  1626. * @since 1.0.0 
  1627. * 
  1628. * @param int $group_id ID of the group being unbanned from. 
  1629. * @param int $user_id ID of the user being unbanned. 
  1630. */ 
  1631. do_action( 'groups_unban_member', $group_id, $user_id ); 
  1632.  
  1633. return $member->unban(); 
  1634.  
  1635. /** Group Removal *************************************************************/ 
  1636.  
  1637. /** 
  1638. * Remove a member from a group. 
  1639. * 
  1640. * @since 1.2.6 
  1641. * 
  1642. * @param int $user_id ID of the user. 
  1643. * @param int $group_id ID of the group. 
  1644. * @return bool True on success, false on failure. 
  1645. */ 
  1646. function groups_remove_member( $user_id, $group_id ) { 
  1647.  
  1648. if ( ! bp_is_item_admin() ) { 
  1649. return false; 
  1650.  
  1651. $member = new BP_Groups_Member( $user_id, $group_id ); 
  1652.  
  1653. /** 
  1654. * Fires before the removal of a member from a group. 
  1655. * 
  1656. * @since 1.2.6 
  1657. * 
  1658. * @param int $group_id ID of the group being removed from. 
  1659. * @param int $user_id ID of the user being removed. 
  1660. */ 
  1661. do_action( 'groups_remove_member', $group_id, $user_id ); 
  1662.  
  1663. return $member->remove(); 
  1664.  
  1665. /** Group Membership **********************************************************/ 
  1666.  
  1667. /** 
  1668. * Create a group membership request. 
  1669. * 
  1670. * @since 1.0.0 
  1671. * 
  1672. * @param int $requesting_user_id ID of the user requesting membership. 
  1673. * @param int $group_id ID of the group. 
  1674. * @return bool True on success, false on failure. 
  1675. */ 
  1676. function groups_send_membership_request( $requesting_user_id, $group_id ) { 
  1677.  
  1678. // Prevent duplicate requests. 
  1679. if ( groups_check_for_membership_request( $requesting_user_id, $group_id ) ) 
  1680. return false; 
  1681.  
  1682. // Check if the user is already a member or is banned. 
  1683. if ( groups_is_user_member( $requesting_user_id, $group_id ) || groups_is_user_banned( $requesting_user_id, $group_id ) ) 
  1684. return false; 
  1685.  
  1686. // Check if the user is already invited - if so, simply accept invite. 
  1687. if ( groups_check_user_has_invite( $requesting_user_id, $group_id ) ) { 
  1688. groups_accept_invite( $requesting_user_id, $group_id ); 
  1689. return true; 
  1690.  
  1691. $requesting_user = new BP_Groups_Member; 
  1692. $requesting_user->group_id = $group_id; 
  1693. $requesting_user->user_id = $requesting_user_id; 
  1694. $requesting_user->inviter_id = 0; 
  1695. $requesting_user->is_admin = 0; 
  1696. $requesting_user->user_title = ''; 
  1697. $requesting_user->date_modified = bp_core_current_time(); 
  1698. $requesting_user->is_confirmed = 0; 
  1699. $requesting_user->comments = isset( $_POST['group-request-membership-comments'] ) ? $_POST['group-request-membership-comments'] : ''; 
  1700.  
  1701. if ( $requesting_user->save() ) { 
  1702. $admins = groups_get_group_admins( $group_id ); 
  1703.  
  1704. // Saved okay, now send the email notification. 
  1705. for ( $i = 0, $count = count( $admins ); $i < $count; ++$i ) 
  1706. groups_notification_new_membership_request( $requesting_user_id, $admins[$i]->user_id, $group_id, $requesting_user->id ); 
  1707.  
  1708. /** 
  1709. * Fires after the creation of a new membership request. 
  1710. * 
  1711. * @since 1.0.0 
  1712. * 
  1713. * @param int $requesting_user_id ID of the user requesting membership. 
  1714. * @param array $admins Array of group admins. 
  1715. * @param int $group_id ID of the group being requested to. 
  1716. * @param int $requesting_user->id ID of the user requesting membership. 
  1717. */ 
  1718. do_action( 'groups_membership_requested', $requesting_user_id, $admins, $group_id, $requesting_user->id ); 
  1719.  
  1720. return true; 
  1721.  
  1722. return false; 
  1723.  
  1724. /** 
  1725. * Accept a pending group membership request. 
  1726. * 
  1727. * @since 1.0.0 
  1728. * 
  1729. * @param int $membership_id ID of the membership object. 
  1730. * @param int $user_id Optional. ID of the user who requested membership. 
  1731. * Provide this value along with $group_id to override 
  1732. * $membership_id. 
  1733. * @param int $group_id Optional. ID of the group to which membership is being 
  1734. * requested. Provide this value along with $user_id to 
  1735. * override $membership_id. 
  1736. * @return bool True on success, false on failure. 
  1737. */ 
  1738. function groups_accept_membership_request( $membership_id, $user_id = 0, $group_id = 0 ) { 
  1739.  
  1740. if ( !empty( $user_id ) && !empty( $group_id ) ) { 
  1741. $membership = new BP_Groups_Member( $user_id, $group_id ); 
  1742. } else { 
  1743. $membership = new BP_Groups_Member( false, false, $membership_id ); 
  1744.  
  1745. $membership->accept_request(); 
  1746.  
  1747. if ( !$membership->save() ) { 
  1748. return false; 
  1749.  
  1750. // Check if the user has an outstanding invite, if so delete it. 
  1751. if ( groups_check_user_has_invite( $membership->user_id, $membership->group_id ) ) { 
  1752. groups_delete_invite( $membership->user_id, $membership->group_id ); 
  1753.  
  1754. /** 
  1755. * Fires after a group membership request has been accepted. 
  1756. * 
  1757. * @since 1.0.0 
  1758. * 
  1759. * @param int $user_id ID of the user who accepted membership. 
  1760. * @param int $group_id ID of the group that was accepted membership to. 
  1761. * @param bool $value If membership was accepted. 
  1762. */ 
  1763. do_action( 'groups_membership_accepted', $membership->user_id, $membership->group_id, true ); 
  1764.  
  1765. return true; 
  1766.  
  1767. /** 
  1768. * Reject a pending group membership request. 
  1769. * 
  1770. * @since 1.0.0 
  1771. * 
  1772. * @param int $membership_id ID of the membership object. 
  1773. * @param int $user_id Optional. ID of the user who requested membership. 
  1774. * Provide this value along with $group_id to override 
  1775. * $membership_id. 
  1776. * @param int $group_id Optional. ID of the group to which membership is being 
  1777. * requested. Provide this value along with $user_id to 
  1778. * override $membership_id. 
  1779. * @return bool True on success, false on failure. 
  1780. */ 
  1781. function groups_reject_membership_request( $membership_id, $user_id = 0, $group_id = 0 ) { 
  1782. if ( !$membership = groups_delete_membership_request( $membership_id, $user_id, $group_id ) ) { 
  1783. return false; 
  1784.  
  1785. /** 
  1786. * Fires after a group membership request has been rejected. 
  1787. * 
  1788. * @since 1.0.0 
  1789. * 
  1790. * @param int $user_id ID of the user who rejected membership. 
  1791. * @param int $group_id ID of the group that was rejected membership to. 
  1792. * @param bool $value If membership was accepted. 
  1793. */ 
  1794. do_action( 'groups_membership_rejected', $membership->user_id, $membership->group_id, false ); 
  1795.  
  1796. return true; 
  1797.  
  1798. /** 
  1799. * Delete a pending group membership request. 
  1800. * 
  1801. * @since 1.2.0 
  1802. * 
  1803. * @param int $membership_id ID of the membership object. 
  1804. * @param int $user_id Optional. ID of the user who requested membership. 
  1805. * Provide this value along with $group_id to override 
  1806. * $membership_id. 
  1807. * @param int $group_id Optional. ID of the group to which membership is being 
  1808. * requested. Provide this value along with $user_id to 
  1809. * override $membership_id. 
  1810. * @return bool True on success, false on failure. 
  1811. */ 
  1812. function groups_delete_membership_request( $membership_id, $user_id = 0, $group_id = 0 ) { 
  1813. if ( !empty( $user_id ) && !empty( $group_id ) ) 
  1814. $membership = new BP_Groups_Member( $user_id, $group_id ); 
  1815. else 
  1816. $membership = new BP_Groups_Member( false, false, $membership_id ); 
  1817.  
  1818. if ( ! BP_Groups_Member::delete_request( $membership->user_id, $membership->group_id ) ) 
  1819. return false; 
  1820.  
  1821. return $membership; 
  1822.  
  1823. /** 
  1824. * Check whether a user has an outstanding membership request for a given group. 
  1825. * 
  1826. * @since 1.0.0 
  1827. * 
  1828. * @param int $user_id ID of the user. 
  1829. * @param int $group_id ID of the group. 
  1830. * @return int|bool ID of the membership if found, otherwise false. 
  1831. */ 
  1832. function groups_check_for_membership_request( $user_id, $group_id ) { 
  1833. $request = false; 
  1834.  
  1835. $user_groups = bp_get_user_groups( $user_id, array( 
  1836. 'is_confirmed' => false,  
  1837. 'is_banned' => false,  
  1838. 'is_admin' => null,  
  1839. 'is_mod' => null 
  1840. ) ); 
  1841.  
  1842. if ( isset( $user_groups[ $group_id ] ) && 0 === $user_groups[ $group_id ]->inviter_id ) { 
  1843. $request = $user_groups[ $group_id ]->id; 
  1844.  
  1845. return $request; 
  1846.  
  1847. /** 
  1848. * Accept all pending membership requests to a group. 
  1849. * 
  1850. * @since 1.0.2 
  1851. * 
  1852. * @param int $group_id ID of the group. 
  1853. * @return bool True on success, false on failure. 
  1854. */ 
  1855. function groups_accept_all_pending_membership_requests( $group_id ) { 
  1856. $user_ids = BP_Groups_Member::get_all_membership_request_user_ids( $group_id ); 
  1857.  
  1858. if ( !$user_ids ) 
  1859. return false; 
  1860.  
  1861. foreach ( (array) $user_ids as $user_id ) 
  1862. groups_accept_membership_request( false, $user_id, $group_id ); 
  1863.  
  1864. /** 
  1865. * Fires after the acceptance of all pending membership requests to a group. 
  1866. * 
  1867. * @since 1.0.2 
  1868. * 
  1869. * @param int $group_id ID of the group whose pending memberships were accepted. 
  1870. */ 
  1871. do_action( 'groups_accept_all_pending_membership_requests', $group_id ); 
  1872.  
  1873. return true; 
  1874.  
  1875. /** Group Meta ****************************************************************/ 
  1876.  
  1877. /** 
  1878. * Delete metadata for a group. 
  1879. * 
  1880. * @since 1.0.0 
  1881. * 
  1882. * @param int $group_id ID of the group. 
  1883. * @param string|bool $meta_key The key of the row to delete. 
  1884. * @param string|bool $meta_value Optional. Metadata value. If specified, only delete 
  1885. * metadata entries with this value. 
  1886. * @param bool $delete_all Optional. If true, delete matching metadata entries 
  1887. * for all groups. Otherwise, only delete matching 
  1888. * metadata entries for the specified group. 
  1889. * Default: false. 
  1890. * @return bool True on success, false on failure. 
  1891. */ 
  1892. function groups_delete_groupmeta( $group_id, $meta_key = false, $meta_value = false, $delete_all = false ) { 
  1893. global $wpdb; 
  1894.  
  1895. // Legacy - if no meta_key is passed, delete all for the item. 
  1896. if ( empty( $meta_key ) ) { 
  1897. $keys = $wpdb->get_col( $wpdb->prepare( "SELECT meta_key FROM {$wpdb->groupmeta} WHERE group_id = %d", $group_id ) ); 
  1898.  
  1899. // With no meta_key, ignore $delete_all. 
  1900. $delete_all = false; 
  1901. } else { 
  1902. $keys = array( $meta_key ); 
  1903.  
  1904. add_filter( 'query', 'bp_filter_metaid_column_name' ); 
  1905.  
  1906. $retval = true; 
  1907. foreach ( $keys as $key ) { 
  1908. $retval = delete_metadata( 'group', $group_id, $key, $meta_value, $delete_all ); 
  1909.  
  1910. remove_filter( 'query', 'bp_filter_metaid_column_name' ); 
  1911.  
  1912. return $retval; 
  1913.  
  1914. /** 
  1915. * Get a piece of group metadata. 
  1916. * 
  1917. * @since 1.0.0 
  1918. * 
  1919. * @param int $group_id ID of the group. 
  1920. * @param string $meta_key Metadata key. 
  1921. * @param bool $single Optional. If true, return only the first value of the 
  1922. * specified meta_key. This parameter has no effect if 
  1923. * meta_key is empty. 
  1924. * @return mixed Metadata value. 
  1925. */ 
  1926. function groups_get_groupmeta( $group_id, $meta_key = '', $single = true ) { 
  1927. add_filter( 'query', 'bp_filter_metaid_column_name' ); 
  1928. $retval = get_metadata( 'group', $group_id, $meta_key, $single ); 
  1929. remove_filter( 'query', 'bp_filter_metaid_column_name' ); 
  1930.  
  1931. return $retval; 
  1932.  
  1933. /** 
  1934. * Update a piece of group metadata. 
  1935. * 
  1936. * @since 1.0.0 
  1937. * 
  1938. * @param int $group_id ID of the group. 
  1939. * @param string $meta_key Metadata key. 
  1940. * @param mixed $meta_value Value to store. 
  1941. * @param mixed $prev_value Optional. If specified, only update existing 
  1942. * metadata entries with the specified value. 
  1943. * Otherwise, update all entries. 
  1944. * @return bool|int $retval Returns false on failure. On successful update of existing 
  1945. * metadata, returns true. On successful creation of new metadata,  
  1946. * returns the integer ID of the new metadata row. 
  1947. */ 
  1948. function groups_update_groupmeta( $group_id, $meta_key, $meta_value, $prev_value = '' ) { 
  1949. add_filter( 'query', 'bp_filter_metaid_column_name' ); 
  1950. $retval = update_metadata( 'group', $group_id, $meta_key, $meta_value, $prev_value ); 
  1951. remove_filter( 'query', 'bp_filter_metaid_column_name' ); 
  1952.  
  1953. return $retval; 
  1954.  
  1955. /** 
  1956. * Add a piece of group metadata. 
  1957. * 
  1958. * @since 2.0.0 
  1959. * 
  1960. * @param int $group_id ID of the group. 
  1961. * @param string $meta_key Metadata key. 
  1962. * @param mixed $meta_value Metadata value. 
  1963. * @param bool $unique Optional. Whether to enforce a single metadata value 
  1964. * for the given key. If true, and the object already 
  1965. * has a value for the key, no change will be made. 
  1966. * Default: false. 
  1967. * @return int|bool The meta ID on successful update, false on failure. 
  1968. */ 
  1969. function groups_add_groupmeta( $group_id, $meta_key, $meta_value, $unique = false ) { 
  1970. add_filter( 'query', 'bp_filter_metaid_column_name' ); 
  1971. $retval = add_metadata( 'group', $group_id, $meta_key, $meta_value, $unique ); 
  1972. remove_filter( 'query', 'bp_filter_metaid_column_name' ); 
  1973.  
  1974. return $retval; 
  1975.  
  1976. /** Group Cleanup Functions ***************************************************/ 
  1977.  
  1978. /** 
  1979. * Delete all group membership information for the specified user. 
  1980. * 
  1981. * @since 1.0.0 
  1982. * 
  1983. * @param int $user_id ID of the user. 
  1984. */ 
  1985. function groups_remove_data_for_user( $user_id ) { 
  1986. BP_Groups_Member::delete_all_for_user( $user_id ); 
  1987.  
  1988. /** 
  1989. * Fires after the deletion of all data for a user. 
  1990. * 
  1991. * @since 1.1.0 
  1992. * 
  1993. * @param int $user_id ID of the user whose data is being deleted. 
  1994. */ 
  1995. do_action( 'groups_remove_data_for_user', $user_id ); 
  1996. add_action( 'wpmu_delete_user', 'groups_remove_data_for_user' ); 
  1997. add_action( 'delete_user', 'groups_remove_data_for_user' ); 
  1998. add_action( 'bp_make_spam_user', 'groups_remove_data_for_user' ); 
  1999.  
  2000. /** Group Types ***************************************************************/ 
  2001.  
  2002. /** 
  2003. * Register a group type. 
  2004. * 
  2005. * @since 2.6.0 
  2006. * @since 2.7.0 Introduce $has_directory, $show_in_create_screen, $show_in_list, and 
  2007. * $description, $create_screen_checked as $args parameters. 
  2008. * 
  2009. * @param string $group_type Unique string identifier for the group type. 
  2010. * @param array $args { 
  2011. * Array of arguments describing the group type. 
  2012. * 
  2013. * @type string|bool $has_directory Set the slug to be used for custom group directory page. eg. 
  2014. * example.com/groups/type/MY_SLUG. Default: false. 
  2015. * @type bool $show_in_create_screen Whether this group type is allowed to be selected on the group creation 
  2016. * page. Default: false. 
  2017. * @type bool|null $show_in_list Whether this group type should be shown in lists rendered by 
  2018. * bp_group_type_list(). Default: null. If $show_in_create_screen is true,  
  2019. * this will default to true, unless this is set explicitly to false. 
  2020. * @type string $description A short descriptive summary of what the group type is. Currently shown 
  2021. * on a group's "Manage > Settings" page when selecting group types. 
  2022. * @type bool $create_screen_checked If $show_in_create_screen is true, whether we should have our group type 
  2023. * checkbox checked by default. Handy if you want to imply that the group 
  2024. * type should be enforced, but decision lies with the group creator. 
  2025. * Default: false. 
  2026. * @type array $labels { 
  2027. * Array of labels to use in various parts of the interface. 
  2028. * 
  2029. * @type string $name Default name. Should typically be plural. 
  2030. * @type string $singular_name Singular name. 
  2031. * } 
  2032. * } 
  2033. * @return object|WP_Error Group type object on success, WP_Error object on failure. 
  2034. */ 
  2035. function bp_groups_register_group_type( $group_type, $args = array() ) { 
  2036. $bp = buddypress(); 
  2037.  
  2038. if ( isset( $bp->groups->types[ $group_type ] ) ) { 
  2039. return new WP_Error( 'bp_group_type_exists', __( 'Group type already exists.', 'buddypress' ), $group_type ); 
  2040.  
  2041. $r = bp_parse_args( $args, array( 
  2042. 'has_directory' => false,  
  2043. 'show_in_create_screen' => false,  
  2044. 'show_in_list' => null,  
  2045. 'description' => '',  
  2046. 'create_screen_checked' => false,  
  2047. 'labels' => array(),  
  2048. ), 'register_group_type' ); 
  2049.  
  2050. $group_type = sanitize_key( $group_type ); 
  2051.  
  2052. /** 
  2053. * Filters the list of illegal group type names. 
  2054. * 
  2055. * - 'any' is a special pseudo-type, representing items unassociated with any group type. 
  2056. * - 'null' is a special pseudo-type, representing users without any type. 
  2057. * - '_none' is used internally to denote an item that should not apply to any group types. 
  2058. * 
  2059. * @since 2.6.0 
  2060. * 
  2061. * @param array $illegal_names Array of illegal names. 
  2062. */ 
  2063. $illegal_names = apply_filters( 'bp_group_type_illegal_names', array( 'any', 'null', '_none' ) ); 
  2064. if ( in_array( $group_type, $illegal_names, true ) ) { 
  2065. return new WP_Error( 'bp_group_type_illegal_name', __( 'You may not register a group type with this name.', 'buddypress' ), $group_type ); 
  2066.  
  2067. // Store the group type name as data in the object (not just as the array key). 
  2068. $r['name'] = $group_type; 
  2069.  
  2070. // Make sure the relevant labels have been filled in. 
  2071. $default_name = isset( $r['labels']['name'] ) ? $r['labels']['name'] : ucfirst( $r['name'] ); 
  2072. $r['labels'] = array_merge( array( 
  2073. 'name' => $default_name,  
  2074. 'singular_name' => $default_name,  
  2075. ), $r['labels'] ); 
  2076.  
  2077. // Directory slug. 
  2078. if ( ! empty( $r['has_directory'] ) ) { 
  2079. // A string value is intepreted as the directory slug. 
  2080. if ( is_string( $r['has_directory'] ) ) { 
  2081. $directory_slug = $r['has_directory']; 
  2082.  
  2083. // Otherwise fall back on group type. 
  2084. } else { 
  2085. $directory_slug = $group_type; 
  2086.  
  2087. // Sanitize for use in URLs. 
  2088. $r['directory_slug'] = sanitize_title( $directory_slug ); 
  2089. $r['has_directory'] = true; 
  2090. } else { 
  2091. $r['directory_slug'] = ''; 
  2092. $r['has_directory'] = false; 
  2093.  
  2094. // Type lists. 
  2095. if ( true === $r['show_in_create_screen'] && is_null( $r['show_in_list'] ) ) { 
  2096. $r['show_in_list'] = true; 
  2097. } else { 
  2098. $r['show_in_list'] = (bool) $r['show_in_list']; 
  2099.  
  2100. $bp->groups->types[ $group_type ] = $type = (object) $r; 
  2101.  
  2102. /** 
  2103. * Fires after a group type is registered. 
  2104. * 
  2105. * @since 2.6.0 
  2106. * 
  2107. * @param string $group_type Group type identifier. 
  2108. * @param object $type Group type object. 
  2109. */ 
  2110. do_action( 'bp_groups_register_group_type', $group_type, $type ); 
  2111.  
  2112. return $type; 
  2113.  
  2114. /** 
  2115. * Get a list of all registered group type objects. 
  2116. * 
  2117. * @since 2.6.0 
  2118. * 
  2119. * @see bp_groups_register_group_type() for accepted arguments. 
  2120. * 
  2121. * @param array|string $args Optional. An array of key => value arguments to match against 
  2122. * the group type objects. Default empty array. 
  2123. * @param string $output Optional. The type of output to return. Accepts 'names' 
  2124. * or 'objects'. Default 'names'. 
  2125. * @param string $operator Optional. The logical operation to perform. 'or' means only one 
  2126. * element from the array needs to match; 'and' means all elements 
  2127. * must match. Accepts 'or' or 'and'. Default 'and'. 
  2128. * @return array $types A list of groups type names or objects. 
  2129. */ 
  2130. function bp_groups_get_group_types( $args = array(), $output = 'names', $operator = 'and' ) { 
  2131. $types = buddypress()->groups->types; 
  2132.  
  2133. $types = wp_filter_object_list( $types, $args, $operator ); 
  2134.  
  2135. /** 
  2136. * Filters the array of group type objects. 
  2137. * 
  2138. * This filter is run before the $output filter has been applied, so that 
  2139. * filtering functions have access to the entire group type objects. 
  2140. * 
  2141. * @since 2.6.0 
  2142. * 
  2143. * @param array $types group type objects, keyed by name. 
  2144. * @param array $args Array of key=>value arguments for filtering. 
  2145. * @param string $operator 'or' to match any of $args, 'and' to require all. 
  2146. */ 
  2147. $types = apply_filters( 'bp_groups_get_group_types', $types, $args, $operator ); 
  2148.  
  2149. if ( 'names' === $output ) { 
  2150. $types = wp_list_pluck( $types, 'name' ); 
  2151.  
  2152. return $types; 
  2153.  
  2154. /** 
  2155. * Retrieve a group type object by name. 
  2156. * 
  2157. * @since 2.6.0 
  2158. * 
  2159. * @param string $group_type The name of the group type. 
  2160. * @return object A group type object. 
  2161. */ 
  2162. function bp_groups_get_group_type_object( $group_type ) { 
  2163. $types = bp_groups_get_group_types( array(), 'objects' ); 
  2164.  
  2165. if ( empty( $types[ $group_type ] ) ) { 
  2166. return null; 
  2167.  
  2168. return $types[ $group_type ]; 
  2169.  
  2170. /** 
  2171. * Set type for a group. 
  2172. * 
  2173. * @since 2.6.0 
  2174. * @since 2.7.0 $group_type parameter also accepts an array of group types now. 
  2175. * 
  2176. * @param int $group ID of the group. 
  2177. * @param string|array $group_type Group type or array of group types to set. 
  2178. * @param bool $append Optional. True to append this to existing types for group,  
  2179. * false to replace. Default: false. 
  2180. * @return array $retval See bp_set_object_terms(). 
  2181. */ 
  2182. function bp_groups_set_group_type( $group_id, $group_type, $append = false ) { 
  2183. // Pass an empty group type to remove group's type. 
  2184. if ( ! empty( $group_type ) && is_string( $group_type ) && ! bp_groups_get_group_type_object( $group_type ) ) { 
  2185. return false; 
  2186.  
  2187. // Cast as array. 
  2188. $group_type = (array) $group_type; 
  2189.  
  2190. // Validate group types. 
  2191. foreach ( $group_type as $type ) { 
  2192. // Remove any invalid group types. 
  2193. if ( is_null( bp_groups_get_group_type_object( $type ) ) ) { 
  2194. unset( $group_type[ $type ] ); 
  2195.  
  2196. $retval = bp_set_object_terms( $group_id, $group_type, 'bp_group_type', $append ); 
  2197.  
  2198. // Bust the cache if the type has been updated. 
  2199. if ( ! is_wp_error( $retval ) ) { 
  2200. wp_cache_delete( $group_id, 'bp_groups_group_type' ); 
  2201.  
  2202. /** 
  2203. * Fires just after a group type has been changed. 
  2204. * 
  2205. * @since 2.6.0 
  2206. * 
  2207. * @param int $group_id ID of the group whose group type has been updated. 
  2208. * @param string|array $group_type Group type or array of group types. 
  2209. * @param bool $append Whether the type is being appended to existing types. 
  2210. */ 
  2211. do_action( 'bp_groups_set_group_type', $group_id, $group_type, $append ); 
  2212.  
  2213. return $retval; 
  2214.  
  2215. /** 
  2216. * Get type for a group. 
  2217. * 
  2218. * @since 2.6.0 
  2219. * 
  2220. * @param int $group_id ID of the group. 
  2221. * @param bool $single Optional. Whether to return a single type string. If multiple types are found 
  2222. * for the group, the oldest one will be returned. Default: true. 
  2223. * @return string|array|bool On success, returns a single group type (if `$single` is true) or an array of group 
  2224. * types (if `$single` is false). Returns false on failure. 
  2225. */ 
  2226. function bp_groups_get_group_type( $group_id, $single = true ) { 
  2227. $types = wp_cache_get( $group_id, 'bp_groups_group_type' ); 
  2228.  
  2229. if ( false === $types ) { 
  2230. $raw_types = bp_get_object_terms( $group_id, 'bp_group_type' ); 
  2231.  
  2232. if ( ! is_wp_error( $raw_types ) ) { 
  2233. $types = array(); 
  2234.  
  2235. // Only include currently registered group types. 
  2236. foreach ( $raw_types as $gtype ) { 
  2237. if ( bp_groups_get_group_type_object( $gtype->name ) ) { 
  2238. $types[] = $gtype->name; 
  2239.  
  2240. wp_cache_set( $group_id, $types, 'bp_groups_group_type' ); 
  2241.  
  2242. $type = false; 
  2243. if ( ! empty( $types ) ) { 
  2244. if ( $single ) { 
  2245. $type = end( $types ); 
  2246. } else { 
  2247. $type = $types; 
  2248.  
  2249. /** 
  2250. * Filters a groups's group type(s). 
  2251. * 
  2252. * @since 2.6.0 
  2253. * 
  2254. * @param string|array $type Group type. 
  2255. * @param int $group_id ID of the group. 
  2256. * @param bool $single Whether to return a single type string, or an array. 
  2257. */ 
  2258. return apply_filters( 'bp_groups_get_group_type', $type, $group_id, $single ); 
  2259.  
  2260. /** 
  2261. * Remove type for a group. 
  2262. * 
  2263. * @since 2.6.0 
  2264. * 
  2265. * @param int $group ID of the user. 
  2266. * @param string $group_type Group type. 
  2267. * @return bool|WP_Error $deleted True on success. False or WP_Error on failure. 
  2268. */ 
  2269. function bp_groups_remove_group_type( $group_id, $group_type ) { 
  2270. if ( empty( $group_type ) || ! bp_groups_get_group_type_object( $group_type ) ) { 
  2271. return false; 
  2272.  
  2273. $deleted = bp_remove_object_terms( $group_id, $group_type, 'bp_group_type' ); 
  2274.  
  2275. // Bust the case, if the type has been removed. 
  2276. if ( ! is_wp_error( $deleted ) ) { 
  2277. wp_cache_delete( $group_id, 'bp_groups_group_type' ); 
  2278.  
  2279. /** 
  2280. * Fires just after a group's group type has been removed. 
  2281. * 
  2282. * @since 2.6.0 
  2283. * 
  2284. * @param int $group ID of the group whose group type has been removed. 
  2285. * @param string $group_type Group type. 
  2286. */ 
  2287. do_action( 'bp_groups_remove_group_type', $group_id, $group_type ); 
  2288.  
  2289. return $deleted; 
  2290.  
  2291. /** 
  2292. * Check whether the given group has a certain group type. 
  2293. * 
  2294. * @since 2.6.0 
  2295. * 
  2296. * @param int $group_id ID of the group. 
  2297. * @param string $group_type Group type. 
  2298. * @return bool Whether the group has the give group type. 
  2299. */ 
  2300. function bp_groups_has_group_type( $group_id, $group_type ) { 
  2301. if ( empty( $group_type ) || ! bp_groups_get_group_type_object( $group_type ) ) { 
  2302. return false; 
  2303.  
  2304. // Get all group's group types. 
  2305. $types = bp_groups_get_group_type( $group_id, false ); 
  2306.  
  2307. if ( ! is_array( $types ) ) { 
  2308. return false; 
  2309.  
  2310. return in_array( $group_type, $types ); 
  2311.  
  2312. /** 
  2313. * Get the "current" group type, if one is provided, in group directories. 
  2314. * 
  2315. * @since 2.7.0 
  2316. * 
  2317. * @return string 
  2318. */ 
  2319. function bp_get_current_group_directory_type() { 
  2320.  
  2321. /** 
  2322. * Filters the "current" group type, if one is provided, in group directories. 
  2323. * 
  2324. * @since 2.7.0 
  2325. * 
  2326. * @param string $value "Current" group type. 
  2327. */ 
  2328. return apply_filters( 'bp_get_current_group_directory_type', buddypress()->groups->current_directory_type ); 
  2329.  
  2330. /** 
  2331. * Delete a group's type when the group is deleted. 
  2332. * 
  2333. * @since 2.6.0 
  2334. * 
  2335. * @param int $group_id ID of the group. 
  2336. * @return array $value See {@see bp_groups_set_group_type()}. 
  2337. */ 
  2338. function bp_remove_group_type_on_group_delete( $group_id = 0 ) { 
  2339. bp_groups_set_group_type( $group_id, '' ); 
  2340. add_action( 'groups_delete_group', 'bp_remove_group_type_on_group_delete' ); 
.