X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=api%2Fv3%2FContact.php;h=c9dc42d61a2256f0e8ff69bd76a022c6e609e06b;hb=af3775b322b9e4f11d097067367f0ea7763f5f10;hp=3e33f35e78c626e0991ad16d4e5581dfe9715f10;hpb=61fe4988936f8bb28644451af665a141d6eb4c7b;p=civicrm-core.git

diff --git a/api/v3/Contact.php b/api/v3/Contact.php
index 3e33f35e78..c9dc42d61a 100644
--- a/api/v3/Contact.php
+++ b/api/v3/Contact.php
@@ -26,33 +26,27 @@
  */
 
 /**
- * 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) {
 
@@ -120,7 +114,7 @@ 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;
@@ -149,12 +143,12 @@ function _civicrm_api3_contact_create_spec(&$params) {
 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 count of contact.
+ * Get number of contacts matching the supplied criteria.
  *
  * @param array $params
  *
@@ -163,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';
@@ -216,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
@@ -261,7 +257,7 @@ 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
  *   input parameters per getfields
@@ -296,6 +292,10 @@ function civicrm_api3_contact_delete($params) {
 
 
 /**
+ * Check parameters passed in.
+ *
+ * This function is on it's way out.
+ *
  * @param array $params
  * @param bool $dupeCheck
  *
@@ -380,7 +380,7 @@ function _civicrm_api3_contact_check_params(&$params, $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',
       ));
@@ -392,8 +392,7 @@ function _civicrm_api3_contact_check_params(&$params, $dupeCheck) {
 }
 
 /**
- * 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.
@@ -412,14 +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
- *
  */
 function _civicrm_api3_greeting_format_params($params) {
   $greetingParams = array('', '_id', '_custom');
@@ -430,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"]);
     }
@@ -539,12 +536,12 @@ 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
  */
@@ -690,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'];
   }
@@ -699,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));
@@ -837,7 +834,7 @@ LIMIT    0, {$limit}
     }
   }
 
-  return civicrm_api3_create_success($contactList, $params, 'contact', 'getquick');
+  return civicrm_api3_create_success($contactList, $params, 'Contact', 'getquick');
 }
 
 /**
@@ -855,18 +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
- *
  */
 function civicrm_api3_contact_merge($params) {
   $mode = CRM_Utils_Array::value('mode', $params, 'safe');
@@ -887,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) {
@@ -899,6 +894,8 @@ function _civicrm_api3_contact_proximity_spec(&$params) {
 }
 
 /**
+ * Get contacts by proximity.
+ *
  * @param array $params
  *
  * @return array
@@ -945,11 +942,13 @@ 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 array $request
@@ -993,6 +992,8 @@ function _civicrm_api3_contact_getlist_params(&$request) {
 }
 
 /**
+ * Get output for getlist function.
+ *
  * @see _civicrm_api3_generic_getlist_output
  *
  * @param array $result
@@ -1003,7 +1004,13 @@ function _civicrm_api3_contact_getlist_params(&$request) {
 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']],