5 +--------------------------------------------------------------------+
6 | CiviCRM version 4.6 |
7 +--------------------------------------------------------------------+
8 | Copyright CiviCRM LLC (c) 2004-2014 |
9 +--------------------------------------------------------------------+
10 | This file is a part of CiviCRM. |
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. |
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. |
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 +--------------------------------------------------------------------+
31 * File for the CiviCRM APIv3 group contact functions
33 * @package CiviCRM_APIv3
34 * @subpackage API_Group
36 * @copyright CiviCRM LLC (c) 2004-2014
37 * @version $Id: GroupContact.php 30171 2010-10-14 09:11:27Z mover $
43 * This API will give list of the groups for particular contact
44 * Particular 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
48 * @param array $params
49 * Name value pair of contact information.
50 * {@getfields GroupContact_get}
52 * @return array list of groups, given contact subsribed to
54 function civicrm_api3_group_contact_get($params) {
56 if (empty($params['contact_id'])) {
57 if (empty($params['status'])) {
59 $params['status'] = 'Added';
61 //ie. id passed in so we have to return something
62 return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__
), $params);
64 $status = CRM_Utils_Array
::value('status', $params, 'Added');
66 $groupId = CRM_Utils_Array
::value('group_id', $params);
67 $values = &CRM_Contact_BAO_GroupContact
::getContactGroup($params['contact_id'], $status, NULL, FALSE, TRUE, FALSE, TRUE, $groupId);
68 return civicrm_api3_create_success($values, $params);
72 * Add contact(s) to group(s)
76 * @param array $params
79 * Allowed @params array keys are:<br>
80 * "contact_id" (required) : first contact to add<br>
81 * "group_id" (required): first group to add contact(s) to<br>
82 * "contact_id.1" etc. (optional) : another contact to add<br>
83 * "group_id.1" etc. (optional) : additional group to add contact(s) to<br>
84 * "status" (optional) : one of "Added", "Pending" or "Removed" (default is "Added")
85 * {@example GroupContactCreate.php 0}
87 * @return array Information about operation results
89 * On success, the return array will be structured as follows:
95 * "not_added" => integer,
97 * "total_count" => integer
101 * On failure, the return array will be structured as follows:
104 * 'error_message' = string,
105 * 'error_data' = mixed or undefined
107 * {@getfields GroupContact_create}
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 = array('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 civicrm_api3_verify_mandatory($params, NULL, array('group_id', 'contact_id'));
120 $action = CRM_Utils_Array
::value('status', $params, 'Added');
121 return _civicrm_api3_group_contact_common($params, $action);
126 * @param <type> $params
128 * @return array <type>@deprecated
130 function civicrm_api3_group_contact_delete($params) {
131 $params['status'] = CRM_Utils_Array
::value('status', $params, empty($params['skip_undelete']) ?
'Removed' : 'Deleted');
132 // "Deleted" isn't a real option so skip the api wrapper to avoid pseudoconstant validation
133 return civicrm_api3_group_contact_create($params);
139 function _civicrm_api3_group_contact_delete_spec(&$params) {
140 // set as not required no either/or std yet
141 $params['id']['api.required'] = 0;
146 * @param <type> $params
148 * @return array|int <type>@deprecated
150 function civicrm_api3_group_contact_pending($params) {
151 $params['status'] = 'Pending';
152 return civicrm_api('GroupContact', 'Create', $params);
157 * @param array $params
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
164 function _civicrm_api3_group_contact_common($params, $op = 'Added') {
166 $contactIDs = array();
168 foreach ($params as $n => $v) {
169 if (substr($n, 0, 10) == 'contact_id') {
172 elseif (substr($n, 0, 8) == 'group_id') {
177 if (empty($contactIDs)) {
178 return civicrm_api3_create_error('contact_id is a required field');
181 if (empty($groupIDs)) {
182 return civicrm_api3_create_error('group_id is a required field');
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);
189 if ($op == 'Added' ||
$op == 'Pending') {
190 $extraReturnValues= array(
195 foreach ($groupIDs as $groupID) {
196 list($tc, $a, $na) = CRM_Contact_BAO_GroupContact
::addContactsToGroup($contactIDs,
202 $extraReturnValues['total_count'] +
= $tc;
203 $extraReturnValues['added'] +
= $a;
204 $extraReturnValues['not_added'] +
= $na;
208 $extraReturnValues= array(
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;
220 $dao = null;// can't pass this by reference
221 return civicrm_api3_create_success(1,$params,'group_contact','create',$dao,$extraReturnValues);
225 * @deprecated - this should be part of create but need to know we aren't missing something
227 function civicrm_api3_group_contact_update_status($params) {
229 civicrm_api3_verify_mandatory($params, NULL, array('contact_id', 'group_id'));
231 CRM_Contact_BAO_GroupContact
::addContactsToGroup(
232 array($params['contact_id']),
234 CRM_Utils_Array
::value('method', $params, 'API'),
236 CRM_Utils_Array
::value('tracking', $params)
243 * @deprecated api notice
244 * @return array of deprecated actions
246 function _civicrm_api3_group_contact_deprecation() {
248 'delete' => 'GroupContact "delete" action is deprecated in favor of "create".',
249 'pending' => 'GroupContact "pending" action is deprecated in favor of "create".',
250 'update_status' => 'GroupContact "update_status" action is deprecated in favor of "create".',