3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.6 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2015 |
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 * Add contact(s) to group(s).
79 * This api has a legacy/nonstandard signature.
80 * On success, the return array will be structured as follows:
87 * "not_added" => integer,
89 * "total_count" => integer
94 * On failure, the return array will be structured as follows:
98 * 'error_message' = string,
99 * 'error_data' = mixed or undefined
103 * @param array $params
105 * - "contact_id" (required) : first contact to add
106 * - "group_id" (required): first group to add contact(s) to
107 * - "contact_id.1" etc. (optional) : another contact to add
108 * - "group_id.1" etc. (optional) : additional group to add contact(s) to
109 * - "status" (optional) : one of "Added", "Pending" or "Removed" (default is "Added")
112 * Information about operation results
114 function civicrm_api3_group_contact_create($params) {
115 // Nonstandard bao - doesn't accept ID as a param, so convert id to group_id + contact_id
116 if (!empty($params['id'])) {
117 $getParams = array('id' => $params['id']);
118 $info = _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__
), $getParams);
119 if (!empty($info['values'][$params['id']])) {
120 $params['group_id'] = $info['values'][$params['id']]['group_id'];
121 $params['contact_id'] = $info['values'][$params['id']]['contact_id'];
124 civicrm_api3_verify_mandatory($params, NULL, array('group_id', 'contact_id'));
125 $action = CRM_Utils_Array
::value('status', $params, 'Added');
126 return _civicrm_api3_group_contact_common($params, $action);
130 * Delete group contact record.
132 * @param array $params
138 function civicrm_api3_group_contact_delete($params) {
139 $params['status'] = CRM_Utils_Array
::value('status', $params, empty($params['skip_undelete']) ?
'Removed' : 'Deleted');
140 // "Deleted" isn't a real option so skip the api wrapper to avoid pseudoconstant validation
141 return civicrm_api3_group_contact_create($params);
147 * @param array $params
149 function _civicrm_api3_group_contact_delete_spec(&$params) {
150 // set as not required no either/or std yet
151 $params['id']['api.required'] = 0;
155 * Get pending group contacts.
157 * @param array $params
162 function civicrm_api3_group_contact_pending($params) {
163 $params['status'] = 'Pending';
164 return civicrm_api('GroupContact', 'Create', $params);
168 * Group contact helper function.
170 * @todo behaviour is highly non-standard - need to figure out how to make this 'behave'
171 * & at the very least return IDs & details of the groups created / changed
173 * @param array $params
178 function _civicrm_api3_group_contact_common($params, $op = 'Added') {
180 $contactIDs = array();
182 foreach ($params as $n => $v) {
183 if (substr($n, 0, 10) == 'contact_id') {
186 elseif (substr($n, 0, 8) == 'group_id') {
191 if (empty($contactIDs)) {
192 return civicrm_api3_create_error('contact_id is a required field');
195 if (empty($groupIDs)) {
196 return civicrm_api3_create_error('group_id is a required field');
199 $method = CRM_Utils_Array
::value('method', $params, 'API');
200 $status = CRM_Utils_Array
::value('status', $params, $op);
201 $tracking = CRM_Utils_Array
::value('tracking', $params);
203 if ($op == 'Added' ||
$op == 'Pending') {
204 $extraReturnValues = array(
209 foreach ($groupIDs as $groupID) {
210 list($tc, $a, $na) = CRM_Contact_BAO_GroupContact
::addContactsToGroup($contactIDs,
216 $extraReturnValues['total_count'] +
= $tc;
217 $extraReturnValues['added'] +
= $a;
218 $extraReturnValues['not_added'] +
= $na;
222 $extraReturnValues = array(
227 foreach ($groupIDs as $groupID) {
228 list($tc, $r, $nr) = CRM_Contact_BAO_GroupContact
::removeContactsFromGroup($contactIDs, $groupID, $method, $status, $tracking);
229 $extraReturnValues['total_count'] +
= $tc;
230 $extraReturnValues['removed'] +
= $r;
231 $extraReturnValues['not_removed'] +
= $nr;
234 // can't pass this by reference
236 return civicrm_api3_create_success(1, $params, 'GroupContact', 'create', $dao, $extraReturnValues);
240 * Update group contact status.
242 * @deprecated - this should be part of create but need to know we aren't missing something
244 * @param array $params
247 * @throws \API_Exception
249 function civicrm_api3_group_contact_update_status($params) {
251 civicrm_api3_verify_mandatory($params, NULL, array('contact_id', 'group_id'));
253 CRM_Contact_BAO_GroupContact
::addContactsToGroup(
254 array($params['contact_id']),
256 CRM_Utils_Array
::value('method', $params, 'API'),
258 CRM_Utils_Array
::value('tracking', $params)
265 * Deprecated function notices.
267 * @deprecated api notice
269 * Array of deprecated actions
271 function _civicrm_api3_group_contact_deprecation() {
273 'delete' => 'GroupContact "delete" action is deprecated in favor of "create".',
274 'pending' => 'GroupContact "pending" action is deprecated in favor of "create".',
275 'update_status' => 'GroupContact "update_status" action is deprecated in favor of "create".',