api/v3/GroupContact.php

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