api/v3/GroupContact.php

   1 <?php
   2 // $Id$
   3
   4 /*
   5  +--------------------------------------------------------------------+
   6  | CiviCRM version 4.4                                                |
   7  +--------------------------------------------------------------------+
   8  | Copyright CiviCRM LLC (c) 2004-2013                                |
   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-2013
  37  * @version $Id: GroupContact.php 30171 2010-10-14 09:11:27Z mover $
  38  *
  39  */
  40
  41
  42 /**
  43  * This API will give list of the groups for particular contact
  44  * Particualr status can be sent in params array
  45  * If no status mentioned in params, by default 'added' will be used
  46  * to fetch the records
  47  *
  48  * @param  array $params  name value pair of contact information
  49  * {@getfields GroupContact_get}
  50  *
  51  * @return  array  list of groups, given contact subsribed to
  52  */
  53 function civicrm_api3_group_contact_get($params) {
  54
  55   if (empty($params['contact_id'])) {
  56     if (empty($params['status'])) {
  57       //default to 'Added'
  58       $params['status'] = 'Added';
  59     }
  60     //ie. id passed in so we have to return something
  61     return _civicrm_api3_basic_get('CRM_Contact_BAO_GroupContact', $params);
  62   }
  63   $status = CRM_Utils_Array::value('status', $params, 'Added');
  64
  65   $values = &CRM_Contact_BAO_GroupContact::getContactGroup($params['contact_id'], $status, NULL, FALSE, TRUE);
  66   return civicrm_api3_create_success($values, $params);
  67 }
  68
  69 /**
  70  * Add contact(s) to group(s)
  71  *
  72  * @access public
  73  *
  74  * @param  array $params Input parameters
  75  *
  76  * Allowed @params array keys are:<br>
  77  * "contact_id" (required) : first contact to add<br>
  78  * "group_id" (required): first group to add contact(s) to<br>
  79  * "contact_id.1" etc. (optional) : another contact to add<br>
  80  * "group_id.1" etc. (optional) : additional group to add contact(s) to<br>
  81  * "status" (optional) : one of "Added", "Pending" or "Removed" (default is "Added")
  82  * {@example GroupContactCreate.php 0}
  83  *
  84  * @return array Information about operation results
  85  *
  86  * On success, the return array will be structured as follows:
  87  * <code>array(
  88  *   "is_error" => 0,
  89  *   "version"  => 3,
  90  *   "count"    => 3,
  91  *   "values" => array(
  92  *     "not_added"   => integer,
  93  *     "added"       => integer,
  94  *     "total_count" => integer
  95  *   )
  96  * )</code>
  97  *
  98  * On failure, the return array will be structured as follows:
  99  * <code>array(
 100  *   'is_error' => 1,
 101  *   'error_message' = string,
 102  *   'error_data' = mixed or undefined
 103  * )</code>
 104  * {@getfields GroupContact_create}
 105  */
 106 function civicrm_api3_group_contact_create($params) {
 107
 108   $action = CRM_Utils_Array::value('status', $params, 'Added');
 109   return _civicrm_api3_group_contact_common($params, $action);
 110 }
 111
 112 /**
 113  * Adjust Metadata for Create action
 114  *
 115  * The metadata is used for setting defaults, documentation & validation
 116  * @param array $params array or parameters determined by getfields
 117  */
 118 function _civicrm_api3_group_contact_create_spec(&$params) {
 119   $params['group_id']['api.required'] = 1;
 120   $params['contact_id']['api.required'] = 1;
 121 }
 122
 123 /**
 124  *
 125  * @param <type> $params
 126  *
 127  * @return <type>
 128  * @deprecated
 129  */
 130 function civicrm_api3_group_contact_delete($params) {
 131   $params['status'] = 'Removed';
 132   return civicrm_api('GroupContact', 'Create', $params);
 133 }
 134
 135 /**
 136  * modify metadata
 137  */
 138 function _civicrm_api3_group_contact_delete_spec(&$params) {
 139   // set as not required no either/or std yet
 140   $params['id']['api.required'] = 0;
 141 }
 142
 143 /**
 144  *
 145  * @param <type> $params
 146  *
 147  * @return <type>
 148  * @deprecated
 149  */
 150 function civicrm_api3_group_contact_pending($params) {
 151   $params['status'] = 'Pending';
 152   return civicrm_api('GroupContact', 'Create', $params);
 153 }
 154
 155 /**
 156  *
 157  * @param array $params
 158  * @param string $op
 159  *
 160  * @return Array
 161  * @todo behaviour is highly non-standard - need to figure out how to make this 'behave'
 162  * & at the very least return IDs & details of the groups created / changed
 163  */
 164 function _civicrm_api3_group_contact_common($params, $op = 'Added') {
 165
 166   $contactIDs = array();
 167   $groupIDs = array();
 168   foreach ($params as $n => $v) {
 169     if (substr($n, 0, 10) == 'contact_id') {
 170       $contactIDs[] = $v;
 171     }
 172     elseif (substr($n, 0, 8) == 'group_id') {
 173       $groupIDs[] = $v;
 174     }
 175   }
 176
 177   if (empty($contactIDs)) {
 178     return civicrm_api3_create_error('contact_id is a required field');
 179   }
 180
 181   if (empty($groupIDs)) {
 182     return civicrm_api3_create_error('group_id is a required field');
 183   }
 184
 185   $method = CRM_Utils_Array::value('method', $params, 'API');
 186   $status = CRM_Utils_Array::value('status', $params, $op);
 187   $tracking = CRM_Utils_Array::value('tracking', $params);
 188
 189   if ($op == 'Added' || $op == 'Pending') {
 190     $extraReturnValues= array(
 191       'total_count' => 0,
 192       'added' => 0,
 193       'not_added' => 0
 194     );
 195     foreach ($groupIDs as $groupID) {
 196       list($tc, $a, $na) = CRM_Contact_BAO_GroupContact::addContactsToGroup($contactIDs,
 197         $groupID,
 198         $method,
 199         $status,
 200         $tracking
 201       );
 202       $extraReturnValues['total_count'] += $tc;
 203       $extraReturnValues['added'] += $a;
 204       $extraReturnValues['not_added'] += $na;
 205     }
 206   }
 207   else {
 208     $extraReturnValues= array(
 209       'total_count' => 0,
 210       'removed' => 0,
 211       'not_removed' => 0
 212     );
 213     foreach ($groupIDs as $groupID) {
 214       list($tc, $r, $nr) = CRM_Contact_BAO_GroupContact::removeContactsFromGroup($contactIDs, $groupID, $method, $status, $tracking);
 215       $extraReturnValues['total_count'] += $tc;
 216       $extraReturnValues['removed'] += $r;
 217       $extraReturnValues['not_removed'] += $nr;
 218     }
 219   }
 220   $dao = null;// can't pass this by reference
 221   return civicrm_api3_create_success(1,$params,'group_contact','create',$dao,$extraReturnValues);
 222 }
 223
 224 /**
 225  * @deprecated - this should be part of create but need to know we aren't missing something
 226  */
 227 function civicrm_api3_group_contact_update_status($params) {
 228
 229   civicrm_api3_verify_mandatory($params, NULL, array('contact_id', 'group_id'));
 230
 231   $method = CRM_Utils_Array::value('method', $params, 'API');
 232   $tracking = CRM_Utils_Array::value('tracking', $params);
 233
 234   CRM_Contact_BAO_GroupContact::updateGroupMembershipStatus($params['contact_id'], $params['group_id'], $method, $tracking);
 235
 236   return TRUE;
 237 }
 238