Merge pull request #6397 from colemanw/CRM-14078
[civicrm-core.git] / api / v3 / GroupContact.php
1 <?php
2 /*
3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.6 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2015 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
9 | |
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. |
13 | |
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. |
18 | |
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 +--------------------------------------------------------------------+
26 */
27
28 /**
29 * This api exposes CiviCRM GroupContact records.
30 *
31 * This api is for adding/removing contacts from a group,
32 * or fetching a list of groups for a contact.
33 *
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.
37 *
38 * To create/delete groups, use the group api instead.
39 *
40 * @package CiviCRM_APIv3
41 */
42
43 /**
44 * Fetch a list of groups for a contact, or contacts for a group.
45 *
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.
49 *
50 * If no status mentioned in params, by default 'added' will be used
51 * to fetch the records
52 *
53 * @param array $params
54 * Name value pair of contact information.
55 *
56 * @return array
57 * list of groups, given contact subsribed to
58 */
59 function civicrm_api3_group_contact_get($params) {
60
61 if (empty($params['contact_id'])) {
62 if (empty($params['status'])) {
63 //default to 'Added'
64 $params['status'] = 'Added';
65 }
66 //ie. id passed in so we have to return something
67 return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
68 }
69 $status = CRM_Utils_Array::value('status', $params, 'Added');
70
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');
74 }
75
76 /**
77 * Add contact(s) to group(s).
78 *
79 * This api has a legacy/nonstandard signature.
80 * On success, the return array will be structured as follows:
81 * @code
82 * array(
83 * "is_error" => 0,
84 * "version" => 3,
85 * "count" => 3,
86 * "values" => array(
87 * "not_added" => integer,
88 * "added" => integer,
89 * "total_count" => integer
90 * )
91 * )
92 * @endcode
93 *
94 * On failure, the return array will be structured as follows:
95 * @code
96 * array(
97 * 'is_error' => 1,
98 * 'error_message' = string,
99 * 'error_data' = mixed or undefined
100 * )
101 * @endcode
102 *
103 * @param array $params
104 * Input parameters.
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")
110 *
111 * @return array
112 * Information about operation results
113 */
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'];
122 }
123 }
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);
127 }
128
129 /**
130 * Delete group contact record.
131 *
132 * @param array $params
133 *
134 * @return array
135 *
136 * @deprecated
137 */
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);
142 }
143
144 /**
145 * Adjust metadata.
146 *
147 * @param array $params
148 */
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;
152 }
153
154 /**
155 * Get pending group contacts.
156 *
157 * @param array $params
158 *
159 * @return array|int
160 * @deprecated
161 */
162 function civicrm_api3_group_contact_pending($params) {
163 $params['status'] = 'Pending';
164 return civicrm_api('GroupContact', 'Create', $params);
165 }
166
167 /**
168 * Group contact helper function.
169 *
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
172 *
173 * @param array $params
174 * @param string $op
175 *
176 * @return array
177 */
178 function _civicrm_api3_group_contact_common($params, $op = 'Added') {
179
180 $contactIDs = array();
181 $groupIDs = array();
182 foreach ($params as $n => $v) {
183 if (substr($n, 0, 10) == 'contact_id') {
184 $contactIDs[] = $v;
185 }
186 elseif (substr($n, 0, 8) == 'group_id') {
187 $groupIDs[] = $v;
188 }
189 }
190
191 if (empty($contactIDs)) {
192 return civicrm_api3_create_error('contact_id is a required field');
193 }
194
195 if (empty($groupIDs)) {
196 return civicrm_api3_create_error('group_id is a required field');
197 }
198
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);
202
203 if ($op == 'Added' || $op == 'Pending') {
204 $extraReturnValues = array(
205 'total_count' => 0,
206 'added' => 0,
207 'not_added' => 0,
208 );
209 foreach ($groupIDs as $groupID) {
210 list($tc, $a, $na) = CRM_Contact_BAO_GroupContact::addContactsToGroup($contactIDs,
211 $groupID,
212 $method,
213 $status,
214 $tracking
215 );
216 $extraReturnValues['total_count'] += $tc;
217 $extraReturnValues['added'] += $a;
218 $extraReturnValues['not_added'] += $na;
219 }
220 }
221 else {
222 $extraReturnValues = array(
223 'total_count' => 0,
224 'removed' => 0,
225 'not_removed' => 0,
226 );
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;
232 }
233 }
234 // can't pass this by reference
235 $dao = NULL;
236 return civicrm_api3_create_success(1, $params, 'GroupContact', 'create', $dao, $extraReturnValues);
237 }
238
239 /**
240 * Update group contact status.
241 *
242 * @deprecated - this should be part of create but need to know we aren't missing something
243 *
244 * @param array $params
245 *
246 * @return bool
247 * @throws \API_Exception
248 */
249 function civicrm_api3_group_contact_update_status($params) {
250
251 civicrm_api3_verify_mandatory($params, NULL, array('contact_id', 'group_id'));
252
253 CRM_Contact_BAO_GroupContact::addContactsToGroup(
254 array($params['contact_id']),
255 $params['group_id'],
256 CRM_Utils_Array::value('method', $params, 'API'),
257 'Added',
258 CRM_Utils_Array::value('tracking', $params)
259 );
260
261 return TRUE;
262 }
263
264 /**
265 * Deprecated function notices.
266 *
267 * @deprecated api notice
268 * @return array
269 * Array of deprecated actions
270 */
271 function _civicrm_api3_group_contact_deprecation() {
272 return array(
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".',
276 );
277 }