+--------------------------------------------------------------------+
| CiviCRM version 4.6 |
+--------------------------------------------------------------------+
- | Copyright CiviCRM LLC (c) 2004-2014 |
+ | Copyright CiviCRM LLC (c) 2004-2015 |
+--------------------------------------------------------------------+
| This file is a part of CiviCRM. |
| |
*/
/**
- * new version of civicrm apis. See blog post at
- * http://civicrm.org/node/131
- * @todo Write sth
+ * This api exposes CiviCRM contacts.
*
- * @package CiviCRM_APIv3
- * @subpackage API_Contact
- * @copyright CiviCRM LLC (c) 2004-2014
- * $Id: Contact.php 30879 2010-11-22 15:45:55Z shot $
+ * Contacts are the main entity in CiviCRM and this api is more robust than most.
+ * - Get action allows all params supported by advanced search.
+ * - Create action allows creating several related entities at once (e.g. email).
+ * - Create allows checking for duplicate contacts.
+ * Use getfields to list the full range of parameters and options supported by each action.
*
+ * @package CiviCRM_APIv3
*/
/**
- * Create or update a contact (note you should always call this via civicrm_api() & never directly)
+ * Create or update a Contact.
*
* @param array $params
* Input parameters.
*
- * Allowed @params array keys are:
- * {@getfields contact_create}
- *
- *
* @throws API_Exception
- * @example ContactCreate.php Example of Create Call
*
* @return array
* API Result Array
- *
*/
function civicrm_api3_contact_create($params) {
* Adjust Metadata for Create action.
*
* @param array $params
- * Array or parameters determined by getfields.
+ * Array of parameters determined by getfields.
*/
function _civicrm_api3_contact_create_spec(&$params) {
$params['contact_type']['api.required'] = 1;
$params['dupe_check'] = array(
'title' => 'Check for Duplicates',
'description' => 'Throw error if contact create matches dedupe rule',
+ 'type' => CRM_Utils_Type::T_BOOLEAN,
);
$params['prefix_id']['api.aliases'] = array('individual_prefix', 'individual_prefix_id');
$params['suffix_id']['api.aliases'] = array('individual_suffix', 'individual_suffix_id');
}
/**
- * Retrieve one or more contacts, given a set of search params
+ * Retrieve one or more contacts, given a set of search params.
+ *
+ * @param array $params
*
* @return array
* API Result Array
function civicrm_api3_contact_get($params) {
$options = array();
_civicrm_api3_contact_get_supportanomalies($params, $options);
- $contacts = _civicrm_api3_get_using_query_object('contact', $params, $options);
- return civicrm_api3_create_success($contacts, $params, 'contact');
+ $contacts = _civicrm_api3_get_using_query_object('Contact', $params, $options);
+ return civicrm_api3_create_success($contacts, $params, 'Contact');
}
/**
+ * Get number of contacts matching the supplied criteria.
+ *
* @param array $params
*
* @return int
function civicrm_api3_contact_getcount($params) {
$options = array();
_civicrm_api3_contact_get_supportanomalies($params, $options);
- $count = _civicrm_api3_get_using_query_object('contact', $params, $options, 1);
+ $count = _civicrm_api3_get_using_query_object('Contact', $params, $options, 1);
return (int) $count;
}
/**
- * Adjust Metadata for Get action
+ * Adjust Metadata for Get action.
*
* @param array $params
- * Array or parameters determined by getfields.
+ * Array of parameters determined by getfields.
*/
function _civicrm_api3_contact_get_spec(&$params) {
$params['contact_is_deleted']['api.default'] = 0;
- //we declare all these pseudofields as there are other undocumented fields accessible
+ // We declare all these pseudoFields as there are other undocumented fields accessible
// via the api - but if check permissions is set we only allow declared fields
- $params['address_id']['title'] = 'Primary Address ID';
- $params['street_address']['title'] = 'Primary Address Street Address';
- $params['supplemental_address_1']['title'] = 'Primary Address Supplemental Address 1';
- $params['supplemental_address_2']['title'] = 'Primary Address Supplemental Address 2';
- $params['current_employer']['title'] = 'Current Employer';
- $params['city']['title'] = 'Primary Address City';
- $params['postal_code_suffix']['title'] = 'Primary Address Post Code Suffix';
- $params['postal_code']['title'] = 'Primary Address Post Code';
- $params['geo_code_1']['title'] = 'Primary Address Latitude';
- $params['geo_code_2']['title'] = 'Primary Address Longitude';
- $params['state_province_id']['title'] = 'Primary Address State Province ID';
- $params['state_province_name']['title'] = 'Primary Address State Province Name';
- $params['state_province']['title'] = 'Primary Address State Province';
- $params['country_id']['title'] = 'Primary Address Country ID';
- $params['country']['title'] = 'Primary Address country';
- $params['worldregion_id']['title'] = 'Primary Address World Region ID';
- $params['worldregion']['title'] = 'Primary Address World Region';
- $params['phone_id']['title'] = 'Primary Phone ID';
- $params['phone']['title'] = 'Primary Phone';
- $params['phone_type_id']['title'] = 'Primary Phone Type ID';
- $params['provider_id']['title'] = 'Primary Phone Provider ID';
- $params['email_id']['title'] = 'Primary Email ID';
- $params['email']['title'] = 'Primary Email';
- $params['gender_id']['title'] = 'Gender ID';
- $params['gender']['title'] = 'Gender';
- $params['on_hold']['title'] = 'Primary Email On Hold';
- $params['im']['title'] = 'Primary Instant Messenger';
- $params['im_id']['title'] = 'Primary Instant Messenger ID';
- $params['group_id']['title'] = 'Group Memberships (filter)';
- $params['group']['title'] = 'Group Memberships (filter, array)';
- $params['tag']['title'] = 'Assigned tags (filter, array)';
+ $params['address_id'] = array(
+ 'title' => 'Primary Address ID',
+ 'type' => CRM_Utils_Type::T_INT,
+ );
+ $params['street_address'] = array(
+ 'title' => 'Primary Address Street Address',
+ 'type' => CRM_Utils_Type::T_STRING,
+ );
+ $params['supplemental_address_1'] = array(
+ 'title' => 'Primary Address Supplemental Address 1',
+ 'type' => CRM_Utils_Type::T_STRING,
+ );
+ $params['supplemental_address_2'] = array(
+ 'title' => 'Primary Address Supplemental Address 2',
+ 'type' => CRM_Utils_Type::T_STRING,
+ );
+ $params['current_employer'] = array(
+ 'title' => 'Current Employer',
+ 'type' => CRM_Utils_Type::T_STRING,
+ );
+ $params['city'] = array(
+ 'title' => 'Primary Address City',
+ 'type' => CRM_Utils_Type::T_STRING,
+ );
+ $params['postal_code_suffix'] = array(
+ 'title' => 'Primary Address Post Code Suffix',
+ 'type' => CRM_Utils_Type::T_STRING,
+ );
+ $params['postal_code'] = array(
+ 'title' => 'Primary Address Post Code',
+ 'type' => CRM_Utils_Type::T_STRING,
+ );
+ $params['geo_code_1'] = array(
+ 'title' => 'Primary Address Latitude',
+ 'type' => CRM_Utils_Type::T_STRING,
+ );
+ $params['geo_code_2'] = array(
+ 'title' => 'Primary Address Longitude',
+ 'type' => CRM_Utils_Type::T_STRING,
+ );
+ $params['state_province_id'] = array(
+ 'title' => 'Primary Address State Province ID',
+ 'type' => CRM_Utils_Type::T_INT,
+ );
+ $params['state_province_name'] = array(
+ 'title' => 'Primary Address State Province Name',
+ 'type' => CRM_Utils_Type::T_STRING,
+ );
+ $params['state_province'] = array(
+ 'title' => 'Primary Address State Province',
+ 'type' => CRM_Utils_Type::T_STRING,
+ );
+ $params['country_id'] = array(
+ 'title' => 'Primary Address Country ID',
+ 'type' => CRM_Utils_Type::T_INT,
+ );
+ $params['country'] = array(
+ 'title' => 'Primary Address country',
+ 'type' => CRM_Utils_Type::T_STRING,
+ );
+ $params['worldregion_id'] = array(
+ 'title' => 'Primary Address World Region ID',
+ 'type' => CRM_Utils_Type::T_INT,
+ );
+ $params['worldregion'] = array(
+ 'title' => 'Primary Address World Region',
+ 'type' => CRM_Utils_Type::T_STRING,
+ );
+ $params['phone_id'] = array(
+ 'title' => 'Primary Phone ID',
+ 'type' => CRM_Utils_Type::T_INT,
+ );
+ $params['phone'] = array(
+ 'title' => 'Primary Phone',
+ 'type' => CRM_Utils_Type::T_STRING,
+ );
+ $params['phone_type_id'] = array(
+ 'title' => 'Primary Phone Type ID',
+ 'type' => CRM_Utils_Type::T_INT,
+ );
+ $params['provider_id'] = array(
+ 'title' => 'Primary Phone Provider ID',
+ 'type' => CRM_Utils_Type::T_INT,
+ );
+ $params['email_id'] = array(
+ 'title' => 'Primary Email ID',
+ 'type' => CRM_Utils_Type::T_INT,
+ );
+ $params['email'] = array(
+ 'title' => 'Primary Email',
+ 'type' => CRM_Utils_Type::T_STRING,
+ );
+ $params['on_hold'] = array(
+ 'title' => 'Primary Email On Hold',
+ 'type' => CRM_Utils_Type::T_BOOLEAN,
+ );
+ $params['im'] = array(
+ 'title' => 'Primary Instant Messenger',
+ 'type' => CRM_Utils_Type::T_STRING,
+ );
+ $params['im_id'] = array(
+ 'title' => 'Primary Instant Messenger ID',
+ 'type' => CRM_Utils_Type::T_INT,
+ );
+ $params['group'] = array(
+ 'title' => 'Group',
+ 'pseudoconstant' => array(
+ 'table' => 'civicrm_group',
+ ),
+ );
+ $params['tag'] = array(
+ 'title' => 'Tags',
+ 'pseudoconstant' => array(
+ 'table' => 'civicrm_tag',
+ ),
+ );
$params['birth_date_low'] = array('name' => 'birth_date_low', 'type' => CRM_Utils_Type::T_DATE, 'title' => ts('Birth Date is equal to or greater than'));
$params['birth_date_high'] = array('name' => 'birth_date_high', 'type' => CRM_Utils_Type::T_DATE, 'title' => ts('Birth Date is equal to or less than'));
$params['deceased_date_low'] = array('name' => 'deceased_date_low', 'type' => CRM_Utils_Type::T_DATE, 'title' => ts('Deceased Date is equal to or greater than'));
}
/**
- * We are supporting 'showAll' = 'all', 'trash' or 'active' for contact get
+ * Support for historical oddities.
+ *
+ * We are supporting 'showAll' = 'all', 'trash' or 'active' for Contact get
* and for getcount
* - hopefully some day we'll come up with a std syntax for the 3-way-boolean of
* 0, 1 or not set
}
/**
- * Delete a contact with given contact id
+ * Delete a Contact with given contact_id.
*
* @param array $params
* input parameters per getfields
/**
+ * Check parameters passed in.
+ *
+ * This function is on it's way out.
+ *
* @param array $params
* @param bool $dupeCheck
*
$params['employer_id'] = $dupeIds[0];
}
else {
- $result = civicrm_api3('contact', 'create', array(
+ $result = civicrm_api3('Contact', 'create', array(
'organization_name' => $params['current_employer'],
'contact_type' => 'Organization',
));
}
/**
- * Takes an associative array and creates a contact object and all the associated
- * derived objects (i.e. individual, location, email, phone etc)
+ * Helper function for Contact create.
*
* @param array $params
* (reference ) an assoc array of name/value pairs.
}
/**
- * Validate the addressee or email or postal greetings
+ * Validate the addressee or email or postal greetings.
*
* @param array $params
- * Associative array of property name/value.
- * pairs to insert in new contact.
+ * Array per getfields metadata.
*
* @throws API_Exception
- *
*/
function _civicrm_api3_greeting_format_params($params) {
$greetingParams = array('', '_id', '_custom');
}
$formatParams = FALSE;
- // unset display value from params.
+ // Unset display value from params.
if (isset($params["{$key}{$greeting}_display"])) {
unset($params["{$key}{$greeting}_display"]);
}
}
/**
- * Old contact quick search api
+ * Old Contact quick search api.
*
* @deprecated
*
- * {@example ContactGetquick.php 0}
* @param array $params
+ *
* @return array
* @throws \API_Exception
*/
$where .= " AND cc.contact_type LIKE '{$contactType}'";
}
- //set default for current_employer or return contact with particular id
+ // Set default for current_employer or return contact with particular id
if (!empty($params['id'])) {
$where .= " AND cc.id = " . (int) $params['id'];
}
$where .= " AND cc.id <> " . (int) $params['cid'];
}
- //contact's based of relationhip type
+ // Contact's based of relationhip type
$relType = NULL;
if (!empty($params['rel'])) {
$relation = explode('_', CRM_Utils_Array::value('rel', $params));
}
}
- return civicrm_api3_create_success($contactList, $params, 'contact', 'getquick');
+ return civicrm_api3_create_success($contactList, $params, 'Contact', 'getquick');
}
/**
+ * Declare deprecated api functions.
+ *
* @deprecated api notice
* @return array
* Array of deprecated actions
* Merges given pair of duplicate contacts.
*
* @param array $params
- * Input parameters.
- *
- * Allowed @params array keys are:
- * {int main_id main contact id with whom merge has to happen}
- * {int other_id duplicate contact which would be deleted after merge operation}
- * {string mode helps decide how to behave when there are conflicts.
- * A 'safe' value skips the merge if there are no conflicts. Does a force merge otherwise.}
- * {boolean auto_flip wether to let api decide which contact to retain and which to delete.}
+ * Allowed array keys are:
+ * -int main_id: main contact id with whom merge has to happen
+ * -int other_id: duplicate contact which would be deleted after merge operation
+ * -string mode: "safe" skips the merge if there are no conflicts. Does a force merge otherwise.
+ * -boolean auto_flip: whether to let api decide which contact to retain and which to delete.
*
* @return array
* API Result Array
- *
*/
function civicrm_api3_contact_merge($params) {
$mode = CRM_Utils_Array::value('mode', $params, 'safe');
}
/**
+ * Adjust metadata for contact_proximity api function.
+ *
* @param array $params
*/
function _civicrm_api3_contact_proximity_spec(&$params) {
- $params['latitude']['api.required'] = 1;
- $params['latitude']['title'] = 'Latitude';
- $params['longitude']['api.required'] = 1;
- $params['longitude']['title'] = 'Longitude';
- $params['unit']['api.default'] = 'meter';
- $params['unit']['title'] = 'Unit of Measurement';
+ $params['latitude'] = array(
+ 'title' => 'Latitude',
+ 'api.required' => 1,
+ 'type' => CRM_Utils_Type::T_STRING,
+ );
+ $params['longitude'] = array(
+ 'title' => 'Longitude',
+ 'api.required' => 1,
+ 'type' => CRM_Utils_Type::T_STRING,
+ );
+
+ $params['unit'] = array(
+ 'title' => 'Unit of Measurement',
+ 'api.default' => 'meter',
+ 'type' => CRM_Utils_Type::T_STRING,
+ );
}
/**
+ * Get contacts by proximity.
+ *
* @param array $params
*
* @return array
$contacts[] = $dao->toArray();
}
- return civicrm_api3_create_success($contacts, $params, 'contact', 'get_by_location', $dao);
+ return civicrm_api3_create_success($contacts, $params, 'Contact', 'get_by_location', $dao);
}
/**
+ * Get parameters for getlist function.
+ *
* @see _civicrm_api3_generic_getlist_params
*
* @param array $request
}
/**
+ * Get output for getlist function.
+ *
* @see _civicrm_api3_generic_getlist_output
*
* @param array $result
function _civicrm_api3_contact_getlist_output($result, $request) {
$output = array();
if (!empty($result['values'])) {
- $addressFields = array_intersect(array('street_address', 'city', 'state_province', 'country'), $request['params']['return']);
+ $addressFields = array_intersect(array(
+ 'street_address',
+ 'city',
+ 'state_province',
+ 'country',
+ ),
+ $request['params']['return']);
foreach ($result['values'] as $row) {
$data = array(
'id' => $row[$request['id_field']],
else {
$data['icon_class'] = $row['contact_type'];
}
- foreach ($request['extra'] as $field) {
- $data['extra'][$field] = isset($row[$field]) ? $row[$field] : NULL;
- }
$output[] = $data;
}
}
projects / civicrm-core.git / blobdiff