Checkstyle fix - one pesky whitespace

[civicrm-core.git] / api / v3 / GroupContact.php

diff --git a/api/v3/GroupContact.php b/api/v3/GroupContact.php
index 601efd2bc467b7e7ad253b4a0af96eee4401d2e8..824afc828447627a74ce4f36162311da5a85c71f 100644 (file)
--- a/api/v3/GroupContact.php
+++ b/api/v3/GroupContact.php
@@ -3,7 +3,7 @@
  +--------------------------------------------------------------------+
  | CiviCRM version 4.6                                                |
  +--------------------------------------------------------------------+
- | Copyright CiviCRM LLC (c) 2004-2014                                |
+ | Copyright CiviCRM LLC (c) 2004-2015                                |
  +--------------------------------------------------------------------+
  | This file is a part of CiviCRM.                                    |
  |                                                                    |
@@ -26,13 +26,13 @@
  */
 
 /**
- * This api exposes CiviCRM group contacts.
+ * This api exposes CiviCRM GroupContact records.
  *
  * This api is for adding/removing contacts from a group,
  * or fetching a list of groups for a contact.
  *
  * Important note: This api does not fetch smart groups for a contact.
- * To fetch all contacts in a smart group, use the contact api
+ * To fetch all contacts in a smart group, use the Contact api
  * passing a contact_id and group_id.
  *
  * To create/delete groups, use the group api instead.
@@ -40,11 +40,12 @@
  * @package CiviCRM_APIv3
  */
 
-
 /**
- * This API will give list of the groups for particular contact.
+ * Fetch a list of groups for a contact, or contacts for a group.
  *
- * Particular status can be sent in params array.
+ * @Note: this only applies to static groups, not smart groups.
+ * To fetch all contacts in a smart group, use the Contact api
+ * passing a contact_id and group_id.
  *
  * If no status mentioned in params, by default 'added' will be used
  * to fetch the records
@@ -68,8 +69,18 @@ function civicrm_api3_group_contact_get($params) {
   $status = CRM_Utils_Array::value('status', $params, 'Added');
 
   $groupId = CRM_Utils_Array::value('group_id', $params);
-  $values = &CRM_Contact_BAO_GroupContact::getContactGroup($params['contact_id'], $status, NULL, FALSE, TRUE, FALSE, TRUE, $groupId);
-  return civicrm_api3_create_success($values, $params);
+  $values = CRM_Contact_BAO_GroupContact::getContactGroup($params['contact_id'], $status, NULL, FALSE, TRUE, FALSE, TRUE, $groupId);
+  return civicrm_api3_create_success($values, $params, 'GroupContact');
+}
+
+/**
+ * Adjust metadata for Create action.
+ *
+ * @param array $params
+ */
+function _civicrm_api3_group_contact_create_spec(&$params) {
+  $params['contact_id']['api.required'] = 1;
+  $params['group_id']['api.required'] = 1;
 }
 
 /**
@@ -100,12 +111,13 @@ function civicrm_api3_group_contact_get($params) {
  * @endcode
  *
  * @param array $params
- *   Input parameters.
- *   - "contact_id" (required) : first contact to add
- *   - "group_id" (required): first group to add contact(s) to
- *   - "contact_id.1" etc. (optional) : another contact to add
- *   - "group_id.1" etc. (optional) : additional group to add contact(s) to
- *   - "status" (optional) : one of "Added", "Pending" or "Removed" (default is "Added")
+ *   Input parameters:
+ *   - "contact_id" (required): First contact to add, or array of Contact IDs
+ *   - "group_id" (required): First group to add contact(s) to, or array of Group IDs
+ *   - "status" (optional): "Added" (default), "Pending" or "Removed"
+ *   Legacy input parameters (will be deprecated):
+ *   - "contact_id.1" etc. (optional): Additional contact_id to add to group(s)
+ *   - "group_id.1" etc. (optional): Additional groups to add contact(s) to
  *
  * @return array
  *   Information about operation results
@@ -120,7 +132,6 @@ function civicrm_api3_group_contact_create($params) {
       $params['contact_id'] = $info['values'][$params['id']]['contact_id'];
     }
   }
-  civicrm_api3_verify_mandatory($params, NULL, array('group_id', 'contact_id'));
   $action = CRM_Utils_Array::value('status', $params, 'Added');
   return _civicrm_api3_group_contact_common($params, $action);
 }
@@ -178,23 +189,32 @@ function _civicrm_api3_group_contact_common($params, $op = 'Added') {
 
   $contactIDs = array();
   $groupIDs = array();
+
+  // CRM-16959: Handle multiple Contact IDs and Group IDs in legacy format
+  // (contact_id.1, contact_id.2) or as an array
   foreach ($params as $n => $v) {
     if (substr($n, 0, 10) == 'contact_id') {
-      $contactIDs[] = $v;
+      if (is_array($v)) {
+        foreach ($v as $arr_v) {
+          $contactIDs[] = $arr_v;
+        }
+      }
+      else {
+        $contactIDs[] = $v;
+      }
     }
     elseif (substr($n, 0, 8) == 'group_id') {
-      $groupIDs[] = $v;
+      if (is_array($v)) {
+        foreach ($v as $arr_v) {
+          $groupIDs[] = $arr_v;
+        }
+      }
+      else {
+        $groupIDs[] = $v;
+      }
     }
   }
 
-  if (empty($contactIDs)) {
-    return civicrm_api3_create_error('contact_id is a required field');
-  }
-
-  if (empty($groupIDs)) {
-    return civicrm_api3_create_error('group_id is a required field');
-  }
-
   $method = CRM_Utils_Array::value('method', $params, 'API');
   $status = CRM_Utils_Array::value('status', $params, $op);
   $tracking = CRM_Utils_Array::value('tracking', $params);
@@ -230,8 +250,9 @@ function _civicrm_api3_group_contact_common($params, $op = 'Added') {
       $extraReturnValues['not_removed'] += $nr;
     }
   }
-  $dao = NULL;// can't pass this by reference
-  return civicrm_api3_create_success(1, $params, 'group_contact', 'create', $dao, $extraReturnValues);
+  // can't pass this by reference
+  $dao = NULL;
+  return civicrm_api3_create_success(1, $params, 'GroupContact', 'create', $dao, $extraReturnValues);
 }
 
 /**