X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=api%2Fv3%2Futils.php;h=988016a1f38fec78f83d9bdab1c2ecf257c2e5c5;hb=27861c9e51c9bdf4ceb4945ea8dcb0d529081a08;hp=53af3b736d31761ba441b4803a6cf7d03605371c;hpb=d09979215fb8fa66d3403e88518e6448ed546edb;p=civicrm-core.git

diff --git a/api/v3/utils.php b/api/v3/utils.php
index 53af3b736d..988016a1f3 100644
--- a/api/v3/utils.php
+++ b/api/v3/utils.php
@@ -23,21 +23,16 @@
   | GNU Affero General Public License or the licensing of CiviCRM,     |
   | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
   +--------------------------------------------------------------------+
-*/
+ */
 
 /**
- * File for CiviCRM APIv3 utilitity functions
+ * CiviCRM APIv3 utility functions.
  *
  * @package CiviCRM_APIv3
- * @subpackage API_utils
- *
- * @copyright CiviCRM LLC (c) 2004-2014
- * @version $Id: utils.php 30879 2010-11-22 15:45:55Z shot $
- *
  */
 
 /**
- * Initialize CiviCRM - should be run at the start of each API function
+ * Initialize CiviCRM - should be run at the start of each API function.
  */
 function _civicrm_api3_initialize() {
   require_once 'CRM/Core/ClassLoader.php';
@@ -46,7 +41,7 @@ function _civicrm_api3_initialize() {
 }
 
 /**
- * Wrapper Function for civicrm_verify_mandatory to make it simple to pass either / or fields for checking
+ * Wrapper Function for civicrm_verify_mandatory to make it simple to pass either / or fields for checking.
  *
  * @param array $params
  *   Array of fields to check.
@@ -54,10 +49,6 @@ function _civicrm_api3_initialize() {
  *   String DAO to check for required fields (create functions only).
  * @param array $keyoptions
  *   List of required fields options. One of the options is required.
- *
- * @return null
- *   or throws error if there the required fields not present
- * @
  */
 function civicrm_api3_verify_one_mandatory($params, $daoName = NULL, $keyoptions = array()) {
   $keys = array(array());
@@ -68,7 +59,7 @@ function civicrm_api3_verify_one_mandatory($params, $daoName = NULL, $keyoptions
 }
 
 /**
- * check mandatory fields are included
+ * Check mandatory fields are included.
  *
  * @param array $params
  *   Array of fields to check.
@@ -78,11 +69,7 @@ function civicrm_api3_verify_one_mandatory($params, $daoName = NULL, $keyoptions
  *   List of required fields. A value can be an array denoting that either this or that is required.
  * @param bool $verifyDAO
  *
- * @throws API_Exception
- * @return null
- *   or throws error if there the required fields not present
- *
- * @todo see notes on _civicrm_api3_check_required_fields regarding removing $daoName param
+ * @throws \API_Exception
  */
 function civicrm_api3_verify_mandatory($params, $daoName = NULL, $keys = array(), $verifyDAO = TRUE) {
 
@@ -134,9 +121,11 @@ function civicrm_api3_verify_mandatory($params, $daoName = NULL, $keys = array()
 }
 
 /**
+ * Create error array.
  *
- * @param $msg
+ * @param string $msg
  * @param array $data
+ *
  * @return array
  */
 function civicrm_api3_create_error($msg, $data = array()) {
@@ -145,7 +134,8 @@ function civicrm_api3_create_error($msg, $data = array()) {
   // we will show sql to privileged user only (not sure of a specific
   // security hole here but seems sensible - perhaps should apply to the trace as well?)
   if (isset($data['sql']) && CRM_Core_Permission::check('Administer CiviCRM')) {
-    $data['debug_information'] = $data['sql']; // Isn't this redundant?
+    // Isn't this redundant?
+    $data['debug_information'] = $data['sql'];
   }
   else {
     unset($data['sql']);
@@ -154,7 +144,7 @@ function civicrm_api3_create_error($msg, $data = array()) {
 }
 
 /**
- * Format array in result output styple
+ * Format array in result output style.
  *
  * @param array|int $values values generated by API operation (the result)
  * @param array $params
@@ -207,7 +197,24 @@ function civicrm_api3_create_success($values = 1, $params = array(), $entity = N
       $allFields = array_keys($apiFields['values']);
     }
     $paramFields = array_keys($params);
-    $undefined = array_diff($paramFields, $allFields, array_keys($_COOKIE), array('action', 'entity', 'debug', 'version', 'check_permissions', 'IDS_request_uri', 'IDS_user_agent', 'return', 'sequential', 'rowCount', 'option_offset', 'option_limit', 'custom', 'option_sort', 'options', 'prettyprint'));
+    $undefined = array_diff($paramFields, $allFields, array_keys($_COOKIE), array(
+      'action',
+      'entity',
+      'debug',
+      'version',
+      'check_permissions',
+      'IDS_request_uri',
+      'IDS_user_agent',
+      'return',
+      'sequential',
+      'rowCount',
+      'option_offset',
+      'option_limit',
+      'custom',
+      'option_sort',
+      'options',
+      'prettyprint',
+      ));
     if ($undefined) {
       $result['undefined_fields'] = array_merge($undefined);
     }
@@ -243,20 +250,22 @@ function civicrm_api3_create_success($values = 1, $params = array(), $entity = N
     $result['values'] = $values;
   }
   if (!empty($params['options']['metadata'])) {
-    // we've made metadata an array but only supporting 'fields' atm
+    // We've made metadata an array but only supporting 'fields' atm.
     if (in_array('fields', (array) $params['options']['metadata']) && $action !== 'getfields') {
-      $fields = civicrm_api3($entity, 'getfields', array('action' => substr($action, 0, 3) == 'get' ? 'get' : 'create'));
+      $fields = civicrm_api3($entity, 'getfields', array(
+        'action' => substr($action, 0, 3) == 'get' ? 'get' : 'create',
+      ));
       $result['metadata']['fields'] = $fields['values'];
     }
   }
-  // Report deprecations
+  // Report deprecations.
   $deprecated = _civicrm_api3_deprecation_check($entity, $result);
-  // Always report "update" action as deprecated
+  // Always report "update" action as deprecated.
   if (!is_string($deprecated) && ($action == 'getactions' || $action == 'update')) {
     $deprecated = ((array) $deprecated) + array('update' => 'The "update" action is deprecated. Use "create" with an id instead.');
   }
   if ($deprecated) {
-    // Metadata-level deprecations or wholesale entity deprecations
+    // Metadata-level deprecations or wholesale entity deprecations.
     if ($entity == 'entity' || $action == 'getactions' || is_string($deprecated)) {
       $result['deprecated'] = $deprecated;
     }
@@ -269,8 +278,10 @@ function civicrm_api3_create_success($values = 1, $params = array(), $entity = N
 }
 
 /**
- * Load the DAO of the entity
+ * Load the DAO of the entity.
+ *
  * @param $entity
+ *
  * @return bool
  */
 function _civicrm_api3_load_DAO($entity) {
@@ -283,11 +294,13 @@ function _civicrm_api3_load_DAO($entity) {
 }
 
 /**
- * return the DAO of the function or Entity
+ * Return the DAO of the function or Entity.
+ *
  * @param string $name
  *   Either a function of the api (civicrm_{entity}_create or the entity name.
  *   return the DAO name to manipulate this function
  *   eg. "civicrm_api3_contact_create" or "Contact" will return "CRM_Contact_BAO_Contact"
+ *
  * @return mixed|string
  */
 function _civicrm_api3_get_DAO($name) {
@@ -351,11 +364,13 @@ function _civicrm_api3_get_DAO($name) {
 }
 
 /**
- * return the DAO of the function or Entity
+ * Return the DAO of the function or Entity.
+ *
  * @param string $name
  *   Is either a function of the api (civicrm_{entity}_create or the entity name.
  *   return the DAO name to manipulate this function
  *   eg. "civicrm_contact_create" or "Contact" will return "CRM_Contact_BAO_Contact"
+ *
  * @return mixed
  */
 function _civicrm_api3_get_BAO($name) {
@@ -374,7 +389,8 @@ function _civicrm_api3_get_BAO($name) {
 }
 
 /**
- *  Recursive function to explode value-separated strings into arrays
+ * Recursive function to explode value-separated strings into arrays.
+ *
  * @param $values
  */
 function _civicrm_api3_separate_values(&$values) {
@@ -384,7 +400,8 @@ function _civicrm_api3_separate_values(&$values) {
       _civicrm_api3_separate_values($value);
     }
     elseif (is_string($value)) {
-      if ($key == 'case_type_id') {// this is to honor the way case API was originally written
+      // This is to honor the way case API was originally written.
+      if ($key == 'case_type_id') {
         $value = trim(str_replace($sp, ',', $value), ',');
       }
       elseif (strpos($value, $sp) !== FALSE) {
@@ -395,12 +412,14 @@ function _civicrm_api3_separate_values(&$values) {
 }
 
 /**
- * This is a legacy wrapper for api_store_values which will check the suitable fields using getfields
- * rather than DAO->fields
+ * This is a legacy wrapper for api_store_values.
  *
- * Getfields has handling for how to deal with uniquenames which dao->fields doesn't
+ * It checks suitable fields using getfields rather than DAO->fields.
+ *
+ * Getfields has handling for how to deal with unique names which dao->fields doesn't
  *
  * Note this is used by BAO type create functions - eg. contribution
+ *
  * @param string $entity
  * @param array $params
  * @param array $values
@@ -411,6 +430,7 @@ function _civicrm_api3_filter_fields_for_bao($entity, &$params, &$values) {
   _civicrm_api3_store_values($fields, $params, $values);
 }
 /**
+ * Store values.
  *
  * @param array $fields
  * @param array $params
@@ -432,15 +452,18 @@ function _civicrm_api3_store_values(&$fields, &$params, &$values) {
 }
 
 /**
- * The API supports 2 types of get requestion. The more complex uses the BAO query object.
+ * Get function for query object api.
+ *
+ * The API supports 2 types of get request. The more complex uses the BAO query object.
  *  This is a generic function for those functions that call it
  *
  *  At the moment only called by contact we should extend to contribution &
  *  others that use the query object. Note that this function passes permission information in.
  *  The others don't
  *
- * * Ideally this would be merged with _civicrm_get_query_object but we need to resolve differences in what the
+ * Ideally this would be merged with _civicrm_get_query_object but we need to resolve differences in what the
  * 2 variants call
+ *
  * @param $entity
  * @param array $params
  *   As passed into api get or getcount function.
@@ -500,6 +523,10 @@ function _civicrm_api3_get_using_query_object($entity, $params, $additional_opti
     $returnProperties = NULL;
   }
 
+  if (substr($sort, 0, 2) == 'id') {
+    $sort = $entity . "_" . $sort;
+  }
+
   $newParams = CRM_Contact_BAO_Query::convertFormValues($inputParams);
   foreach ($newParams as &$newParam) {
     if ($newParam[1] == '='  && is_array($newParam[2])) {
@@ -511,7 +538,6 @@ function _civicrm_api3_get_using_query_object($entity, $params, $additional_opti
         $newParam[2] = $sqlFilter;
       }
     }
-
   }
 
   $skipPermissions = !empty($params['check_permissions']) ? 0 : 1;
@@ -527,7 +553,8 @@ function _civicrm_api3_get_using_query_object($entity, $params, $additional_opti
     $getCount,
     $skipPermissions
   );
-  if ($getCount) { // only return the count of contacts
+  if ($getCount) {
+    // only return the count of contacts
     return $entities;
   }
 
@@ -535,22 +562,24 @@ function _civicrm_api3_get_using_query_object($entity, $params, $additional_opti
 }
 
 /**
- * get dao query object based on input params
+ * Get dao query object based on input params.
+ *
  * Ideally this would be merged with _civicrm_get_using_query_object but we need to resolve differences in what the
  * 2 variants call
  *
  * @param array $params
  * @param string $mode
  * @param string $entity
- * @return CRM_Core_DAO
- *   query object
+ *
+ * @return array
+ *   [CRM_Core_DAO|CRM_Contact_BAO_Query]
  */
 function _civicrm_api3_get_query_object($params, $mode, $entity) {
-  $options          = _civicrm_api3_get_options_from_params($params, TRUE, $entity, 'get');
-  $sort             = CRM_Utils_Array::value('sort', $options, NULL);
-  $offset           = CRM_Utils_Array::value('offset', $options);
-  $rowCount         = CRM_Utils_Array::value('limit', $options);
-  $inputParams      = CRM_Utils_Array::value('input_params', $options, array());
+  $options = _civicrm_api3_get_options_from_params($params, TRUE, $entity, 'get');
+  $sort = CRM_Utils_Array::value('sort', $options, NULL);
+  $offset = CRM_Utils_Array::value('offset', $options);
+  $rowCount = CRM_Utils_Array::value('limit', $options);
+  $inputParams = CRM_Utils_Array::value('input_params', $options, array());
   $returnProperties = CRM_Utils_Array::value('return', $options, NULL);
   if (empty($returnProperties)) {
     $returnProperties = CRM_Contribute_BAO_Query::defaultReturnProperties($mode);
@@ -576,7 +605,8 @@ function _civicrm_api3_get_query_object($params, $mode, $entity) {
 }
 
 /**
- * Function transfers the filters being passed into the DAO onto the params object
+ * Function transfers the filters being passed into the DAO onto the params object.
+ *
  * @param CRM_Core_DAO $dao
  * @param array $params
  * @param bool $unique
@@ -642,21 +672,24 @@ function _civicrm_api3_dao_set_filter(&$dao, $params, $unique = TRUE, $entity) {
   }
   if (!empty($options['return']) && is_array($options['return']) && empty($options['is_count'])) {
     $dao->selectAdd();
-    $options['return']['id'] = TRUE;// ensure 'id' is included
+    // Ensure 'id' is included.
+    $options['return']['id'] = TRUE;
     $allfields = _civicrm_api3_get_unique_name_array($dao);
     $returnMatched = array_intersect(array_keys($options['return']), $allfields);
     foreach ($returnMatched as $returnValue) {
       $dao->selectAdd($returnValue);
     }
 
-    $unmatchedFields = array_diff(// not already matched on the field names
+    // Not already matched on the field names.
+    $unmatchedFields = array_diff(
       array_keys($options['return']),
       $returnMatched
     );
 
     $returnUniqueMatched = array_intersect(
       $unmatchedFields,
-      array_flip($allfields)// but a match for the field keys
+      // But a match for the field keys.
+      array_flip($allfields)
     );
     foreach ($returnUniqueMatched as $uniqueVal) {
       $dao->selectAdd($allfields[$uniqueVal]);
@@ -666,7 +699,8 @@ function _civicrm_api3_dao_set_filter(&$dao, $params, $unique = TRUE, $entity) {
 }
 
 /**
- * Apply filters (e.g. high, low) to DAO object (prior to find)
+ * Apply filters (e.g. high, low) to DAO object (prior to find).
+ *
  * @param string $filterField
  *   Field name of filter.
  * @param string $filterValue
@@ -695,12 +729,13 @@ function _civicrm_api3_apply_filters_to_dao($filterField, $filterValue, &$dao) {
 
 /**
  * Get sort, limit etc options from the params - supporting old & new formats.
- * get returnproperties for legacy
+ *
+ * Get returnProperties for legacy
  *
  * @param array $params
  *   Params array as passed into civicrm_api.
  * @param bool $queryObject
- *   Is this supporting a queryobject api (e.g contact) - if so we support more options.
+ *   Is this supporting a queryObject api (e.g contact) - if so we support more options.
  *   for legacy report & return a unique fields array
  *
  * @param string $entity
@@ -801,7 +836,7 @@ function _civicrm_api3_get_options_from_params(&$params, $queryObject = FALSE, $
 }
 
 /**
- * Apply options (e.g. sort, limit, order by) to DAO object (prior to find)
+ * Apply options (e.g. sort, limit, order by) to DAO object (prior to find).
  *
  * @param array $params
  *   Params array as passed into civicrm_api.
@@ -823,11 +858,15 @@ function _civicrm_api3_apply_options_to_dao(&$params, &$dao, $entity) {
 }
 
 /**
- * build fields array. This is the array of fields as it relates to the given DAO
+ * Build fields array.
+ *
+ * This is the array of fields as it relates to the given DAO
  * returns unique fields as keys by default but if set but can return by DB fields
- * @param $bao
+ *
+ * @param CRM_Core_DAO $bao
  * @param bool $unique
- * @return
+ *
+ * @return array
  */
 function _civicrm_api3_build_fields_array(&$bao, $unique = TRUE) {
   $fields = $bao->fields();
@@ -847,11 +886,14 @@ function _civicrm_api3_build_fields_array(&$bao, $unique = TRUE) {
 }
 
 /**
- * build fields array. This is the array of fields as it relates to the given DAO
+ * Build fields array.
+ *
+ * This is the array of fields as it relates to the given DAO
  * returns unique fields as keys by default but if set but can return by DB fields
- * @param CRM_Core_BAO $bao
  *
- * @return mixed
+ * @param CRM_Core_DAO $bao
+ *
+ * @return array
  */
 function _civicrm_api3_get_unique_name_array(&$bao) {
   $fields = $bao->fields();
@@ -862,7 +904,7 @@ function _civicrm_api3_get_unique_name_array(&$bao) {
 }
 
 /**
- * Converts an DAO object to an array
+ * Converts an DAO object to an array.
  *
  * @param CRM_Core_DAO $dao
  *   Object to convert.
@@ -872,9 +914,6 @@ function _civicrm_api3_get_unique_name_array(&$bao) {
  * @param bool $autoFind
  *
  * @return array
- *
- * @static
- * @access public
  */
 function _civicrm_api3_dao_to_array($dao, $params = NULL, $uniqueFields = TRUE, $entity = "", $autoFind = TRUE) {
   $result = array();
@@ -915,13 +954,15 @@ function _civicrm_api3_dao_to_array($dao, $params = NULL, $uniqueFields = TRUE,
 }
 
 /**
+ * Determine if custom fields need to be retrieved.
+ *
  * We currently retrieve all custom fields or none at this level so if we know the entity
  * && it can take custom fields & there is the string 'custom' in their return request we get them all, they are filtered on the way out
  * @todo filter so only required fields are queried
  *
- * @param array $params
  * @param string $entity
  *   Entity name in CamelCase.
+ * @param array $params
  *
  * @return bool
  */
@@ -930,24 +971,20 @@ function _civicrm_api3_custom_fields_are_required($entity, $params) {
     return FALSE;
   }
   $options = _civicrm_api3_get_options_from_params($params);
-  //we check for possibility of 'custom' => 1 as well as specific custom fields
+  // We check for possibility of 'custom' => 1 as well as specific custom fields.
   $returnString = implode('', $options['return']) . implode('', array_keys($options['return']));
   if (stristr($returnString, 'custom')) {
     return TRUE;
   }
 }
 /**
- * Converts an object to an array
+ * Converts an object to an array.
  *
  * @param object $dao
  *   (reference) object to convert.
  * @param array $values
  *   (reference) array.
  * @param array|bool $uniqueFields
- *
- * @return array
- * @static
- * @access public
  */
 function _civicrm_api3_object_to_array(&$dao, &$values, $uniqueFields = FALSE) {
 
@@ -960,9 +997,11 @@ function _civicrm_api3_object_to_array(&$dao, &$values, $uniqueFields = FALSE) {
 }
 
 /**
- * Wrapper for _civicrm_object_to_array when api supports unique fields
+ * Wrapper for _civicrm_object_to_array when api supports unique fields.
+ *
  * @param $dao
  * @param $values
+ *
  * @return array
  */
 function _civicrm_api3_object_to_array_unique_fields(&$dao, &$values) {
@@ -970,6 +1009,7 @@ function _civicrm_api3_object_to_array_unique_fields(&$dao, &$values) {
 }
 
 /**
+ * Format custom parameters.
  *
  * @param array $params
  * @param array $values
@@ -1008,6 +1048,8 @@ function _civicrm_api3_custom_format_params($params, &$values, $extends, $entity
 }
 
 /**
+ * Format parameters for create action.
+ *
  * @param array $params
  * @param $entity
  */
@@ -1024,7 +1066,9 @@ function _civicrm_api3_format_params_for_create(&$params, $entity) {
 }
 
 /**
- * we can't rely on downstream to add separators to checkboxes so we'll check here. We should look at pushing to BAO function
+ * We can't rely on downstream to add separators to checkboxes so we'll check here.
+ *
+ * We should look at pushing to BAO function
  * and / or validate function but this is a safe place for now as it has massive test coverage & we can keep the change very specific
  * note that this is specifically tested in the GRANT api test case so later refactoring should use that as a checking point
  *
@@ -1042,20 +1086,19 @@ function _civicrm_api3_format_params_for_create(&$params, $entity) {
  * @todo - we are probably skipping handling disabled options as presumably getoptions is not giving us them. This should be non-regressive but might
  * be fixed in future
  *
- * @param $checkboxFieldValue
- * @param $customFieldLabel
- * @param $entity
- *
+ * @param mixed $checkboxFieldValue
+ * @param string $customFieldLabel
+ * @param string $entity
  */
 function formatCheckBoxField(&$checkboxFieldValue, $customFieldLabel, $entity) {
 
   if (is_string($checkboxFieldValue) && stristr($checkboxFieldValue, CRM_Core_DAO::VALUE_SEPARATOR)) {
-    // we can assume it's pre-formatted
+    // We can assume it's pre-formatted.
     return;
   }
   $options = civicrm_api($entity, 'getoptions', array('field' => $customFieldLabel, 'version' => 3));
   if (!empty($options['is_error'])) {
-    //the check is precautionary - can probably be removed later
+    // The check is precautionary - can probably be removed later.
     return;
   }
 
@@ -1119,14 +1162,15 @@ function formatCheckBoxField(&$checkboxFieldValue, $customFieldLabel, $entity) {
 }
 
 /**
+ * This function ensures that we have the right input parameters.
+ *
  * @deprecated
- * This function ensures that we have the right input parameters
  *
  * This function is only called when $dao is passed into verify_mandatory.
  * The practice of passing $dao into verify_mandatory turned out to be
- * unsatisfactory as the required fields @ the dao level is so diffent to the abstract
+ * unsatisfactory as the required fields @ the dao level is so different to the abstract
  * api level. Hence the intention is to remove this function
- * & the associated param from viery_mandatory
+ * & the associated param from verify_mandatory
  *
  * @param array $params
  *   Associative array of property name/value.
@@ -1137,9 +1181,8 @@ function formatCheckBoxField(&$checkboxFieldValue, $customFieldLabel, $entity) {
  * @daoName string DAO to check params agains
  *
  * @return bool
- *   Sshould the missing fields be returned as an array (core error created as default)
+ *   Should the missing fields be returned as an array (core error created as default)
  *   true if all fields present, depending on $result a core error is created of an array of missing fields is returned
- * @access public
  */
 function _civicrm_api3_check_required_fields($params, $daoName, $return = FALSE) {
   //@deprecated - see notes
@@ -1186,7 +1229,7 @@ function _civicrm_api3_check_required_fields($params, $daoName, $return = FALSE)
 }
 
 /**
- * Function to do a 'standard' api get - when the api is only doing a $bao->find then use this
+ * Function to do a 'standard' api get - when the api is only doing a $bao->find then use this.
  *
  * @param string $bao_name
  *   Name of BAO.
@@ -1210,7 +1253,7 @@ function _civicrm_api3_basic_get($bao_name, &$params, $returnAsSuccess = TRUE, $
 }
 
 /**
- * Function to do a 'standard' api create - when the api is only doing a $bao::create then use this
+ * Function to do a 'standard' api create - when the api is only doing a $bao::create then use this.
  *
  * @param string $bao_name
  *   Name of BAO Class.
@@ -1275,7 +1318,9 @@ function _civicrm_api3_basic_create($bao_name, &$params, $entity = NULL) {
  * @param array $params
  *
  * @throws API_Exception
- * @return CRM_Core_DAO|NULL an instance of the BAO
+ *
+ * @return CRM_Core_DAO|NULL
+ *   An instance of the BAO
  */
 function _civicrm_api3_basic_create_fallback($bao_name, &$params) {
   $dao_name = get_parent_class($bao_name);
@@ -1300,8 +1345,9 @@ function _civicrm_api3_basic_create_fallback($bao_name, &$params) {
 }
 
 /**
- * Function to do a 'standard' api del - when the api is only doing a $bao::del then use this
- * if api::del doesn't exist it will try DAO delete method
+ * Function to do a 'standard' api del.
+ *
+ * When the api is only doing a $bao::del then use this if api::del doesn't exist it will try DAO delete method.
  *
  * @param string $bao_name
  * @param array $params
@@ -1339,7 +1385,10 @@ function _civicrm_api3_basic_delete($bao_name, &$params) {
 }
 
 /**
- * Get custom data for the given entity & Add it to the returnArray as 'custom_123' = 'custom string' AND 'custom_123_1' = 'custom string'
+ * Get custom data for the given entity & Add it to the returnArray.
+ *
+ * This looks like 'custom_123' = 'custom string' AND
+ * 'custom_123_1' = 'custom string'
  * Where 123 is field value & 1 is the id within the custom group data table (value ID)
  *
  * @param array $returnArray
@@ -1388,11 +1437,14 @@ function _civicrm_api3_custom_data_get(&$returnArray, $entity, $entity_id, $grou
 }
 
 /**
- * Validate fields being passed into API. This function relies on the getFields function working accurately
+ * Validate fields being passed into API.
+ *
+ * This function relies on the getFields function working accurately
  * for the given API. If error mode is set to TRUE then it will also check
  * foreign keys
  *
  * As of writing only date was implemented.
+ *
  * @param string $entity
  * @param string $action
  * @param array $params
@@ -1401,6 +1453,7 @@ function _civicrm_api3_custom_data_get(&$returnArray, $entity, $entity_id, $grou
  *   Response from getfields all variables are the same as per civicrm_api.
  * @param bool $errorMode
  *   ErrorMode do intensive post fail checks?.
+ *
  * @throws Exception
  */
 function _civicrm_api3_validate_fields($entity, $action, &$params, $fields, $errorMode = FALSE) {
@@ -1419,7 +1472,8 @@ function _civicrm_api3_validate_fields($entity, $action, &$params, $fields, $err
         _civicrm_api3_validate_date($params, $fieldName, $fieldInfo);
         break;
 
-    case 32://blob
+      case 32:
+        //blob
         _civicrm_api3_validate_html($params, $fieldName, $fieldInfo);
         break;
 
@@ -1432,7 +1486,7 @@ function _civicrm_api3_validate_fields($entity, $action, &$params, $fields, $err
         if (strpos($op, 'NULL') !== FALSE || strpos($op, 'EMPTY') !== FALSE) {
           break;
         }
-        foreach((array)$fieldValue as $fieldvalue) {
+        foreach ((array) $fieldValue as $fieldvalue) {
           if (!CRM_Utils_Rule::money($fieldvalue) && !empty($fieldvalue)) {
             throw new Exception($fieldName . " is  not a valid amount: " . $params[$fieldName]);
           }
@@ -1452,7 +1506,7 @@ function _civicrm_api3_validate_fields($entity, $action, &$params, $fields, $err
       }
       if (!empty($fieldInfo['api.unique'])) {
         $params['entity'] = $entity;
-        _civicrm_api3_validate_uniquekey($params, $fieldName, $fieldInfo);
+        _civicrm_api3_validate_unique_key($params, $fieldName);
       }
     }
   }
@@ -1460,6 +1514,7 @@ function _civicrm_api3_validate_fields($entity, $action, &$params, $fields, $err
 
 /**
  * Validate date fields being passed into API.
+ *
  * It currently converts both unique fields and DB field names to a mysql date.
  * @todo - probably the unique field handling & the if exists handling is now done before this
  * function is reached in the wrapper - can reduce this code down to assume we
@@ -1474,6 +1529,7 @@ function _civicrm_api3_validate_fields($entity, $action, &$params, $fields, $err
  *   Uniquename of field being checked.
  * @param array $fieldInfo
  *   Array of fields from getfields function.
+ *
  * @throws Exception
  */
 function _civicrm_api3_validate_date(&$params, &$fieldName, &$fieldInfo) {
@@ -1498,8 +1554,9 @@ function _civicrm_api3_validate_date(&$params, &$fieldName, &$fieldInfo) {
 }
 
 /**
- * convert date into BAO friendly date
- * we accept 'whatever strtotime accepts'
+ * Convert date into BAO friendly date.
+ *
+ * We accept 'whatever strtotime accepts'
  *
  * @param string $dateValue
  * @param string $fieldName
@@ -1530,10 +1587,12 @@ function _civicrm_api3_getValidDate($dateValue, $fieldName, $fieldType) {
  *   Uniquename of field being checked.
  * @param array $fieldInfo
  *   Array of fields from getfields function.
+ *
  * @throws \API_Exception
  */
 function _civicrm_api3_validate_constraint(&$fieldValue, &$fieldName, &$fieldInfo) {
-  $dao = new $fieldInfo['FKClassName'];
+  $daoName = $fieldInfo['FKClassName'];
+  $dao = new $daoName();
   $dao->id = $fieldValue;
   $dao->selectAdd();
   $dao->selectAdd('id');
@@ -1549,11 +1608,10 @@ function _civicrm_api3_validate_constraint(&$fieldValue, &$fieldName, &$fieldInf
  *   Params from civicrm_api.
  * @param string $fieldName
  *   Uniquename of field being checked.
- * @param $fieldInfo
- *   Array of fields from getfields function.
+ *
  * @throws Exception
  */
-function _civicrm_api3_validate_uniquekey(&$params, &$fieldName, &$fieldInfo) {
+function _civicrm_api3_validate_unique_key(&$params, &$fieldName) {
   list($fieldValue, $op) = _civicrm_api3_field_value_check($params, $fieldName);
   if (strpos($op, 'NULL') !== FALSE || strpos($op, 'EMPTY') !== FALSE) {
     return;
@@ -1575,7 +1633,7 @@ function _civicrm_api3_validate_uniquekey(&$params, &$fieldName, &$fieldInfo) {
  * Replace the old set of entities (matching some given keys) with a new set of
  * entities (matching the same keys).
  *
- * Note: This will verify that 'values' is present, but it does not directly verify
+ * @note This will verify that 'values' is present, but it does not directly verify
  * any other parameters.
  *
  * @param string $entity
@@ -1583,7 +1641,8 @@ function _civicrm_api3_validate_uniquekey(&$params, &$fieldName, &$fieldInfo) {
  * @param array $params
  *   Params from civicrm_api, including:.
  *   - 'values': an array of records to save
- *   - all other items: keys which identify new/pre-existing records
+ *   - all other items: keys which identify new/pre-existing records.
+ *
  * @return array|int
  */
 function _civicrm_api3_generic_replace($entity, $params) {
@@ -1649,9 +1708,11 @@ function _civicrm_api3_generic_replace($entity, $params) {
 }
 
 /**
+ * Replace base parameters.
+ *
  * @param array $params
  *
- * @return mixed
+ * @return array
  */
 function _civicrm_api3_generic_replace_base_params($params) {
   $baseParams = $params;
@@ -1662,7 +1723,7 @@ function _civicrm_api3_generic_replace_base_params($params) {
 }
 
 /**
- * returns fields allowable by api
+ * Returns fields allowable by api.
  *
  * @param $entity
  *   String Entity to query.
@@ -1673,7 +1734,13 @@ function _civicrm_api3_generic_replace_base_params($params) {
  * @return array
  */
 function _civicrm_api_get_fields($entity, $unique = FALSE, &$params = array()) {
-  $unsetIfEmpty = array('dataPattern', 'headerPattern', 'default', 'export', 'import');
+  $unsetIfEmpty = array(
+    'dataPattern',
+    'headerPattern',
+    'default',
+    'export',
+    'import',
+  );
   $dao = _civicrm_api3_get_DAO($entity);
   if (empty($dao)) {
     return array();
@@ -1716,10 +1783,13 @@ function _civicrm_api_get_fields($entity, $unique = FALSE, &$params = array()) {
 }
 
 /**
- * Return an array of fields for a given entity - this is the same as the BAO function but
- * fields are prefixed with 'custom_' to represent api params
+ * Return an array of fields for a given entity.
+ *
+ * This is the same as the BAO function but fields are prefixed with 'custom_' to represent api params.
+ *
  * @param $entity
  * @param array $params
+ *
  * @return array
  */
 function _civicrm_api_get_custom_fields($entity, &$params) {
@@ -1752,9 +1822,11 @@ function _civicrm_api_get_custom_fields($entity, &$params) {
 }
 
 /**
- * Translate the custom field data_type attribute into a std 'type'
+ * Translate the custom field data_type attribute into a std 'type'.
+ *
  * @param $dataType
- * @return
+ *
+ * @return int
  */
 function _getStandardTypeFromCustomDataType($dataType) {
   $mapping = array(
@@ -1776,10 +1848,12 @@ function _getStandardTypeFromCustomDataType($dataType) {
 
 
 /**
- * Fill params array with alternate (alias) values where a field has an alias and that is filled & the main field isn't
+ * Fill params array with alternate (alias) values where a field has an alias and that is filled & the main field isn't.
+ *
  * If multiple aliases the last takes precedence
  *
  * Function also swaps unique fields for non-unique fields & vice versa.
+ *
  * @param $apiRequest
  * @param $fields
  */
@@ -1809,8 +1883,7 @@ function _civicrm_api3_swap_out_aliases(&$apiRequest, $fields) {
       && $uniqueName
       && $field != $uniqueName
       && array_key_exists($uniqueName, $apiRequest['params'])
-      )
-    {
+    ) {
       $apiRequest['params'][$field] = CRM_Utils_Array::value($values['uniqueName'], $apiRequest['params']);
       // note that it would make sense to unset the original field here but tests need to be in place first
     }
@@ -1820,7 +1893,8 @@ function _civicrm_api3_swap_out_aliases(&$apiRequest, $fields) {
 
 /**
  * Validate integer fields being passed into API.
- * It currently converts the incoming value 'user_contact_id' into the id of the currently logged in user
+ *
+ * It currently converts the incoming value 'user_contact_id' into the id of the currently logged in user.
  *
  * @param array $params
  *   Params from civicrm_api.
@@ -1829,6 +1903,7 @@ function _civicrm_api3_swap_out_aliases(&$apiRequest, $fields) {
  * @param array $fieldInfo
  *   Array of fields from getfields function.
  * @param string $entity
+ *
  * @throws API_Exception
  */
 function _civicrm_api3_validate_integer(&$params, &$fieldName, &$fieldInfo, $entity) {
@@ -1842,8 +1917,9 @@ function _civicrm_api3_validate_integer(&$params, &$fieldName, &$fieldInfo, $ent
     if (!is_numeric($fieldValue) && is_scalar($fieldValue)) {
       $realContactId = _civicrm_api3_resolve_contactID($fieldValue);
       if ('unknown-user' === $realContactId) {
-        throw new API_Exception("\"$fieldName\" \"{$fieldValue}\" cannot be resolved to a contact ID", 2002, array('error_field' => $fieldName,"type"=>"integer"));
-      } elseif (is_numeric($realContactId)) {
+        throw new API_Exception("\"$fieldName\" \"{$fieldValue}\" cannot be resolved to a contact ID", 2002, array('error_field' => $fieldName, "type" => "integer"));
+      }
+      elseif (is_numeric($realContactId)) {
         $fieldValue = $realContactId;
       }
     }
@@ -1859,10 +1935,10 @@ function _civicrm_api3_validate_integer(&$params, &$fieldName, &$fieldInfo, $ent
     }
 
     // Check our field length
-    if(is_string($fieldValue) && !empty($fieldInfo['maxlength']) && strlen($fieldValue) > $fieldInfo['maxlength']
+    if (is_string($fieldValue) && !empty($fieldInfo['maxlength']) && strlen($fieldValue) > $fieldInfo['maxlength']
       ) {
-      throw new API_Exception( $fieldValue . " is " . strlen($fieldValue) . " characters  - longer than $fieldName length" . $fieldInfo['maxlength'] . ' characters',
-        2100, array('field' => $fieldName, "max_length"=>$fieldInfo['maxlength'])
+      throw new API_Exception($fieldValue . " is " . strlen($fieldValue) . " characters  - longer than $fieldName length" . $fieldInfo['maxlength'] . ' characters',
+        2100, array('field' => $fieldName, "max_length" => $fieldInfo['maxlength'])
       );
     }
   }
@@ -1876,14 +1952,15 @@ function _civicrm_api3_validate_integer(&$params, &$fieldName, &$fieldInfo, $ent
 }
 
 /**
- * Determine a contact ID using a string expression
+ * Determine a contact ID using a string expression.
  *
  * @param string $contactIdExpr
  *   E.g. "user_contact_id" or "@user:username".
+ *
  * @return int|NULL|'unknown-user'
  */
 function _civicrm_api3_resolve_contactID($contactIdExpr) {
-  //if value = 'user_contact_id' replace value with logged in user id
+  // If value = 'user_contact_id' replace value with logged in user id.
   if ($contactIdExpr == "user_contact_id") {
     return CRM_Core_Session::getLoggedInContactID();
   }
@@ -1906,7 +1983,8 @@ function _civicrm_api3_resolve_contactID($contactIdExpr) {
 }
 
 /**
- * Validate html (check for scripting attack)
+ * Validate html (check for scripting attack).
+ *
  * @param array $params
  * @param string $fieldName
  * @param array $fieldInfo
@@ -1920,13 +1998,14 @@ function _civicrm_api3_validate_html(&$params, &$fieldName, $fieldInfo) {
   }
   if ($fieldValue) {
     if (!CRM_Utils_Rule::xssString($fieldValue)) {
-      throw new API_Exception('Illegal characters in input (potential scripting attack)', array("field"=>$fieldName,"error_code"=>"xss"));
+      throw new API_Exception('Illegal characters in input (potential scripting attack)', array("field" => $fieldName, "error_code" => "xss"));
     }
   }
 }
 
 /**
  * Validate string fields being passed into API.
+ *
  * @param array $params
  *   Params from civicrm_api.
  * @param string $fieldName
@@ -1934,6 +2013,7 @@ function _civicrm_api3_validate_html(&$params, &$fieldName, $fieldInfo) {
  * @param array $fieldInfo
  *   Array of fields from getfields function.
  * @param string $entity
+ *
  * @throws API_Exception
  * @throws Exception
  */
@@ -1983,12 +2063,13 @@ function _civicrm_api3_validate_string(&$params, &$fieldName, &$fieldInfo, $enti
 }
 
 /**
- * Validate & swap out any pseudoconstants / options
+ * Validate & swap out any pseudoconstants / options.
  *
  * @param mixed $fieldValue
  * @param string $entity : api entity name
  * @param string $fieldName : field name used in api call (not necessarily the canonical name)
  * @param array $fieldInfo : getfields meta-data
+ *
  * @throws \API_Exception
  */
 function _civicrm_api3_api_match_pseudoconstant(&$fieldValue, $entity, $fieldName, $fieldInfo) {
@@ -1996,20 +2077,24 @@ function _civicrm_api3_api_match_pseudoconstant(&$fieldValue, $entity, $fieldNam
 
   if (!$options) {
     if (strtolower($entity) == 'profile' && !empty($fieldInfo['entity'])) {
-      // we need to get the options from the entity the field relates to
+      // We need to get the options from the entity the field relates to.
       $entity = $fieldInfo['entity'];
     }
-    $options = civicrm_api($entity, 'getoptions', array('version' => 3, 'field' => $fieldInfo['name'], 'context' => 'validate'));
+    $options = civicrm_api($entity, 'getoptions', array(
+      'version' => 3,
+      'field' => $fieldInfo['name'],
+      'context' => 'validate',
+    ));
     $options = CRM_Utils_Array::value('values', $options, array());
   }
 
-  // If passed a value-separated string, explode to an array, then re-implode after matching values
+  // If passed a value-separated string, explode to an array, then re-implode after matching values.
   $implode = FALSE;
   if (is_string($fieldValue) && strpos($fieldValue, CRM_Core_DAO::VALUE_SEPARATOR) !== FALSE) {
     $fieldValue = CRM_Utils_Array::explodePadded($fieldValue);
     $implode = TRUE;
   }
-  // If passed multiple options, validate each
+  // If passed multiple options, validate each.
   if (is_array($fieldValue)) {
     foreach ($fieldValue as &$value) {
       if (!is_array($value)) {
@@ -2029,11 +2114,12 @@ function _civicrm_api3_api_match_pseudoconstant(&$fieldValue, $entity, $fieldNam
 }
 
 /**
- * Validate & swap a single option value for a field
+ * Validate & swap a single option value for a field.
+ *
+ * @param string $value field value
+ * @param array $options array of options for this field
+ * @param string $fieldName field name used in api call (not necessarily the canonical name)
  *
- * @param string $value: field value
- * @param array $options: array of options for this field
- * @param string $fieldName: field name used in api call (not necessarily the canonical name)
  * @throws API_Exception
  */
 function _civicrm_api3_api_match_pseudoconstant_value(&$value, $options, $fieldName) {
@@ -2060,7 +2146,7 @@ function _civicrm_api3_api_match_pseudoconstant_value(&$value, $options, $fieldN
 }
 
 /**
- * Returns the canonical name of a field
+ * Returns the canonical name of a field.
  *
  * @param $entity
  *   api entity name (string should already be standardized - no camelCase).
@@ -2100,8 +2186,11 @@ function _civicrm_api3_api_resolve_alias($entity, $fieldName) {
 }
 
 /**
+ * Check if the function is deprecated.
+ *
  * @param string $entity
  * @param array $result
+ *
  * @return string|array|null
  */
 function _civicrm_api3_deprecation_check($entity, $result = array()) {
@@ -2119,12 +2208,15 @@ function _civicrm_api3_deprecation_check($entity, $result = array()) {
 }
 
 /**
+ * Get the actual field value.
+ *
  * In some case $params[$fieldName] holds Array value in this format Array([operator] => [value])
  * So this function returns the actual field value
  *
  * @param array $params
  * @param string $fieldName
- * @return string|int|boolean|date|null
+ *
+ * @return mixed
  */
 function _civicrm_api3_field_value_check(&$params, $fieldName) {
   $fieldValue = CRM_Utils_Array::value($fieldName, $params);