Merge pull request #6251 from LevityNL/master

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

diff --git a/api/v3/GroupContact.php b/api/v3/GroupContact.php
index 2fcd3400af51e97e824d5503b3af1be3a45c0bf3..e7e76659d44ac5ea7e4c908a915e2e80d4b024af 100644 (file)
--- a/api/v3/GroupContact.php
+++ b/api/v3/GroupContact.php
@@ -1,11 +1,9 @@
 <?php
-// $Id$
-
 /*
  +--------------------------------------------------------------------+
  | CiviCRM version 4.6                                                |
  +--------------------------------------------------------------------+
- | Copyright CiviCRM LLC (c) 2004-2014                                |
+ | Copyright CiviCRM LLC (c) 2004-2015                                |
  +--------------------------------------------------------------------+
  | This file is a part of CiviCRM.                                    |
  |                                                                    |
@@ -28,20 +26,26 @@
  */
 
 /**
- * File for the CiviCRM APIv3 group contact functions
+ * This api exposes CiviCRM GroupContact records.
  *
- * @package CiviCRM_APIv3
- * @subpackage API_Group
+ * 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
+ * passing a contact_id and group_id.
  *
- * @copyright CiviCRM LLC (c) 2004-2014
- * @version $Id: GroupContact.php 30171 2010-10-14 09:11:27Z mover $
+ * To create/delete groups, use the group api instead.
+ *
+ * @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
@@ -66,27 +70,16 @@ function civicrm_api3_group_contact_get($params) {
 
   $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);
+  return civicrm_api3_create_success($values, $params, 'GroupContact');
 }
 
 /**
  * Add contact(s) to group(s).
  *
- * @param array $params
- *   Input parameters.
- *
- * Allowed @params array keys are:<br>
- * "contact_id" (required) : first contact to add<br>
- * "group_id" (required): first group to add contact(s) to<br>
- * "contact_id.1" etc. (optional) : another contact to add<br>
- * "group_id.1" etc. (optional) : additional group to add contact(s) to<br>
- * "status" (optional) : one of "Added", "Pending" or "Removed" (default is "Added")
- *
- * @return array
- *   Information about operation results
- *
- *   On success, the return array will be structured as follows:
- *   <code>array(
+ * This api has a legacy/nonstandard signature.
+ * On success, the return array will be structured as follows:
+ * @code
+ * array(
  *   "is_error" => 0,
  *   "version"  => 3,
  *   "count"    => 3,
@@ -95,15 +88,28 @@ function civicrm_api3_group_contact_get($params) {
  *     "added"       => integer,
  *     "total_count" => integer
  *   )
- *   )</code>
+ * )
+ * @endcode
  *
- *   On failure, the return array will be structured as follows:
- *   <code>array(
+ * On failure, the return array will be structured as follows:
+ * @code
+ * array(
  *   'is_error' => 1,
  *   'error_message' = string,
  *   'error_data' = mixed or undefined
- *   )</code>
- *   {@getfields GroupContact_create}
+ * )
+ * @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")
+ *
+ * @return array
+ *   Information about operation results
  */
 function civicrm_api3_group_contact_create($params) {
   // Nonstandard bao - doesn't accept ID as a param, so convert id to group_id + contact_id
@@ -161,12 +167,13 @@ function civicrm_api3_group_contact_pending($params) {
 /**
  * Group contact helper function.
  *
+ * @todo behaviour is highly non-standard - need to figure out how to make this 'behave'
+ *   & at the very least return IDs & details of the groups created / changed
+ *
  * @param array $params
  * @param string $op
  *
  * @return array
- * @todo behaviour is highly non-standard - need to figure out how to make this 'behave'
- * & at the very least return IDs & details of the groups created / changed
  */
 function _civicrm_api3_group_contact_common($params, $op = 'Added') {
 
@@ -224,8 +231,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);
 }
 
 /**