3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.7 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2017 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
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. |
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. |
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 +--------------------------------------------------------------------+
29 * This api exposes CiviCRM GroupContact records.
31 * This api is for adding/removing contacts from a group,
32 * or fetching a list of groups for a contact.
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.
38 * To create/delete groups, use the group api instead.
40 * @package CiviCRM_APIv3
44 * Fetch a list of groups for a contact, or contacts for a group.
46 * @Note: this only applies to static groups, not smart groups.
47 * To fetch all contacts in a smart group, use the Contact api
48 * passing a contact_id and group_id.
50 * If no status mentioned in params, by default 'added' will be used
51 * to fetch the records
53 * @param array $params
54 * Name value pair of contact information.
57 * list of groups, given contact subsribed to
59 function civicrm_api3_group_contact_get($params) {
61 if (empty($params['contact_id'])) {
62 if (empty($params['status'])) {
64 $params['status'] = 'Added';
66 //ie. id passed in so we have to return something
67 return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__
), $params);
69 $status = CRM_Utils_Array
::value('status', $params, 'Added');
71 $groupId = CRM_Utils_Array
::value('group_id', $params);
72 $values = CRM_Contact_BAO_GroupContact
::getContactGroup($params['contact_id'], $status, NULL, FALSE, TRUE, FALSE, TRUE, $groupId);
73 return civicrm_api3_create_success($values, $params, 'GroupContact');
77 * Adjust metadata for Create action.
79 * @param array $params
81 function _civicrm_api3_group_contact_create_spec(&$params) {
82 $params['contact_id']['api.required'] = 1;
83 $params['group_id']['api.required'] = 1;
87 * Add contact(s) to group(s).
89 * This api has a legacy/nonstandard signature.
90 * On success, the return array will be structured as follows:
97 * "not_added" => integer,
99 * "total_count" => integer
104 * On failure, the return array will be structured as follows:
108 * 'error_message' = string,
109 * 'error_data' = mixed or undefined
113 * @param array $params
115 * - "contact_id" (required): First contact to add, or array of Contact IDs
116 * - "group_id" (required): First group to add contact(s) to, or array of Group IDs
117 * - "status" (optional): "Added" (default), "Pending" or "Removed"
118 * Legacy input parameters (will be deprecated):
119 * - "contact_id.1" etc. (optional): Additional contact_id to add to group(s)
120 * - "group_id.1" etc. (optional): Additional groups to add contact(s) to
123 * Information about operation results
125 function civicrm_api3_group_contact_create($params) {
126 // Nonstandard bao - doesn't accept ID as a param, so convert id to group_id + contact_id
127 if (!empty($params['id'])) {
128 $getParams = array('id' => $params['id']);
129 $info = _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__
), $getParams);
130 if (!empty($info['values'][$params['id']])) {
131 $params['group_id'] = $info['values'][$params['id']]['group_id'];
132 $params['contact_id'] = $info['values'][$params['id']]['contact_id'];
135 $action = CRM_Utils_Array
::value('status', $params, 'Added');
136 return _civicrm_api3_group_contact_common($params, $action);
140 * Delete group contact record.
142 * @param array $params
144 * @throws API_Exception
145 * @throws CiviCRM_API3_Exception
148 function civicrm_api3_group_contact_delete($params) {
149 $checkParams = $params;
150 if (!empty($checkParams['status']) && in_array($checkParams['status'], array('Removed', 'Deleted'))) {
151 $checkParams['status'] = array('IN' => array('Added', 'Pending'));
153 elseif (!empty($checkParams['status']) && $checkParams['status'] == 'Added') {
154 $checkParams['status'] = array('IN' => array('Pending', 'Removed'));
156 elseif (!empty($checkParams['status'])) {
157 unset($checkParams['status']);
159 $groupContact = civicrm_api3('GroupContact', 'get', $checkParams);
160 if ($groupContact['count'] == 0 && !empty($params['skip_undelete'])) {
161 $checkParams['status'] = array('IN' => array('Removed', 'Pending'));
163 $groupContact2 = civicrm_api3('GroupContact', 'get', $checkParams);
164 if ($groupContact['count'] == 0 && $groupContact2['count'] == 0) {
165 throw new API_Exception('Cannot Delete GroupContact');
167 $params['status'] = CRM_Utils_Array
::value('status', $params, empty($params['skip_undelete']) ?
'Removed' : 'Deleted');
168 // "Deleted" isn't a real option so skip the api wrapper to avoid pseudoconstant validation
169 return civicrm_api3_group_contact_create($params);
175 * @param array $params
177 function _civicrm_api3_group_contact_delete_spec(&$params) {
178 // set as not required no either/or std yet
179 $params['id']['api.required'] = 0;
183 * Get pending group contacts.
185 * @param array $params
190 function civicrm_api3_group_contact_pending($params) {
191 $params['status'] = 'Pending';
192 return civicrm_api('GroupContact', 'Create', $params);
196 * Group contact helper function.
198 * @todo behaviour is highly non-standard - need to figure out how to make this 'behave'
199 * & at the very least return IDs & details of the groups created / changed
201 * @param array $params
206 function _civicrm_api3_group_contact_common($params, $op = 'Added') {
208 $contactIDs = array();
211 // CRM-16959: Handle multiple Contact IDs and Group IDs in legacy format
212 // (contact_id.1, contact_id.2) or as an array
213 foreach ($params as $n => $v) {
214 if (substr($n, 0, 10) == 'contact_id') {
216 foreach ($v as $arr_v) {
217 $contactIDs[] = $arr_v;
224 elseif (substr($n, 0, 8) == 'group_id') {
226 foreach ($v as $arr_v) {
227 $groupIDs[] = $arr_v;
236 $method = CRM_Utils_Array
::value('method', $params, 'API');
237 $status = CRM_Utils_Array
::value('status', $params, $op);
238 $tracking = CRM_Utils_Array
::value('tracking', $params);
240 if ($op == 'Added' ||
$op == 'Pending') {
241 $extraReturnValues = array(
246 foreach ($groupIDs as $groupID) {
247 list($tc, $a, $na) = CRM_Contact_BAO_GroupContact
::addContactsToGroup($contactIDs,
253 $extraReturnValues['total_count'] +
= $tc;
254 $extraReturnValues['added'] +
= $a;
255 $extraReturnValues['not_added'] +
= $na;
259 $extraReturnValues = array(
264 foreach ($groupIDs as $groupID) {
265 list($tc, $r, $nr) = CRM_Contact_BAO_GroupContact
::removeContactsFromGroup($contactIDs, $groupID, $method, $status, $tracking);
266 $extraReturnValues['total_count'] +
= $tc;
267 $extraReturnValues['removed'] +
= $r;
268 $extraReturnValues['not_removed'] +
= $nr;
271 // can't pass this by reference
273 return civicrm_api3_create_success(1, $params, 'GroupContact', 'create', $dao, $extraReturnValues);
277 * Update group contact status.
279 * @deprecated - this should be part of create but need to know we aren't missing something
281 * @param array $params
284 * @throws \API_Exception
286 function civicrm_api3_group_contact_update_status($params) {
288 civicrm_api3_verify_mandatory($params, NULL, array('contact_id', 'group_id'));
290 CRM_Contact_BAO_GroupContact
::addContactsToGroup(
291 array($params['contact_id']),
293 CRM_Utils_Array
::value('method', $params, 'API'),
295 CRM_Utils_Array
::value('tracking', $params)
302 * Deprecated function notices.
304 * @deprecated api notice
306 * Array of deprecated actions
308 function _civicrm_api3_group_contact_deprecation() {
310 'delete' => 'GroupContact "delete" action is deprecated in favor of "create".',
311 'pending' => 'GroupContact "pending" action is deprecated in favor of "create".',
312 'update_status' => 'GroupContact "update_status" action is deprecated in favor of "create".',