api/v3/GroupContact.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.6                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2014                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  10  | CiviCRM is free software; you can copy, modify, and distribute it  |
  11  | under the terms of the GNU Affero General Public License           |
  12  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13  |                                                                    |
  14  | CiviCRM is distributed in the hope that it will be useful, but     |
  15  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17  | See the GNU Affero General Public License for more details.        |
  18  |                                                                    |
  19  | You should have received a copy of the GNU Affero General Public   |
  20  | License and the CiviCRM Licensing Exception along                  |
  21  | with this program; if not, contact CiviCRM LLC                     |
  22  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23  | GNU Affero General Public License or the licensing of CiviCRM,     |
  24  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25  +--------------------------------------------------------------------+
  26  */
  27
  28 /**
  29  * This api exposes CiviCRM group contacts.
  30  *
  31  * This api is for adding/removing contacts from a group,
  32  * or fetching a list of groups for a contact.
  33  *
  34  * Important note: This api does not fetch smart groups for a contact.
  35  * To fetch all contacts in a smart group, use the contact api
  36  * passing a contact_id and group_id.
  37  *
  38  * To create/delete groups, use the group api instead.
  39  *
  40  * @package CiviCRM_APIv3
  41  */
  42
  43
  44 /**
  45  * This API will give list of the groups for particular contact.
  46  *
  47  * Particular status can be sent in params array.
  48  *
  49  * If no status mentioned in params, by default 'added' will be used
  50  * to fetch the records
  51  *
  52  * @param array $params
  53  *   Name value pair of contact information.
  54  *
  55  * @return array
  56  *   list of groups, given contact subsribed to
  57  */
  58 function civicrm_api3_group_contact_get($params) {
  59
  60   if (empty($params['contact_id'])) {
  61     if (empty($params['status'])) {
  62       //default to 'Added'
  63       $params['status'] = 'Added';
  64     }
  65     //ie. id passed in so we have to return something
  66     return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
  67   }
  68   $status = CRM_Utils_Array::value('status', $params, 'Added');
  69
  70   $groupId = CRM_Utils_Array::value('group_id', $params);
  71   $values = &CRM_Contact_BAO_GroupContact::getContactGroup($params['contact_id'], $status, NULL, FALSE, TRUE, FALSE, TRUE, $groupId);
  72   return civicrm_api3_create_success($values, $params);
  73 }
  74
  75 /**
  76  * Add contact(s) to group(s).
  77  *
  78  * This api has a legacy/nonstandard signature.
  79  * On success, the return array will be structured as follows:
  80  * @code
  81  * array(
  82  *   "is_error" => 0,
  83  *   "version"  => 3,
  84  *   "count"    => 3,
  85  *   "values" => array(
  86  *     "not_added"   => integer,
  87  *     "added"       => integer,
  88  *     "total_count" => integer
  89  *   )
  90  * )
  91  * @endcode
  92  *
  93  * On failure, the return array will be structured as follows:
  94  * @code
  95  * array(
  96  *   'is_error' => 1,
  97  *   'error_message' = string,
  98  *   'error_data' = mixed or undefined
  99  * )
 100  * @endcode
 101  *
 102  * @param array $params
 103  *   Input parameters.
 104  *   - "contact_id" (required) : first contact to add
 105  *   - "group_id" (required): first group to add contact(s) to
 106  *   - "contact_id.1" etc. (optional) : another contact to add
 107  *   - "group_id.1" etc. (optional) : additional group to add contact(s) to
 108  *   - "status" (optional) : one of "Added", "Pending" or "Removed" (default is "Added")
 109  *
 110  * @return array
 111  *   Information about operation results
 112  */
 113 function civicrm_api3_group_contact_create($params) {
 114   // Nonstandard bao - doesn't accept ID as a param, so convert id to group_id + contact_id
 115   if (!empty($params['id'])) {
 116     $getParams = array('id' => $params['id']);
 117     $info = _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $getParams);
 118     if (!empty($info['values'][$params['id']])) {
 119       $params['group_id'] = $info['values'][$params['id']]['group_id'];
 120       $params['contact_id'] = $info['values'][$params['id']]['contact_id'];
 121     }
 122   }
 123   civicrm_api3_verify_mandatory($params, NULL, array('group_id', 'contact_id'));
 124   $action = CRM_Utils_Array::value('status', $params, 'Added');
 125   return _civicrm_api3_group_contact_common($params, $action);
 126 }
 127
 128 /**
 129  * Delete group contact record.
 130  *
 131  * @param array $params
 132  *
 133  * @return array
 134  *
 135  * @deprecated
 136  */
 137 function civicrm_api3_group_contact_delete($params) {
 138   $params['status'] = CRM_Utils_Array::value('status', $params, empty($params['skip_undelete']) ? 'Removed' : 'Deleted');
 139   // "Deleted" isn't a real option so skip the api wrapper to avoid pseudoconstant validation
 140   return civicrm_api3_group_contact_create($params);
 141 }
 142
 143 /**
 144  * Adjust metadata.
 145  *
 146  * @param array $params
 147  */
 148 function _civicrm_api3_group_contact_delete_spec(&$params) {
 149   // set as not required no either/or std yet
 150   $params['id']['api.required'] = 0;
 151 }
 152
 153 /**
 154  * Get pending group contacts.
 155  *
 156  * @param array $params
 157  *
 158  * @return array|int
 159  * @deprecated
 160  */
 161 function civicrm_api3_group_contact_pending($params) {
 162   $params['status'] = 'Pending';
 163   return civicrm_api('GroupContact', 'Create', $params);
 164 }
 165
 166 /**
 167  * Group contact helper function.
 168  *
 169  * @todo behaviour is highly non-standard - need to figure out how to make this 'behave'
 170  *   & at the very least return IDs & details of the groups created / changed
 171  *
 172  * @param array $params
 173  * @param string $op
 174  *
 175  * @return array
 176  */
 177 function _civicrm_api3_group_contact_common($params, $op = 'Added') {
 178
 179   $contactIDs = array();
 180   $groupIDs = array();
 181   foreach ($params as $n => $v) {
 182     if (substr($n, 0, 10) == 'contact_id') {
 183       $contactIDs[] = $v;
 184     }
 185     elseif (substr($n, 0, 8) == 'group_id') {
 186       $groupIDs[] = $v;
 187     }
 188   }
 189
 190   if (empty($contactIDs)) {
 191     return civicrm_api3_create_error('contact_id is a required field');
 192   }
 193
 194   if (empty($groupIDs)) {
 195     return civicrm_api3_create_error('group_id is a required field');
 196   }
 197
 198   $method = CRM_Utils_Array::value('method', $params, 'API');
 199   $status = CRM_Utils_Array::value('status', $params, $op);
 200   $tracking = CRM_Utils_Array::value('tracking', $params);
 201
 202   if ($op == 'Added' || $op == 'Pending') {
 203     $extraReturnValues = array(
 204       'total_count' => 0,
 205       'added' => 0,
 206       'not_added' => 0,
 207     );
 208     foreach ($groupIDs as $groupID) {
 209       list($tc, $a, $na) = CRM_Contact_BAO_GroupContact::addContactsToGroup($contactIDs,
 210         $groupID,
 211         $method,
 212         $status,
 213         $tracking
 214       );
 215       $extraReturnValues['total_count'] += $tc;
 216       $extraReturnValues['added'] += $a;
 217       $extraReturnValues['not_added'] += $na;
 218     }
 219   }
 220   else {
 221     $extraReturnValues = array(
 222       'total_count' => 0,
 223       'removed' => 0,
 224       'not_removed' => 0,
 225     );
 226     foreach ($groupIDs as $groupID) {
 227       list($tc, $r, $nr) = CRM_Contact_BAO_GroupContact::removeContactsFromGroup($contactIDs, $groupID, $method, $status, $tracking);
 228       $extraReturnValues['total_count'] += $tc;
 229       $extraReturnValues['removed'] += $r;
 230       $extraReturnValues['not_removed'] += $nr;
 231     }
 232   }
 233   $dao = NULL;// can't pass this by reference
 234   return civicrm_api3_create_success(1, $params, 'group_contact', 'create', $dao, $extraReturnValues);
 235 }
 236
 237 /**
 238  * Update group contact status.
 239  *
 240  * @deprecated - this should be part of create but need to know we aren't missing something
 241  *
 242  * @param array $params
 243  *
 244  * @return bool
 245  * @throws \API_Exception
 246  */
 247 function civicrm_api3_group_contact_update_status($params) {
 248
 249   civicrm_api3_verify_mandatory($params, NULL, array('contact_id', 'group_id'));
 250
 251   CRM_Contact_BAO_GroupContact::addContactsToGroup(
 252     array($params['contact_id']),
 253     $params['group_id'],
 254     CRM_Utils_Array::value('method', $params, 'API'),
 255     'Added',
 256     CRM_Utils_Array::value('tracking', $params)
 257   );
 258
 259   return TRUE;
 260 }
 261
 262 /**
 263  * Deprecated function notices.
 264  *
 265  * @deprecated api notice
 266  * @return array
 267  *   Array of deprecated actions
 268  */
 269 function _civicrm_api3_group_contact_deprecation() {
 270   return array(
 271     'delete' => 'GroupContact "delete" action is deprecated in favor of "create".',
 272     'pending' => 'GroupContact "pending" action is deprecated in favor of "create".',
 273     'update_status' => 'GroupContact "update_status" action is deprecated in favor of "create".',
 274   );
 275 }