api/v3/GroupContact.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   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  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  * This api exposes CiviCRM GroupContact records.
  14  *
  15  * This api is for adding/removing contacts from a group,
  16  * or fetching a list of groups for a contact.
  17  *
  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.
  21  *
  22  * To create/delete groups, use the group api instead.
  23  *
  24  * @package CiviCRM_APIv3
  25  */
  26
  27 /**
  28  * Fetch a list of groups for a contact, or contacts for a group.
  29  *
  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.
  33  *
  34  * If no status mentioned in params, by default 'added' will be used
  35  * to fetch the records
  36  *
  37  * @param array $params
  38  *   Name value pair of contact information.
  39  *
  40  * @return array
  41  *   list of groups, given contact subsribed to
  42  */
  43 function civicrm_api3_group_contact_get($params) {
  44
  45   if (empty($params['contact_id'])) {
  46     if (empty($params['status'])) {
  47       //default to 'Added'
  48       $params['status'] = 'Added';
  49     }
  50     //ie. id passed in so we have to return something
  51     return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
  52   }
  53   $status = CRM_Utils_Array::value('status', $params, 'Added');
  54
  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');
  58 }
  59
  60 /**
  61  * Adjust metadata for Create action.
  62  *
  63  * @param array $params
  64  */
  65 function _civicrm_api3_group_contact_create_spec(&$params) {
  66   $params['contact_id']['api.required'] = 1;
  67   $params['group_id']['api.required'] = 1;
  68 }
  69
  70 /**
  71  * Add contact(s) to group(s).
  72  *
  73  * This api has a legacy/nonstandard signature.
  74  * On success, the return array will be structured as follows:
  75  * ```
  76  * array(
  77  *   "is_error" => 0,
  78  *   "version"  => 3,
  79  *   "count"    => 3,
  80  *   "values" => array(
  81  *     "not_added"   => integer,
  82  *     "added"       => integer,
  83  *     "total_count" => integer
  84  *   )
  85  * )
  86  * ```
  87  *
  88  * On failure, the return array will be structured as follows:
  89  * ```
  90  * array(
  91  *   'is_error' => 1,
  92  *   'error_message' = string,
  93  *   'error_data' = mixed or undefined
  94  * )
  95  * ```
  96  *
  97  * @param array $params
  98  *   Input parameters:
  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
 105  *
 106  * @return array
 107  *   Information about operation results
 108  */
 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'];
 117     }
 118   }
 119   $action = CRM_Utils_Array::value('status', $params, 'Added');
 120   return _civicrm_api3_group_contact_common($params, $action);
 121 }
 122
 123 /**
 124  * Delete group contact record.
 125  *
 126  * @param array $params
 127  * @return array
 128  * @throws API_Exception
 129  * @throws CiviCRM_API3_Exception
 130  * @deprecated
 131  */
 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']];
 136   }
 137   elseif (!empty($checkParams['status']) && $checkParams['status'] == 'Added') {
 138     $checkParams['status'] = ['IN' => ['Pending', 'Removed']];
 139   }
 140   elseif (!empty($checkParams['status'])) {
 141     unset($checkParams['status']);
 142   }
 143   $groupContact = civicrm_api3('GroupContact', 'get', $checkParams);
 144   if ($groupContact['count'] == 0 && !empty($params['skip_undelete'])) {
 145     $checkParams['status'] = ['IN' => ['Removed', 'Pending']];
 146   }
 147   $groupContact2 = civicrm_api3('GroupContact', 'get', $checkParams);
 148   if ($groupContact['count'] == 0 && $groupContact2['count'] == 0) {
 149     throw new API_Exception('Cannot Delete GroupContact');
 150   }
 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);
 154 }
 155
 156 /**
 157  * Adjust metadata.
 158  *
 159  * @param array $params
 160  */
 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;
 164 }
 165
 166 /**
 167  * Get pending group contacts.
 168  *
 169  * @param array $params
 170  *
 171  * @return array|int
 172  * @deprecated
 173  */
 174 function civicrm_api3_group_contact_pending($params) {
 175   $params['status'] = 'Pending';
 176   return civicrm_api('GroupContact', 'Create', $params);
 177 }
 178
 179 /**
 180  * Group contact helper function.
 181  *
 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
 184  *
 185  * @param array $params
 186  * @param string $op
 187  *
 188  * @return array
 189  */
 190 function _civicrm_api3_group_contact_common($params, $op = 'Added') {
 191
 192   $contactIDs = [];
 193   $groupIDs = [];
 194
 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') {
 199       if (is_array($v)) {
 200         foreach ($v as $arr_v) {
 201           $contactIDs[] = $arr_v;
 202         }
 203       }
 204       else {
 205         $contactIDs[] = $v;
 206       }
 207     }
 208     elseif (substr($n, 0, 8) == 'group_id') {
 209       if (is_array($v)) {
 210         foreach ($v as $arr_v) {
 211           $groupIDs[] = $arr_v;
 212         }
 213       }
 214       else {
 215         $groupIDs[] = $v;
 216       }
 217     }
 218   }
 219
 220   $method = CRM_Utils_Array::value('method', $params, 'API');
 221   $status = CRM_Utils_Array::value('status', $params, $op);
 222   $tracking = $params['tracking'] ?? NULL;
 223
 224   if ($op == 'Added' || $op == 'Pending') {
 225     $extraReturnValues = [
 226       'total_count' => 0,
 227       'added' => 0,
 228       'not_added' => 0,
 229     ];
 230     foreach ($groupIDs as $groupID) {
 231       list($tc, $a, $na) = CRM_Contact_BAO_GroupContact::addContactsToGroup($contactIDs,
 232         $groupID,
 233         $method,
 234         $status,
 235         $tracking
 236       );
 237       $extraReturnValues['total_count'] += $tc;
 238       $extraReturnValues['added'] += $a;
 239       $extraReturnValues['not_added'] += $na;
 240     }
 241   }
 242   else {
 243     $extraReturnValues = [
 244       'total_count' => 0,
 245       'removed' => 0,
 246       'not_removed' => 0,
 247     ];
 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;
 253     }
 254   }
 255   // can't pass this by reference
 256   $dao = NULL;
 257   return civicrm_api3_create_success(1, $params, 'GroupContact', 'create', $dao, $extraReturnValues);
 258 }
 259
 260 /**
 261  * Update group contact status.
 262  *
 263  * @deprecated - this should be part of create but need to know we aren't missing something
 264  *
 265  * @param array $params
 266  *
 267  * @return bool
 268  * @throws \API_Exception
 269  */
 270 function civicrm_api3_group_contact_update_status($params) {
 271
 272   civicrm_api3_verify_mandatory($params, NULL, ['contact_id', 'group_id']);
 273
 274   CRM_Contact_BAO_GroupContact::addContactsToGroup(
 275     [$params['contact_id']],
 276     $params['group_id'],
 277     CRM_Utils_Array::value('method', $params, 'API'),
 278     'Added',
 279     CRM_Utils_Array::value('tracking', $params)
 280   );
 281
 282   return TRUE;
 283 }
 284
 285 /**
 286  * Deprecated function notices.
 287  *
 288  * @deprecated api notice
 289  * @return array
 290  *   Array of deprecated actions
 291  */
 292 function _civicrm_api3_group_contact_deprecation() {
 293   return [
 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".',
 297   ];
 298 }