3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
6 | This work is published under the GNU AGPLv3 license with some |
7 | permitted exceptions and without any warranty. For full license |
8 | and copyright information, see https://civicrm.org/licensing |
9 +--------------------------------------------------------------------+
13 * This api exposes CiviCRM GroupContact records.
15 * This api is for adding/removing contacts from a group,
16 * or fetching a list of groups for a contact.
18 * Important note: This api does not fetch smart groups for a contact.
19 * To fetch all contacts in a smart group, use the Contact api
20 * passing a contact_id and group_id.
22 * To create/delete groups, use the group api instead.
24 * @package CiviCRM_APIv3
28 * Fetch a list of groups for a contact, or contacts for a group.
30 * @Note: this only applies to static groups, not smart groups.
31 * To fetch all contacts in a smart group, use the Contact api
32 * passing a contact_id and group_id.
34 * If no status mentioned in params, by default 'added' will be used
35 * to fetch the records
37 * @param array $params
38 * Name value pair of contact information.
41 * list of groups, given contact subsribed to
43 function civicrm_api3_group_contact_get($params) {
45 if (empty($params['contact_id'])) {
46 if (empty($params['status'])) {
48 $params['status'] = 'Added';
50 //ie. id passed in so we have to return something
51 return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__
), $params);
53 $status = CRM_Utils_Array
::value('status', $params, 'Added');
55 $groupId = $params['group_id'] ??
NULL;
56 $values = CRM_Contact_BAO_GroupContact
::getContactGroup($params['contact_id'], $status, NULL, FALSE, TRUE, FALSE, TRUE, $groupId);
57 return civicrm_api3_create_success($values, $params, 'GroupContact');
61 * Adjust metadata for Create action.
63 * @param array $params
65 function _civicrm_api3_group_contact_create_spec(&$params) {
66 $params['contact_id']['api.required'] = 1;
67 $params['group_id']['api.required'] = 1;
71 * Add contact(s) to group(s).
73 * This api has a legacy/nonstandard signature.
74 * On success, the return array will be structured as follows:
81 * "not_added" => integer,
83 * "total_count" => integer
88 * On failure, the return array will be structured as follows:
92 * 'error_message' = string,
93 * 'error_data' = mixed or undefined
97 * @param array $params
99 * - "contact_id" (required): First contact to add, or array of Contact IDs
100 * - "group_id" (required): First group to add contact(s) to, or array of Group IDs
101 * - "status" (optional): "Added" (default), "Pending" or "Removed"
102 * Legacy input parameters (will be deprecated):
103 * - "contact_id.1" etc. (optional): Additional contact_id to add to group(s)
104 * - "group_id.1" etc. (optional): Additional groups to add contact(s) to
107 * Information about operation results
109 function civicrm_api3_group_contact_create($params) {
110 // Nonstandard bao - doesn't accept ID as a param, so convert id to group_id + contact_id
111 if (!empty($params['id'])) {
112 $getParams = ['id' => $params['id']];
113 $info = _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__
), $getParams);
114 if (!empty($info['values'][$params['id']])) {
115 $params['group_id'] = $info['values'][$params['id']]['group_id'];
116 $params['contact_id'] = $info['values'][$params['id']]['contact_id'];
119 $action = CRM_Utils_Array
::value('status', $params, 'Added');
120 return _civicrm_api3_group_contact_common($params, $action);
124 * Delete group contact record.
126 * @param array $params
128 * @throws API_Exception
129 * @throws CiviCRM_API3_Exception
132 function civicrm_api3_group_contact_delete($params) {
133 $checkParams = $params;
134 if (!empty($checkParams['status']) && in_array($checkParams['status'], ['Removed', 'Deleted'])) {
135 $checkParams['status'] = ['IN' => ['Added', 'Pending']];
137 elseif (!empty($checkParams['status']) && $checkParams['status'] == 'Added') {
138 $checkParams['status'] = ['IN' => ['Pending', 'Removed']];
140 elseif (!empty($checkParams['status'])) {
141 unset($checkParams['status']);
143 $groupContact = civicrm_api3('GroupContact', 'get', $checkParams);
144 if ($groupContact['count'] == 0 && !empty($params['skip_undelete'])) {
145 $checkParams['status'] = ['IN' => ['Removed', 'Pending']];
147 $groupContact2 = civicrm_api3('GroupContact', 'get', $checkParams);
148 if ($groupContact['count'] == 0 && $groupContact2['count'] == 0) {
149 throw new API_Exception('Cannot Delete GroupContact');
151 $params['status'] = CRM_Utils_Array
::value('status', $params, empty($params['skip_undelete']) ?
'Removed' : 'Deleted');
152 // "Deleted" isn't a real option so skip the api wrapper to avoid pseudoconstant validation
153 return civicrm_api3_group_contact_create($params);
159 * @param array $params
161 function _civicrm_api3_group_contact_delete_spec(&$params) {
162 // set as not required no either/or std yet
163 $params['id']['api.required'] = 0;
167 * Get pending group contacts.
169 * @param array $params
174 function civicrm_api3_group_contact_pending($params) {
175 $params['status'] = 'Pending';
176 return civicrm_api('GroupContact', 'Create', $params);
180 * Group contact helper function.
182 * @todo behaviour is highly non-standard - need to figure out how to make this 'behave'
183 * & at the very least return IDs & details of the groups created / changed
185 * @param array $params
190 function _civicrm_api3_group_contact_common($params, $op = 'Added') {
195 // CRM-16959: Handle multiple Contact IDs and Group IDs in legacy format
196 // (contact_id.1, contact_id.2) or as an array
197 foreach ($params as $n => $v) {
198 if (substr($n, 0, 10) == 'contact_id') {
200 foreach ($v as $arr_v) {
201 $contactIDs[] = $arr_v;
208 elseif (substr($n, 0, 8) == 'group_id') {
210 foreach ($v as $arr_v) {
211 $groupIDs[] = $arr_v;
220 $method = CRM_Utils_Array
::value('method', $params, 'API');
221 $status = CRM_Utils_Array
::value('status', $params, $op);
222 $tracking = $params['tracking'] ??
NULL;
224 if ($op == 'Added' ||
$op == 'Pending') {
225 $extraReturnValues = [
230 foreach ($groupIDs as $groupID) {
231 list($tc, $a, $na) = CRM_Contact_BAO_GroupContact
::addContactsToGroup($contactIDs,
237 $extraReturnValues['total_count'] +
= $tc;
238 $extraReturnValues['added'] +
= $a;
239 $extraReturnValues['not_added'] +
= $na;
243 $extraReturnValues = [
248 foreach ($groupIDs as $groupID) {
249 list($tc, $r, $nr) = CRM_Contact_BAO_GroupContact
::removeContactsFromGroup($contactIDs, $groupID, $method, $status, $tracking);
250 $extraReturnValues['total_count'] +
= $tc;
251 $extraReturnValues['removed'] +
= $r;
252 $extraReturnValues['not_removed'] +
= $nr;
255 // can't pass this by reference
257 return civicrm_api3_create_success(1, $params, 'GroupContact', 'create', $dao, $extraReturnValues);
261 * Update group contact status.
263 * @deprecated - this should be part of create but need to know we aren't missing something
265 * @param array $params
268 * @throws \API_Exception
270 function civicrm_api3_group_contact_update_status($params) {
272 civicrm_api3_verify_mandatory($params, NULL, ['contact_id', 'group_id']);
274 CRM_Contact_BAO_GroupContact
::addContactsToGroup(
275 [$params['contact_id']],
277 CRM_Utils_Array
::value('method', $params, 'API'),
279 CRM_Utils_Array
::value('tracking', $params)
286 * Deprecated function notices.
288 * @deprecated api notice
290 * Array of deprecated actions
292 function _civicrm_api3_group_contact_deprecation() {
294 'delete' => 'GroupContact "delete" action is deprecated in favor of "create".',
295 'pending' => 'GroupContact "pending" action is deprecated in favor of "create".',
296 'update_status' => 'GroupContact "update_status" action is deprecated in favor of "create".',