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 if(!empty($apiRequest['params']['fieldname'])){
27 CRM_Utils_PseudoConstant
::flushConstant($apiRequest['params']['fieldname']);
29 if(!empty($apiRequest['params']['option_group_id'])){
30 $optionGroupName = civicrm_api('option_group', 'getvalue', array('version' => 3, 'id' => $apiRequest['params']['option_group_id'], 'return' => 'name') );
31 if(is_string($optionGroupName)){
32 CRM_Utils_PseudoConstant
::flushConstant(_civicrm_api_get_camel_name($optionGroupName));
36 $entity = _civicrm_api_get_camel_name($apiRequest['entity']);
37 $lcase_entity = _civicrm_api_get_entity_name_from_camel($entity);
38 $subentity = CRM_Utils_Array
::value('contact_type', $apiRequest['params']);
39 $action = strtolower(CRM_Utils_Array
::value('action', $apiRequest['params']));
40 $apiOptions = CRM_Utils_Array
::value('options', $apiRequest['params'], array());
41 if ($action == 'getvalue' ||
$action == 'getvalue' ||
$action == 'getcount') {
48 // determines whether to use unique field names - seem comment block above
50 if (isset($results[$entity . $subentity]) && CRM_Utils_Array
::value($action, $results[$entity])
51 && empty($apiOptions)) {
52 return $results[$entity . $subentity][$action];
54 // defaults based on data model and API policy
57 $values = _civicrm_api_get_fields($entity, false, $apiRequest['params']);
58 $results[$entity][$action] = civicrm_api3_create_success($values,
59 $apiRequest['params'], $entity, 'getfields'
61 return $results[$entity][$action];
64 return civicrm_api3_create_success(_civicrm_api_get_fields($apiRequest['entity']));
70 $metadata = _civicrm_api_get_fields($apiRequest['entity'], $unique, $apiRequest['params']);
71 if (empty($metadata['id'])){
72 // if id is not set we will set it eg. 'id' from 'case_id', case_id will be an alias
73 if(!empty($metadata[strtolower($apiRequest['entity']) . '_id'])) {
74 $metadata['id'] = $metadata[$lcase_entity . '_id'];
75 unset($metadata[$lcase_entity . '_id']);
76 $metadata['id']['api.aliases'] = array($lcase_entity . '_id');
80 // really the preference would be to set the unique name in the xml
81 // question is which is a less risky fix this close to a release - setting in xml for the known failure
82 // (note) or setting for all api where fields is returning 'id' & we want to accept 'note_id' @ the api layer
83 // nb we don't officially accept note_id anyway - rationale here is more about centralising a now-tested
85 $metadata['id']['api.aliases'] = array($lcase_entity . '_id');
92 'id' => array('title' => 'Unique Identifier',
94 'api.aliases' => array($lcase_entity . '_id'),
100 'field' => array('title' => 'Field to retrieve options for',
105 // oddballs are on their own
109 // find any supplemental information
110 $hypApiRequest = array('entity' => $apiRequest['entity'], 'action' => $action, 'version' => $apiRequest['version']);
111 $hypApiRequest +
= _civicrm_api_resolve($hypApiRequest);
112 $helper = '_' . $hypApiRequest['function'] . '_spec';
113 if (function_exists($helper)) {
118 $fieldsToResolve = CRM_Utils_Array
::value('get_options', $apiOptions, array());
120 foreach ($metadata as $fieldname => $fieldSpec) {
121 _civicrm_api3_generic_get_metadata_options($metadata, $fieldname, $fieldSpec, $fieldsToResolve);
124 $results[$entity][$action] = civicrm_api3_create_success($metadata, $apiRequest['params'], NULL, 'getfields');
125 return $results[$entity][$action];
129 * API return function to reformat results as count
131 * @param array $apiRequest api request as an array. Keys are
133 * @return integer count of results
135 function civicrm_api3_generic_getcount($apiRequest) {
136 $result = civicrm_api($apiRequest['entity'], 'get', $apiRequest['params']);
137 return $result['count'];
141 * API return function to reformat results as single result
143 * @param array $apiRequest api request as an array. Keys are
145 * @return integer count of results
147 function civicrm_api3_generic_getsingle($apiRequest) {
148 // so the first entity is always result['values'][0]
149 $apiRequest['params']['sequential'] = 1;
150 $result = civicrm_api($apiRequest['entity'], 'get', $apiRequest['params']);
151 if ($result['is_error'] !== 0) {
154 if ($result['count'] === 1) {
155 return $result['values'][0];
157 if ($result['count'] !== 1) {
158 return civicrm_api3_create_error("Expected one " . $apiRequest['entity'] . " but found " . $result['count'], array('count' => $result['count']));
160 return civicrm_api3_create_error("Undefined behavior");
164 * API return function to reformat results as single value
166 * @param array $apiRequest api request as an array. Keys are
168 * @return integer count of results
170 function civicrm_api3_generic_getvalue($apiRequest) {
171 $apiRequest['params']['sequential'] = 1;
172 $result = civicrm_api($apiRequest['entity'], 'get', $apiRequest['params']);
173 if ($result['is_error'] !== 0) {
176 if ($result['count'] !== 1) {
177 $result = civicrm_api3_create_error("Expected one " . $apiRequest['entity'] . " but found " . $result['count'], array('count' => $result['count']));
181 // we only take "return=" as valid options
182 if (CRM_Utils_Array
::value('return', $apiRequest['params'])) {
183 if (!isset($result['values'][0][$apiRequest['params']['return']])) {
184 return civicrm_api3_create_error("field " . $apiRequest['params']['return'] . " unset or not existing", array('invalid_field' => $apiRequest['params']['return']));
187 return $result['values'][0][$apiRequest['params']['return']];
190 return civicrm_api3_create_error("missing param return=field you want to read the value of", array('error_type' => 'mandatory_missing', 'missing_param' => 'return'));
194 * API wrapper for replace function
196 * @param array $apiRequest api request as an array. Keys are
198 * @return integer count of results
200 function civicrm_api3_generic_replace($apiRequest) {
201 return _civicrm_api3_generic_replace($apiRequest['entity'], $apiRequest['params']);
205 * API wrapper for getoptions function
207 * @param array $apiRequest api request as an array. Keys are
209 * @return array of results
211 function civicrm_api3_generic_getoptions($apiRequest) {
212 $field = $apiRequest['params']['field'];
213 $getFieldsArray = array(
215 'action' => 'create',
216 'options' => array('get_options' => $field),
218 // First try to retrieve the options from getfields
219 $result = civicrm_api($apiRequest['entity'], 'getfields', $getFieldsArray);
220 if (!isset($result['values'][$field]) && isset($result['values'][$field . '_id'])) {
221 $field = $field . '_id';
223 if (!empty($result['values'][$field]['options'])) {
224 return civicrm_api3_create_success($result['values'][$field]['options']);
226 // If that didn't work, try the constant api
227 if (substr($field, -3) == '_id') {
228 // Convert foo_id to just plain foo
229 $field = substr($field, 0, -3);
231 $params = array('name' => _civicrm_api_get_camel_name($field));
232 $entity = strtolower($apiRequest['entity']);
233 if ($entity == 'contribution') {
234 $params['class'] = 'CRM_Contribute_PseudoConstant';
236 elseif ($entity == 'event' ||
$entity == 'participant') {
237 $params['class'] = 'CRM_Event_PseudoConstant';
239 elseif (strpos($entity, 'membership') === 0) {
240 $params['class'] = 'CRM_Member_PseudoConstant';
242 require_once 'api/v3/Constant.php';
243 return civicrm_api3_constant_get($params);
247 * Function fills the 'options' array on the metadata returned by getfields if
248 * 1) the param option 'get_options' is defined - e.g. $params['options']['get_options'] => array('custom_1)
249 * (this is passed in as the $fieldsToResolve array)
250 * 2) the field is a pseudoconstant and is NOT an FK
251 * - the reason for this is that checking / transformation is done on pseudoconstants but
252 * - if the field is an FK then mysql will enforce the data quality (& we have handling on failure)
253 * @todo - if may be we should define a 'resolve' key on the psuedoconstant for when these rules are not fine enough
254 * 3) if there is an 'enum' then it is split up into the relevant options
256 * This function is only split out for the purpose of code clarity / comment block documentation
257 * @param array $metadata the array of metadata that will form the result of the getfields function
258 * @param string $fieldname field currently being processed
259 * @param array $fieldSpec metadata for that field
260 * @param array $fieldsToResolve anny field resolutions specifically requested
262 function _civicrm_api3_generic_get_metadata_options(&$metadata, $fieldname, $fieldSpec, $fieldsToResolve){
263 if (array_key_exists('enumValues', $fieldSpec)) {
264 // use of a space after the comma is inconsistent in xml
265 $enumStr = str_replace(', ', ',', $fieldSpec['enumValues']);
266 $metadata[$fieldname]['options'] = explode(',', $enumStr);
270 if(empty($fieldSpec['pseudoconstant'])){
273 elseif(!empty($fieldSpec['FKClassName']) && !in_array($fieldname, $fieldsToResolve)){
276 if(substr($fieldname, -3) == '_id'){
277 $metadata[$fieldname]['api.aliases'][] = substr($fieldname, 0, -3);
280 $pseudoParams = $fieldSpec['pseudoconstant'];
281 $pseudoParams['version'] = 3;
282 $options = civicrm_api('constant', 'get', $pseudoParams);
283 if (is_array(CRM_Utils_Array
::value('values', $options))) {
284 $metadata[$fieldname]['options'] = $options['values'];