4 * Get information about fields for a given api request. Getfields information
5 * is used for documentation, validation, default setting
6 * We first query the scheme using the $dao->fields function & then augment
7 * that information by calling the _spec functions that apply to the relevant function
8 * Note that we use 'unique' field names as described in the xml/schema files
9 * for get requests & just field name for create. This is because some get functions
10 * access multiple objects e.g. contact api accesses is_deleted from the activity
11 * table & from the contact table
13 * @param array $apiRequest api request as an array. Keys are
17 * - function: callback (mixed)
18 * - params: array, varies
19 * @return array API success object
21 function civicrm_api3_generic_getfields($apiRequest) {
22 static $results = array();
23 if ((CRM_Utils_Array
::value('cache_clear', $apiRequest['params']))) {
25 // we will also clear pseudoconstants here - should potentially be moved to relevant BAO classes
26 CRM_Core_PseudoConstant
::flush();
27 if(!empty($apiRequest['params']['fieldname'])){
28 CRM_Utils_PseudoConstant
::flushConstant($apiRequest['params']['fieldname']);
30 if(!empty($apiRequest['params']['option_group_id'])){
31 $optionGroupName = civicrm_api('option_group', 'getvalue', array('version' => 3, 'id' => $apiRequest['params']['option_group_id'], 'return' => 'name') );
32 if(is_string($optionGroupName)){
33 CRM_Utils_PseudoConstant
::flushConstant(_civicrm_api_get_camel_name($optionGroupName));
37 $entity = _civicrm_api_get_camel_name($apiRequest['entity']);
38 $lcase_entity = _civicrm_api_get_entity_name_from_camel($entity);
39 $subentity = CRM_Utils_Array
::value('contact_type', $apiRequest['params']);
40 $action = strtolower(CRM_Utils_Array
::value('action', $apiRequest['params']));
41 $sequential = empty($apiRequest['params']) ?
0 : 1;
42 $apiOptions = CRM_Utils_Array
::value('options', $apiRequest['params'], array());
43 if (!$action ||
$action == 'getvalue' ||
$action == 'getcount') {
46 // determines whether to use unique field names - seem comment block above
48 if (empty($apiOptions) && isset($results[$entity . $subentity]) && isset($action, $results[$entity . $subentity])
49 && isset($action, $results[$entity . $subentity][$sequential])) {
50 return $results[$entity . $subentity][$action][$sequential];
52 // defaults based on data model and API policy
55 $values = _civicrm_api_get_fields($entity, false, $apiRequest['params']);
56 return civicrm_api3_create_success($values, $apiRequest['params'], $entity, 'getfields');
62 $metadata = _civicrm_api_get_fields($apiRequest['entity'], $unique, $apiRequest['params']);
63 if (empty($metadata['id'])){
64 // if id is not set we will set it eg. 'id' from 'case_id', case_id will be an alias
65 if(!empty($metadata[strtolower($apiRequest['entity']) . '_id'])) {
66 $metadata['id'] = $metadata[$lcase_entity . '_id'];
67 unset($metadata[$lcase_entity . '_id']);
68 $metadata['id']['api.aliases'] = array($lcase_entity . '_id');
72 // really the preference would be to set the unique name in the xml
73 // question is which is a less risky fix this close to a release - setting in xml for the known failure
74 // (note) or setting for all api where fields is returning 'id' & we want to accept 'note_id' @ the api layer
75 // nb we don't officially accept note_id anyway - rationale here is more about centralising a now-tested
77 $metadata['id']['api.aliases'] = array($lcase_entity . '_id');
83 'id' => array('title' => 'Unique Identifier',
85 'api.aliases' => array($lcase_entity . '_id'),
86 'type' => CRM_Utils_Type
::T_INT
,
93 'title' => 'Field to retrieve options for',
97 'title' => 'Context string',
102 // oddballs are on their own
106 // find any supplemental information
107 $hypApiRequest = array('entity' => $apiRequest['entity'], 'action' => $action, 'version' => $apiRequest['version']);
108 $hypApiRequest +
= _civicrm_api_resolve($hypApiRequest);
109 $helper = '_' . $hypApiRequest['function'] . '_spec';
110 if (function_exists($helper)) {
112 $helper($metadata, $apiRequest);
115 $fieldsToResolve = (array) CRM_Utils_Array
::value('get_options', $apiOptions, array());
117 foreach ($metadata as $fieldname => $fieldSpec) {
118 _civicrm_api3_generic_get_metadata_options($metadata, $apiRequest['entity'], $fieldname, $fieldSpec, $fieldsToResolve);
121 $results[$entity][$action][$sequential] = civicrm_api3_create_success($metadata, $apiRequest['params'], NULL, 'getfields');
122 return $results[$entity][$action][$sequential];
126 * API return function to reformat results as count
128 * @param array $apiRequest api request as an array. Keys are
130 * @return integer count of results
132 function civicrm_api3_generic_getcount($apiRequest) {
133 $apiRequest['params']['options']['is_count'] = TRUE;
134 $result = civicrm_api($apiRequest['entity'], 'get', $apiRequest['params']);
135 if(is_numeric (CRM_Utils_Array
::value('values', $result))) {
136 return (int) $result['values'];
138 if(!isset($result['count'])) {
139 throw new API_Exception(ts('Unexpected result from getcount') . print_r($result, TRUE));
141 return $result['count'];
145 * API return function to reformat results as single result
147 * @param array $apiRequest api request as an array. Keys are
149 * @return integer count of results
151 function civicrm_api3_generic_getsingle($apiRequest) {
152 // so the first entity is always result['values'][0]
153 $apiRequest['params']['sequential'] = 1;
154 $result = civicrm_api($apiRequest['entity'], 'get', $apiRequest['params']);
155 if ($result['is_error'] !== 0) {
158 if ($result['count'] === 1) {
159 return $result['values'][0];
161 if ($result['count'] !== 1) {
162 return civicrm_api3_create_error("Expected one " . $apiRequest['entity'] . " but found " . $result['count'], array('count' => $result['count']));
164 return civicrm_api3_create_error("Undefined behavior");
168 * API return function to reformat results as single value
170 * @param array $apiRequest api request as an array. Keys are
172 * @return integer count of results
174 function civicrm_api3_generic_getvalue($apiRequest) {
175 $apiRequest['params']['sequential'] = 1;
176 $result = civicrm_api($apiRequest['entity'], 'get', $apiRequest['params']);
177 if ($result['is_error'] !== 0) {
180 if ($result['count'] !== 1) {
181 $result = civicrm_api3_create_error("Expected one " . $apiRequest['entity'] . " but found " . $result['count'], array('count' => $result['count']));
185 // we only take "return=" as valid options
186 if (!empty($apiRequest['params']['return'])) {
187 if (!isset($result['values'][0][$apiRequest['params']['return']])) {
188 return civicrm_api3_create_error("field " . $apiRequest['params']['return'] . " unset or not existing", array('invalid_field' => $apiRequest['params']['return']));
191 return $result['values'][0][$apiRequest['params']['return']];
194 return civicrm_api3_create_error("missing param return=field you want to read the value of", array('error_type' => 'mandatory_missing', 'missing_param' => 'return'));
198 * API wrapper for replace function
200 * @param array $apiRequest api request as an array. Keys are
202 * @return integer count of results
204 function civicrm_api3_generic_replace($apiRequest) {
205 return _civicrm_api3_generic_replace($apiRequest['entity'], $apiRequest['params']);
209 * API wrapper for getoptions function
211 * @param array $apiRequest api request as an array.
213 * @return array of results
215 function civicrm_api3_generic_getoptions($apiRequest) {
217 $fieldName = _civicrm_api3_api_resolve_alias($apiRequest['entity'], $apiRequest['params']['field']);
219 return civicrm_api3_create_error("The field '{$apiRequest['params']['field']}' doesn't exist.");
221 // Validate 'context' from params
222 $context = CRM_Utils_Array
::value('context', $apiRequest['params']);
223 CRM_Core_DAO
::buildOptionsContext($context);
224 unset($apiRequest['params']['context'], $apiRequest['params']['field']);
226 $baoName = _civicrm_api3_get_BAO($apiRequest['entity']);
227 $options = $output = $baoName::buildOptions($fieldName, $context, $apiRequest['params']);
228 if ($options === FALSE) {
229 return civicrm_api3_create_error("The field '{$fieldName}' has no associated option list.");
231 // Support 'sequential' output as a non-associative array
232 if (!empty($apiRequest['params']['sequential'])) {
234 foreach ($options as $key => $val) {
235 $output[] = array('key' => $key, 'value' => $val);
238 return civicrm_api3_create_success($output, $apiRequest['params'], $apiRequest['entity'], 'getoptions');
242 * Function fills the 'options' array on the metadata returned by getfields if
243 * 1) the param option 'get_options' is defined - e.g. $params['options']['get_options'] => array('custom_1)
244 * (this is passed in as the $fieldsToResolve array)
245 * 2) the field is a pseudoconstant and is NOT an FK
246 * - the reason for this is that checking / transformation is done on pseudoconstants but
247 * - if the field is an FK then mysql will enforce the data quality (& we have handling on failure)
248 * @todo - if may be we should define a 'resolve' key on the psuedoconstant for when these rules are not fine enough
250 * This function is only split out for the purpose of code clarity / comment block documentation
251 * @param array $metadata the array of metadata that will form the result of the getfields function
252 * @param string $fieldname field currently being processed
253 * @param array $fieldSpec metadata for that field
254 * @param array $fieldsToResolve anny field resolutions specifically requested
256 function _civicrm_api3_generic_get_metadata_options(&$metadata, $entity, $fieldname, $fieldSpec, $fieldsToResolve){
257 if (empty($fieldSpec['pseudoconstant'])) {
261 if (!empty($metadata[$fieldname]['options']) ||
(!in_array($fieldname, $fieldsToResolve) && !in_array('all', $fieldsToResolve))) {
265 $options = civicrm_api($entity, 'getoptions', array('version' => 3, 'field' => $fieldname));
266 if (is_array(CRM_Utils_Array
::value('values', $options))) {
267 $metadata[$fieldname]['options'] = $options['values'];