5 * Get information about fields for a given api request. Getfields information
6 * is used for documentation, validation, default setting
7 * We first query the scheme using the $dao->fields function & then augment
8 * that information by calling the _spec functions that apply to the relevant function
9 * Note that we use 'unique' field names as described in the xml/schema files
10 * for get requests & just field name for create. This is because some get functions
11 * access multiple objects e.g. contact api accesses is_deleted from the activity
12 * table & from the contact table
14 * @param array $apiRequest api request as an array. Keys are
18 * - function: callback (mixed)
19 * - params: array, varies
20 * @return array API success object
22 function civicrm_api3_generic_getfields($apiRequest) {
23 static $results = array();
24 if ((CRM_Utils_Array
::value('cache_clear', $apiRequest['params']))) {
26 // we will also clear pseudoconstants here - should potentially be moved to relevant BAO classes
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 $apiOptions = CRM_Utils_Array
::value('options', $apiRequest['params'], array());
42 if ($action == 'getvalue' ||
$action == 'getvalue' ||
$action == 'getcount') {
49 // determines whether to use unique field names - seem comment block above
51 if (isset($results[$entity . $subentity]) && CRM_Utils_Array
::value($action, $results[$entity])
52 && empty($apiOptions)) {
53 return $results[$entity . $subentity][$action];
55 // defaults based on data model and API policy
58 $values = _civicrm_api_get_fields($entity, false, $apiRequest['params']);
59 $results[$entity][$action] = civicrm_api3_create_success($values,
60 $apiRequest['params'], $entity, 'getfields'
62 return $results[$entity][$action];
65 return civicrm_api3_create_success(_civicrm_api_get_fields($apiRequest['entity']));
71 $metadata = _civicrm_api_get_fields($apiRequest['entity'], $unique, $apiRequest['params']);
72 if (empty($metadata['id']) && !empty($metadata[$apiRequest['entity'] . '_id'])) {
73 $metadata['id'] = $metadata[$lcase_entity . '_id'];
74 $metadata['id']['api.aliases'] = array($lcase_entity . '_id');
75 unset($metadata[$lcase_entity . '_id']);
81 'id' => array('title' => 'Unique Identifier',
83 'api.aliases' => array($lcase_entity . '_id'),
89 'field' => array('title' => 'Field to retrieve options for',
94 // oddballs are on their own
98 // find any supplemental information
99 $hypApiRequest = array('entity' => $apiRequest['entity'], 'action' => $action, 'version' => $apiRequest['version']);
100 $hypApiRequest +
= _civicrm_api_resolve($hypApiRequest);
101 $helper = '_' . $hypApiRequest['function'] . '_spec';
102 if (function_exists($helper)) {
107 $fieldsToResolve = CRM_Utils_Array
::value('get_options', $apiOptions, array());
109 foreach ($metadata as $fieldname => $fieldSpec) {
110 _civicrm_api3_generic_get_metadata_options($metadata, $fieldname, $fieldSpec, $fieldsToResolve);
113 $results[$entity][$action] = civicrm_api3_create_success($metadata, $apiRequest['params'], NULL, 'getfields');
114 return $results[$entity][$action];
118 * API return function to reformat results as count
120 * @param array $apiRequest api request as an array. Keys are
122 * @return integer count of results
124 function civicrm_api3_generic_getcount($apiRequest) {
125 $result = civicrm_api($apiRequest['entity'], 'get', $apiRequest['params']);
126 return $result['count'];
130 * API return function to reformat results as single result
132 * @param array $apiRequest api request as an array. Keys are
134 * @return integer count of results
136 function civicrm_api3_generic_getsingle($apiRequest) {
137 // so the first entity is always result['values'][0]
138 $apiRequest['params']['sequential'] = 1;
139 $result = civicrm_api($apiRequest['entity'], 'get', $apiRequest['params']);
140 if ($result['is_error'] !== 0) {
143 if ($result['count'] === 1) {
144 return $result['values'][0];
146 if ($result['count'] !== 1) {
147 return civicrm_api3_create_error("Expected one " . $apiRequest['entity'] . " but found " . $result['count'], array('count' => $result['count']));
149 return civicrm_api3_create_error("Undefined behavior");
153 * API return function to reformat results as single value
155 * @param array $apiRequest api request as an array. Keys are
157 * @return integer count of results
159 function civicrm_api3_generic_getvalue($apiRequest) {
160 $apiRequest['params']['sequential'] = 1;
161 $result = civicrm_api($apiRequest['entity'], 'get', $apiRequest['params']);
162 if ($result['is_error'] !== 0) {
165 if ($result['count'] !== 1) {
166 $result = civicrm_api3_create_error("Expected one " . $apiRequest['entity'] . " but found " . $result['count'], array('count' => $result['count']));
170 // we only take "return=" as valid options
171 if (CRM_Utils_Array
::value('return', $apiRequest['params'])) {
172 if (!isset($result['values'][0][$apiRequest['params']['return']])) {
173 return civicrm_api3_create_error("field " . $apiRequest['params']['return'] . " unset or not existing", array('invalid_field' => $apiRequest['params']['return']));
176 return $result['values'][0][$apiRequest['params']['return']];
179 return civicrm_api3_create_error("missing param return=field you want to read the value of", array('error_type' => 'mandatory_missing', 'missing_param' => 'return'));
183 * API wrapper for replace function
185 * @param array $apiRequest api request as an array. Keys are
187 * @return integer count of results
189 function civicrm_api3_generic_replace($apiRequest) {
190 return _civicrm_api3_generic_replace($apiRequest['entity'], $apiRequest['params']);
194 * API wrapper for getoptions function
196 * @param array $apiRequest api request as an array. Keys are
198 * @return array of results
200 function civicrm_api3_generic_getoptions($apiRequest) {
201 $field = $apiRequest['params']['field'];
202 $getFieldsArray = array(
204 'action' => 'create',
205 'options' => array('get_options' => $field),
207 // First try to retrieve the options from getfields
208 $result = civicrm_api($apiRequest['entity'], 'getfields', $getFieldsArray);
209 if (!isset($result['values'][$field]) && isset($result['values'][$field . '_id'])) {
210 $field = $field . '_id';
212 if (!empty($result['values'][$field]['options'])) {
213 return civicrm_api3_create_success($result['values'][$field]['options']);
215 // If that didn't work, try the constant api
216 if (substr($field, -3) == '_id') {
217 // Convert foo_id to just plain foo
218 $field = substr($field, 0, -3);
220 $params = array('name' => _civicrm_api_get_camel_name($field));
221 $entity = strtolower($apiRequest['entity']);
222 if ($entity == 'contribution') {
223 $params['class'] = 'CRM_Contribute_PseudoConstant';
225 elseif ($entity == 'event' ||
$entity == 'participant') {
226 $params['class'] = 'CRM_Event_PseudoConstant';
228 elseif (strpos($entity, 'membership') === 0) {
229 $params['class'] = 'CRM_Member_PseudoConstant';
231 require_once 'api/v3/Constant.php';
232 return civicrm_api3_constant_get($params);
236 * Function fills the 'options' array on the metadata returned by getfields if
237 * 1) the param option 'get_options' is defined - e.g. $params['options']['get_options'] => array('custom_1)
238 * (this is passed in as the $fieldsToResolve array)
239 * 2) the field is a pseudoconstant and is NOT an FK
240 * - the reason for this is that checking / transformation is done on pseudoconstants but
241 * - if the field is an FK then mysql will enforce the data quality (& we have handling on failure)
242 * @todo - if may be we should define a 'resolve' key on the psuedoconstant for when these rules are not fine enough
243 * 3) if there is an 'enum' then it is split up into the relevant options
245 * This function is only split out for the purpose of code clarity / comment block documentation
246 * @param array $metadata the array of metadata that will form the result of the getfields function
247 * @param string $fieldname field currently being processed
248 * @param array $fieldSpec metadata for that field
249 * @param array $fieldsToResolve anny field resolutions specifically requested
251 function _civicrm_api3_generic_get_metadata_options(&$metadata, $fieldname, $fieldSpec, $fieldsToResolve){
252 if (array_key_exists('enumValues', $fieldSpec)) {
253 // use of a space after the comma is inconsistent in xml
254 $enumStr = str_replace(', ', ',', $fieldSpec['enumValues']);
255 $metadata[$fieldname]['options'] = explode(',', $enumStr);
259 if(empty($fieldSpec['pseudoconstant'])){
262 elseif(!empty($fieldSpec['FKClassName']) && !in_array($fieldname, $fieldsToResolve)){
265 if(substr($fieldname, -3) == '_id'){
266 $metadata[$fieldname]['api.aliases'][] = substr($fieldname, 0, -3);
269 $pseudoParams = $fieldSpec['pseudoconstant'];
270 $pseudoParams['version'] = 3;
271 $options = civicrm_api('constant', 'get', $pseudoParams);
272 if (is_array(CRM_Utils_Array
::value('values', $options))) {
273 $metadata[$fieldname]['options'] = $options['values'];