Merge pull request #4923 from colemanw/invoice_id

[civicrm-core.git] / api / v3 / utils.php

diff --git a/api/v3/utils.php b/api/v3/utils.php
index 5305bc789188cec58c4a8c86ebe56148d747aa51..7deeab9744d0c79df0e7ec8631c60651ffc7b110 100644 (file)
--- a/api/v3/utils.php
+++ b/api/v3/utils.php
@@ -135,11 +135,9 @@ function civicrm_api3_verify_mandatory($params, $daoName = NULL, $keys = array()
 
 /**
  *
+ * @param $msg
  * @param array $data
- *
- * @throws API_Exception
  * @return array
- *   <type>
  */
 function civicrm_api3_create_error($msg, $data = array()) {
   $data['is_error'] = 1;
@@ -272,6 +270,8 @@ function civicrm_api3_create_success($values = 1, $params = array(), $entity = N
 
 /**
  * Load the DAO of the entity
+ * @param $entity
+ * @return bool
  */
 function _civicrm_api3_load_DAO($entity) {
   $dao = _civicrm_api3_get_DAO($entity);
@@ -375,7 +375,7 @@ function _civicrm_api3_get_BAO($name) {
 
 /**
  *  Recursive function to explode value-separated strings into arrays
- *
+ * @param $values
  */
 function _civicrm_api3_separate_values(&$values) {
   $sp = CRM_Core_DAO::VALUE_SEPARATOR;
@@ -439,7 +439,7 @@ function _civicrm_api3_store_values(&$fields, &$params, &$values) {
  *  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
@@ -542,8 +542,7 @@ function _civicrm_api3_get_using_query_object($entity, $params, $additional_opti
  * @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');
@@ -825,6 +824,9 @@ 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
  * returns unique fields as keys by default but if set but can return by DB fields
+ * @param $bao
+ * @param bool $unique
+ * @return
  */
 function _civicrm_api3_build_fields_array(&$bao, $unique = TRUE) {
   $fields = $bao->fields();
@@ -846,7 +848,7 @@ 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
  * returns unique fields as keys by default but if set but can return by DB fields
- * @param CRM_Core_BAO $bao
+ * @param CRM_Core_DAO $bao
  *
  * @return mixed
  */
@@ -870,8 +872,6 @@ function _civicrm_api3_get_unique_name_array(&$bao) {
  *
  * @return array
  *
- * @static void
- * @access public
  */
 function _civicrm_api3_dao_to_array($dao, $params = NULL, $uniqueFields = TRUE, $entity = "", $autoFind = TRUE) {
   $result = array();
@@ -943,8 +943,6 @@ function _civicrm_api3_custom_fields_are_required($entity, $params) {
  * @param array|bool $uniqueFields
  *
  * @return array
- * @static void
- * @access public
  */
 function _civicrm_api3_object_to_array(&$dao, &$values, $uniqueFields = FALSE) {
 
@@ -958,6 +956,9 @@ function _civicrm_api3_object_to_array(&$dao, &$values, $uniqueFields = FALSE) {
 
 /**
  * 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) {
   return _civicrm_api3_object_to_array($dao, $values, TRUE);
@@ -1133,7 +1134,6 @@ function formatCheckBoxField(&$checkboxFieldValue, $customFieldLabel, $entity) {
  * @return bool
  *   Sshould 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
@@ -1446,7 +1446,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);
       }
     }
   }
@@ -1519,13 +1519,12 @@ function _civicrm_api3_getValidDate($dateValue, $fieldName, $fieldType) {
 /**
  * Validate foreign constraint fields being passed into API.
  *
- * @param array $params
- *   Params from civicrm_api.
+ * @param mixed $fieldValue
  * @param string $fieldName
  *   Uniquename of field being checked.
  * @param array $fieldInfo
  *   Array of fields from getfields function.
- * @throws Exception
+ * @throws \API_Exception
  */
 function _civicrm_api3_validate_constraint(&$fieldValue, &$fieldName, &$fieldInfo) {
   $dao = new $fieldInfo['FKClassName'];
@@ -1533,7 +1532,7 @@ function _civicrm_api3_validate_constraint(&$fieldValue, &$fieldName, &$fieldInf
   $dao->selectAdd();
   $dao->selectAdd('id');
   if (!$dao->find()) {
-    throw new Exception("$fieldName is not valid : " . $fieldValue);
+    throw new API_Exception("$fieldName is not valid : " . $fieldValue);
   }
 }
 
@@ -1544,11 +1543,9 @@ 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;
@@ -1713,6 +1710,9 @@ 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
+ * @param $entity
+ * @param array $params
+ * @return array
  */
 function _civicrm_api_get_custom_fields($entity, &$params) {
   $entity = _civicrm_api_get_camel_name($entity);
@@ -1742,8 +1742,11 @@ function _civicrm_api_get_custom_fields($entity, &$params) {
   }
   return $ret;
 }
+
 /**
  * Translate the custom field data_type attribute into a std 'type'
+ * @param $dataType
+ * @return
  */
 function _getStandardTypeFromCustomDataType($dataType) {
   $mapping = array(
@@ -1769,6 +1772,8 @@ function _getStandardTypeFromCustomDataType($dataType) {
  * If multiple aliases the last takes precedence
  *
  * Function also swaps unique fields for non-unique fields & vice versa.
+ * @param $apiRequest
+ * @param $fields
  */
 function _civicrm_api3_swap_out_aliases(&$apiRequest, $fields) {
   foreach ($fields as $field => $values) {
@@ -1972,10 +1977,11 @@ function _civicrm_api3_validate_string(&$params, &$fieldName, &$fieldInfo, $enti
 /**
  * Validate & swap out any pseudoconstants / options
  *
- * @param array $params: api parameters
- * @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
+ * @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) {
   $options = CRM_Utils_Array::value('options', $fieldInfo);