INFRA-132 - Batch 14 (g)
[civicrm-core.git] / api / v3 / Generic.php
CommitLineData
6a488035 1<?php
6a488035
TO
2
3/**
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
12 *
cf470720
TO
13 * @param array $apiRequest
14 * Api request as an array. Keys are.
16b10e64
CW
15 * - entity: string
16 * - action: string
17 * - version: string
18 * - function: callback (mixed)
19 * - params: array, varies
a6c01b45 20 * @return array
72b3a70c 21 * API success object
6a488035
TO
22 */
23function civicrm_api3_generic_getfields($apiRequest) {
24 static $results = array();
25 if ((CRM_Utils_Array::value('cache_clear', $apiRequest['params']))) {
26 $results = array();
27 // we will also clear pseudoconstants here - should potentially be moved to relevant BAO classes
37547b77 28 CRM_Core_PseudoConstant::flush();
9b873358 29 if (!empty($apiRequest['params']['fieldname'])) {
6a488035
TO
30 CRM_Utils_PseudoConstant::flushConstant($apiRequest['params']['fieldname']);
31 }
9b873358 32 if (!empty($apiRequest['params']['option_group_id'])) {
481a74f4 33 $optionGroupName = civicrm_api('option_group', 'getvalue', array('version' => 3, 'id' => $apiRequest['params']['option_group_id'], 'return' => 'name'));
9b873358 34 if (is_string($optionGroupName)) {
6a488035
TO
35 CRM_Utils_PseudoConstant::flushConstant(_civicrm_api_get_camel_name($optionGroupName));
36 }
37 }
38 }
39 $entity = _civicrm_api_get_camel_name($apiRequest['entity']);
40 $lcase_entity = _civicrm_api_get_entity_name_from_camel($entity);
41 $subentity = CRM_Utils_Array::value('contact_type', $apiRequest['params']);
42 $action = strtolower(CRM_Utils_Array::value('action', $apiRequest['params']));
ceccbc35 43 $sequential = empty($apiRequest['params']) ? 0 : 1;
6a488035 44 $apiOptions = CRM_Utils_Array::value('options', $apiRequest['params'], array());
54df0f0c 45 if (!$action || $action == 'getvalue' || $action == 'getcount') {
6a488035
TO
46 $action = 'get';
47 }
6a488035
TO
48 // determines whether to use unique field names - seem comment block above
49 $unique = TRUE;
ceccbc35 50 if (empty($apiOptions) && isset($results[$entity . $subentity]) && isset($action, $results[$entity . $subentity])
51 && isset($action, $results[$entity . $subentity][$sequential])) {
52 return $results[$entity . $subentity][$action][$sequential];
6a488035
TO
53 }
54 // defaults based on data model and API policy
55 switch ($action) {
56 case 'getfields':
9c8096cb 57 $values = _civicrm_api_get_fields($entity, FALSE, $apiRequest['params']);
f2b53f26 58 return civicrm_api3_create_success($values, $apiRequest['params'], $entity, 'getfields');
ea100cb5 59
6a488035
TO
60 case 'create':
61 case 'update':
62 case 'replace':
63 $unique = FALSE;
64 case 'get':
2b6e1174
CW
65 case 'getsingle':
66 case 'getcount':
6a488035 67 $metadata = _civicrm_api_get_fields($apiRequest['entity'], $unique, $apiRequest['params']);
9b873358 68 if (empty($metadata['id'])) {
9ec90e57 69 // if id is not set we will set it eg. 'id' from 'case_id', case_id will be an alias
22e263ad 70 if (!empty($metadata[strtolower($apiRequest['entity']) . '_id'])) {
9ec90e57 71 $metadata['id'] = $metadata[$lcase_entity . '_id'];
72 unset($metadata[$lcase_entity . '_id']);
73 $metadata['id']['api.aliases'] = array($lcase_entity . '_id');
74 }
75 }
92e4c2a5 76 else {
9ec90e57 77 // really the preference would be to set the unique name in the xml
78 // question is which is a less risky fix this close to a release - setting in xml for the known failure
79 // (note) or setting for all api where fields is returning 'id' & we want to accept 'note_id' @ the api layer
80 // nb we don't officially accept note_id anyway - rationale here is more about centralising a now-tested
81 // inconsistency
6a488035 82 $metadata['id']['api.aliases'] = array($lcase_entity . '_id');
6a488035
TO
83 }
84 break;
85
86 case 'delete':
87 $metadata = array(
3a8e9315
CW
88 'id' => array(
89 'title' => $entity . ' ID',
90 'name' => 'id',
6a488035
TO
91 'api.required' => 1,
92 'api.aliases' => array($lcase_entity . '_id'),
b2402735 93 'type' => CRM_Utils_Type::T_INT,
6a488035
TO
94 ));
95 break;
96
97 case 'getoptions':
98 $metadata = array(
786ad6e1 99 'field' => array(
3a8e9315
CW
100 'name' => 'field',
101 'title' => 'Field name',
786ad6e1
CW
102 'api.required' => 1,
103 ),
104 'context' => array(
3a8e9315
CW
105 'name' => 'context',
106 'title' => 'Context',
786ad6e1
CW
107 ),
108 );
c866eb5f
TO
109 break;
110
6a488035
TO
111 default:
112 // oddballs are on their own
113 $metadata = array();
114 }
115
116 // find any supplemental information
117 $hypApiRequest = array('entity' => $apiRequest['entity'], 'action' => $action, 'version' => $apiRequest['version']);
c65db512
TO
118 try {
119 list ($apiProvider, $hypApiRequest) = \Civi\Core\Container::singleton()->get('civi_api_kernel')->resolve($hypApiRequest);
378e2654
TO
120 if (isset($hypApiRequest['function'])) {
121 $helper = '_' . $hypApiRequest['function'] . '_spec';
0db6c3e1
TO
122 }
123 else {
378e2654
TO
124 // not implemented MagicFunctionProvider
125 $helper = NULL;
126 }
0db6c3e1
TO
127 }
128 catch (\Civi\API\Exception\NotImplementedException $e) {
c65db512
TO
129 $helper = NULL;
130 }
6a488035
TO
131 if (function_exists($helper)) {
132 // alter
6a386447 133 $helper($metadata, $apiRequest);
6a488035
TO
134 }
135
a4c5e9a3 136 $fieldsToResolve = (array) CRM_Utils_Array::value('get_options', $apiOptions, array());
6a488035
TO
137
138 foreach ($metadata as $fieldname => $fieldSpec) {
ddaac11c 139 _civicrm_api3_generic_get_metadata_options($metadata, $apiRequest, $fieldname, $fieldSpec, $fieldsToResolve);
6a488035
TO
140 }
141
a14e9d08 142 $results[$entity][$action][$sequential] = civicrm_api3_create_success($metadata, $apiRequest['params'], $entity, 'getfields');
ceccbc35 143 return $results[$entity][$action][$sequential];
6a488035
TO
144}
145
146/**
147 * API return function to reformat results as count
148 *
cf470720
TO
149 * @param array $apiRequest
150 * Api request as an array. Keys are.
6a488035 151 *
77b97be7 152 * @throws API_Exception
df8d3074 153 * @return int
72b3a70c 154 * count of results
6a488035
TO
155 */
156function civicrm_api3_generic_getcount($apiRequest) {
972322c5 157 $apiRequest['params']['options']['is_count'] = TRUE;
6a488035 158 $result = civicrm_api($apiRequest['entity'], 'get', $apiRequest['params']);
37fa58b0 159 if (is_numeric(CRM_Utils_Array::value('values', $result))) {
972322c5 160 return (int) $result['values'];
161 }
22e263ad 162 if (!isset($result['count'])) {
8335b10a 163 throw new API_Exception(ts('Unexpected result from getcount') . print_r($result, TRUE));
164 }
6a488035
TO
165 return $result['count'];
166}
167
168/**
169 * API return function to reformat results as single result
170 *
cf470720
TO
171 * @param array $apiRequest
172 * Api request as an array. Keys are.
6a488035 173 *
df8d3074 174 * @return int
72b3a70c 175 * count of results
6a488035
TO
176 */
177function civicrm_api3_generic_getsingle($apiRequest) {
178 // so the first entity is always result['values'][0]
179 $apiRequest['params']['sequential'] = 1;
180 $result = civicrm_api($apiRequest['entity'], 'get', $apiRequest['params']);
181 if ($result['is_error'] !== 0) {
182 return $result;
183 }
184 if ($result['count'] === 1) {
185 return $result['values'][0];
186 }
187 if ($result['count'] !== 1) {
188 return civicrm_api3_create_error("Expected one " . $apiRequest['entity'] . " but found " . $result['count'], array('count' => $result['count']));
189 }
190 return civicrm_api3_create_error("Undefined behavior");
191}
192
193/**
194 * API return function to reformat results as single value
195 *
cf470720
TO
196 * @param array $apiRequest
197 * Api request as an array. Keys are.
6a488035 198 *
df8d3074 199 * @return int
72b3a70c 200 * count of results
6a488035
TO
201 */
202function civicrm_api3_generic_getvalue($apiRequest) {
203 $apiRequest['params']['sequential'] = 1;
204 $result = civicrm_api($apiRequest['entity'], 'get', $apiRequest['params']);
205 if ($result['is_error'] !== 0) {
206 return $result;
207 }
208 if ($result['count'] !== 1) {
209 $result = civicrm_api3_create_error("Expected one " . $apiRequest['entity'] . " but found " . $result['count'], array('count' => $result['count']));
210 return $result;
211 }
212
213 // we only take "return=" as valid options
a7488080 214 if (!empty($apiRequest['params']['return'])) {
6a488035
TO
215 if (!isset($result['values'][0][$apiRequest['params']['return']])) {
216 return civicrm_api3_create_error("field " . $apiRequest['params']['return'] . " unset or not existing", array('invalid_field' => $apiRequest['params']['return']));
217 }
218
219 return $result['values'][0][$apiRequest['params']['return']];
220 }
221
222 return civicrm_api3_create_error("missing param return=field you want to read the value of", array('error_type' => 'mandatory_missing', 'missing_param' => 'return'));
223}
224
4e87860d 225/**
c490a46a 226 * @param array $params
4e87860d 227 */
9c8096cb
TO
228function _civicrm_api3_generic_getrefcount_spec(&$params) {
229 $params['id']['api.required'] = 1;
4c41ecb2 230 $params['id']['title'] = 'Entity ID';
9c8096cb
TO
231}
232
233/**
234 * API to determine if a record is in-use
235 *
cf470720
TO
236 * @param array $apiRequest
237 * Api request as an array.
9c8096cb
TO
238 *
239 * @throws API_Exception
a6c01b45 240 * @return array
72b3a70c 241 * API result (int 0 or 1)
9c8096cb
TO
242 */
243function civicrm_api3_generic_getrefcount($apiRequest) {
244 $entityToClassMap = CRM_Core_DAO_AllCoreTables::daoToClass();
245 if (!isset($entityToClassMap[$apiRequest['entity']])) {
246 throw new API_Exception("The entity '{$apiRequest['entity']}' is unknown or unsupported by 'getrefcount'. Consider implementing this API.", 'getrefcount_unsupported');
247 }
248 $daoClass = $entityToClassMap[$apiRequest['entity']];
249
250 /* @var $dao CRM_Core_DAO */
251 $dao = new $daoClass();
252 $dao->id = $apiRequest['params']['id'];
253 if ($dao->find(TRUE)) {
254 return civicrm_api3_create_success($dao->getReferenceCounts());
255 }
256 else {
257 return civicrm_api3_create_success(array());
258 }
259}
260
6a488035
TO
261/**
262 * API wrapper for replace function
263 *
cf470720
TO
264 * @param array $apiRequest
265 * Api request as an array. Keys are.
6a488035 266 *
df8d3074 267 * @return int
72b3a70c 268 * count of results
6a488035
TO
269 */
270function civicrm_api3_generic_replace($apiRequest) {
271 return _civicrm_api3_generic_replace($apiRequest['entity'], $apiRequest['params']);
272}
273
274/**
275 * API wrapper for getoptions function
276 *
cf470720
TO
277 * @param array $apiRequest
278 * Api request as an array.
6a488035 279 *
a6c01b45 280 * @return array
16b10e64 281 * Array of results
6a488035
TO
282 */
283function civicrm_api3_generic_getoptions($apiRequest) {
70f7ba9e
CW
284 // Resolve aliases
285 $fieldName = _civicrm_api3_api_resolve_alias($apiRequest['entity'], $apiRequest['params']['field']);
286 if (!$fieldName) {
287 return civicrm_api3_create_error("The field '{$apiRequest['params']['field']}' doesn't exist.");
288 }
a4a33486 289 // Validate 'context' from params
786ad6e1
CW
290 $context = CRM_Utils_Array::value('context', $apiRequest['params']);
291 CRM_Core_DAO::buildOptionsContext($context);
a3d8b390 292 unset($apiRequest['params']['context'], $apiRequest['params']['field']);
70f7ba9e 293
786ad6e1 294 $baoName = _civicrm_api3_get_BAO($apiRequest['entity']);
b7ceb253 295 $options = $baoName::buildOptions($fieldName, $context, $apiRequest['params']);
ee2b1c1c 296 if ($options === FALSE) {
70f7ba9e 297 return civicrm_api3_create_error("The field '{$fieldName}' has no associated option list.");
6a488035 298 }
15a1171a
CW
299 // Support 'sequential' output as a non-associative array
300 if (!empty($apiRequest['params']['sequential'])) {
b7ceb253 301 $options = CRM_Utils_Array::makeNonAssociative($options);
15a1171a 302 }
b7ceb253 303 return civicrm_api3_create_success($options, $apiRequest['params'], $apiRequest['entity'], 'getoptions');
6a488035
TO
304}
305
11e09c59 306/**
6a488035
TO
307 * Function fills the 'options' array on the metadata returned by getfields if
308 * 1) the param option 'get_options' is defined - e.g. $params['options']['get_options'] => array('custom_1)
309 * (this is passed in as the $fieldsToResolve array)
310 * 2) the field is a pseudoconstant and is NOT an FK
311 * - the reason for this is that checking / transformation is done on pseudoconstants but
312 * - if the field is an FK then mysql will enforce the data quality (& we have handling on failure)
7c285037 313 * @todo - if may be we should define a 'resolve' key on the pseudoconstant for when these rules are not fine enough
6a488035
TO
314 *
315 * This function is only split out for the purpose of code clarity / comment block documentation
77b97be7 316 *
cf470720
TO
317 * @param array $metadata
318 * The array of metadata that will form the result of the getfields function.
72b3a70c 319 * @param array $apiRequest
cf470720
TO
320 * @param string $fieldname
321 * Field currently being processed.
322 * @param array $fieldSpec
323 * Metadata for that field.
324 * @param array $fieldsToResolve
325 * Anny field resolutions specifically requested.
6a488035 326 */
9b873358 327function _civicrm_api3_generic_get_metadata_options(&$metadata, $apiRequest, $fieldname, $fieldSpec, $fieldsToResolve) {
3a8e9315 328 if (empty($fieldSpec['pseudoconstant']) && empty($fieldSpec['option_group_id'])) {
6a488035
TO
329 return;
330 }
331
ed8abbbb 332 if (!empty($metadata[$fieldname]['options']) || (!in_array($fieldname, $fieldsToResolve) && !in_array('all', $fieldsToResolve))) {
70f7ba9e
CW
333 return;
334 }
335
ddaac11c 336 $options = civicrm_api($apiRequest['entity'], 'getoptions', array('version' => 3, 'field' => $fieldname, 'sequential' => !empty($apiRequest['params']['sequential'])));
6a488035
TO
337 if (is_array(CRM_Utils_Array::value('values', $options))) {
338 $metadata[$fieldname]['options'] = $options['values'];
339 }
340}