X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=api%2Fv3%2FContact.php;h=c9dc42d61a2256f0e8ff69bd76a022c6e609e06b;hb=af3775b322b9e4f11d097067367f0ea7763f5f10;hp=281897beb8a6f890e40fc207d8ff69490f83c9d5;hpb=6049c0d89e4b18c81cea8108acc71ba6bdc3ba85;p=civicrm-core.git diff --git a/api/v3/Contact.php b/api/v3/Contact.php index 281897beb8..c9dc42d61a 100644 --- a/api/v3/Contact.php +++ b/api/v3/Contact.php @@ -23,37 +23,30 @@ | GNU Affero General Public License or the licensing of CiviCRM, | | see the CiviCRM license FAQ at http://civicrm.org/licensing | +--------------------------------------------------------------------+ -*/ + */ /** - * 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 * - * @static void - * @access public + * @return array + * API Result Array */ function civicrm_api3_contact_create($params) { @@ -70,7 +63,7 @@ function civicrm_api3_contact_create($params) { $defLocType = CRM_Core_BAO_LocationType::getDefault(); $params['email'] = array( 1 => array( - 'email' => $email, + 'email' => $email, 'is_primary' => 1, 'location_type_id' => ($defLocType->id) ? $defLocType->id : 1, ), @@ -81,8 +74,8 @@ function civicrm_api3_contact_create($params) { if (!empty($params['home_url'])) { $websiteTypes = CRM_Core_PseudoConstant::get('CRM_Core_DAO_Website', 'website_type_id'); $params['website'] = array( - 1 => array( - 'website_type_id' => key($websiteTypes), + 1 => array( + 'website_type_id' => key($websiteTypes), 'url' => $params['home_url'], ), ); @@ -118,10 +111,10 @@ function civicrm_api3_contact_create($params) { } /** - * Adjust Metadata for Create action + * 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; @@ -140,26 +133,23 @@ function _civicrm_api3_contact_create_spec(&$params) { } /** - * Retrieve one or more contacts, given a set of search params - * - * @param array input parameters + * Retrieve one or more contacts, given a set of search params. * - * @return array API Result Array - * (@getfields contact_get} - * @static void - * @access public - * - * @example ContactGet.php Standard GET example + * @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 @@ -167,20 +157,20 @@ function civicrm_api3_contact_get($params) { 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'; @@ -220,7 +210,9 @@ function _civicrm_api3_contact_get_spec(&$params) { } /** - * 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 @@ -265,16 +257,13 @@ function _civicrm_api3_contact_get_supportanomalies(&$params, &$options) { } /** - * Delete a contact with given contact id + * Delete a Contact with given contact_id. * * @param array $params - * (reference ) input parameters, contact_id element required. - * - * @return array API Result Array - * @access public + * input parameters per getfields * - * @example ContactDelete.php - * {@getfields contact_delete} + * @return array + * API Result Array */ function civicrm_api3_contact_delete($params) { @@ -303,18 +292,18 @@ function civicrm_api3_contact_delete($params) { /** + * Check parameters passed in. + * + * This function is on it's way out. + * * @param array $params * @param bool $dupeCheck - * @param bool $dupeErrorArray - * @param bool $obsoletevalue - * @param int $dedupeRuleGroupID * * @return null * @throws API_Exception * @throws CiviCRM_API3_Exception */ -function _civicrm_api3_contact_check_params(&$params, $dupeCheck = TRUE, $dupeErrorArray = FALSE, $obsoletevalue = TRUE, $dedupeRuleGroupID = NULL) -{ +function _civicrm_api3_contact_check_params(&$params, $dupeCheck) { switch (strtolower(CRM_Utils_Array::value('contact_type', $params))) { case 'household': @@ -362,7 +351,7 @@ function _civicrm_api3_contact_check_params(&$params, $dupeCheck = TRUE, $dupeEr $ids = CRM_Dedupe_Finder::dupesByParams($dedupeParams, $params['contact_type'], 'Unsupervised', array()); if (count($ids) > 0) { - throw new API_Exception("Found matching contacts: " . implode(',', $ids), "duplicate", array("ids" => $ids)); + throw new API_Exception("Found matching contacts: " . implode(',', $ids), "duplicate", array("ids" => $ids)); } } @@ -391,9 +380,9 @@ function _civicrm_api3_contact_check_params(&$params, $dupeCheck = TRUE, $dupeEr $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' + 'contact_type' => 'Organization', )); $params['employer_id'] = $result['id']; } @@ -403,17 +392,14 @@ function _civicrm_api3_contact_check_params(&$params, $dupeCheck = TRUE, $dupeEr } /** - * 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. * @param int $contactID * If present the contact with that ID is updated. * - * @return CRM_Contact_BAO_Contact object - * @access public - * @static + * @return CRM_Contact_BAO_Contact|CRM_Core_Error */ function _civicrm_api3_contact_update($params, $contactID = NULL) { //@todo - doesn't contact create support 'id' which is already set- check & remove @@ -425,15 +411,12 @@ function _civicrm_api3_contact_update($params, $contactID = NULL) { } /** - * 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 - * - * @access public */ function _civicrm_api3_greeting_format_params($params) { $greetingParams = array('', '_id', '_custom'); @@ -444,7 +427,7 @@ function _civicrm_api3_greeting_format_params($params) { } $formatParams = FALSE; - // unset display value from params. + // Unset display value from params. if (isset($params["{$key}{$greeting}_display"])) { unset($params["{$key}{$greeting}_display"]); } @@ -553,12 +536,14 @@ function _civicrm_api3_greeting_format_params($params) { } /** - * Old contact quick search api + * Old Contact quick search api. * * @deprecated * - * {@example ContactGetquick.php 0} + * @param array $params * + * @return array + * @throws \API_Exception */ function civicrm_api3_contact_getquick($params) { civicrm_api3_verify_mandatory($params, NULL, array('name')); @@ -702,7 +687,7 @@ function civicrm_api3_contact_getquick($params) { $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']; } @@ -711,7 +696,7 @@ function civicrm_api3_contact_getquick($params) { $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)); @@ -833,28 +818,31 @@ LIMIT 0, {$limit} if ($listCurrentEmployer && !empty($currEmpDetails)) { $contactList = array( array( - 'data' => $currEmpDetails['data'], - 'id' => $currEmpDetails['id'] - ) + 'data' => $currEmpDetails['data'], + 'id' => $currEmpDetails['id'], + ), ); } else { $contactList = array( array( 'data' => $name, - 'id' => $name - ) + 'id' => $name, + ), ); } } } - 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 of deprecated actions + * @return array + * Array of deprecated actions */ function _civicrm_api3_contact_deprecation() { return array('getquick' => 'The "getquick" action is deprecated in favor of "getlist".'); @@ -864,19 +852,14 @@ function _civicrm_api3_contact_deprecation() { * 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 - * - * @static void - * @access public + * @return array + * API Result Array */ function civicrm_api3_contact_merge($params) { $mode = CRM_Utils_Array::value('mode', $params, 'safe'); @@ -897,6 +880,8 @@ function civicrm_api3_contact_merge($params) { } /** + * Adjust metadata for contact_proximity api function. + * * @param array $params */ function _civicrm_api3_contact_proximity_spec(&$params) { @@ -909,6 +894,8 @@ function _civicrm_api3_contact_proximity_spec(&$params) { } /** + * Get contacts by proximity. + * * @param array $params * * @return array @@ -955,15 +942,16 @@ WHERE $whereClause $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 $request - * Array. + * @param array $request */ function _civicrm_api3_contact_getlist_params(&$request) { // get the autocomplete options from settings @@ -1004,19 +992,25 @@ function _civicrm_api3_contact_getlist_params(&$request) { } /** + * Get output for getlist function. + * * @see _civicrm_api3_generic_getlist_output * - * @param $result - * Array. - * @param $request - * Array. + * @param array $result + * @param array $request * * @return array */ 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']],