<?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. |
| |
*/
/**
- * 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
- * Particular status can be sent in params array
+ * Fetch a list of groups for a contact, or contacts for a group.
+ *
+ * @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
*
* @param array $params
* Name value pair of contact information.
- * {@getfields GroupContact_get}
*
* @return array
- * list of groups, given contact subsribed to
+ * list of groups, given contact subsribed to
*/
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)
- *
- * @access public
- *
- * @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")
- * {@example GroupContactCreate.php 0}
- *
- * @return array
- * Information about operation results
+ * Add contact(s) to group(s).
*
+ * This api has a legacy/nonstandard signature.
* On success, the return array will be structured as follows:
- * <code>array(
+ * @code
+ * array(
* "is_error" => 0,
* "version" => 3,
* "count" => 3,
* "added" => integer,
* "total_count" => integer
* )
- * )</code>
+ * )
+ * @endcode
*
* On failure, the return array will be structured as follows:
- * <code>array(
+ * @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
}
/**
+ * Delete group contact record.
*
- * @param <type> $params
+ * @param array $params
*
* @return array
- * <type>
+ *
* @deprecated
*/
function civicrm_api3_group_contact_delete($params) {
}
/**
- * modify metadata
+ * Adjust metadata.
+ *
+ * @param array $params
*/
function _civicrm_api3_group_contact_delete_spec(&$params) {
// set as not required no either/or std yet
}
/**
+ * Get pending group contacts.
*
- * @param <type> $params
+ * @param array $params
*
- * @return array|int <type>
+ * @return array|int
* @deprecated
*/
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
+ * @return array
*/
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);
}
/**
+ * Update group contact status.
+ *
* @deprecated - this should be part of create but need to know we aren't missing something
+ *
+ * @param array $params
+ *
+ * @return bool
+ * @throws \API_Exception
*/
function civicrm_api3_group_contact_update_status($params) {
}
/**
+ * Deprecated function notices.
+ *
* @deprecated api notice
* @return array
- * of deprecated actions
+ * Array of deprecated actions
*/
function _civicrm_api3_group_contact_deprecation() {
return array(
'update_status' => 'GroupContact "update_status" action is deprecated in favor of "create".',
);
}
-
projects / civicrm-core.git / blobdiff