3 +--------------------------------------------------------------------+
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2019 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
10 | CiviCRM is free software; you can copy, modify, and distribute it |
11 | under the terms of the GNU Affero General Public License |
12 | Version 3, 19 November 2007 and the CiviCRM Licensing Exception. |
14 | CiviCRM is distributed in the hope that it will be useful, but |
15 | WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
17 | See the GNU Affero General Public License for more details. |
19 | You should have received a copy of the GNU Affero General Public |
20 | License and the CiviCRM Licensing Exception along |
21 | with this program; if not, contact CiviCRM LLC |
22 | at info[AT]civicrm[DOT]org. If you have questions about the |
23 | GNU Affero General Public License or the licensing of CiviCRM, |
24 | see the CiviCRM license FAQ at http://civicrm.org/licensing |
25 +--------------------------------------------------------------------+
29 * @package CiviCRM_APIv3
33 * Get information about fields for a given api request.
35 * Getfields information is used for documentation, validation, default setting
36 * We first query the scheme using the $dao->fields function & then augment
37 * that information by calling the _spec functions that apply to the relevant function
38 * Note that we use 'unique' field names as described in the xml/schema files
39 * for get requests & just field name for create. This is because some get functions
40 * access multiple objects e.g. contact api accesses is_deleted from the activity
41 * table & from the contact table
43 * @param array $apiRequest
44 * Api request as an array. Keys are.
48 * - function: callback (mixed)
49 * - params: array, varies
52 * Determines whether to key by unique field names (only affects get-type) actions
57 function civicrm_api3_generic_getfields($apiRequest, $unique = TRUE) {
59 if ((CRM_Utils_Array
::value('cache_clear', $apiRequest['params']))) {
61 // we will also clear pseudoconstants here - should potentially be moved to relevant BAO classes
62 CRM_Core_PseudoConstant
::flush();
63 if (!empty($apiRequest['params']['fieldname'])) {
64 CRM_Utils_PseudoConstant
::flushConstant($apiRequest['params']['fieldname']);
66 if (!empty($apiRequest['params']['option_group_id'])) {
67 $optionGroupName = civicrm_api('option_group', 'getvalue', [
69 'id' => $apiRequest['params']['option_group_id'],
72 if (is_string($optionGroupName)) {
73 CRM_Utils_PseudoConstant
::flushConstant(_civicrm_api_get_camel_name($optionGroupName));
77 $entity = $apiRequest['entity'];
78 $lowercase_entity = _civicrm_api_get_entity_name_from_camel($entity);
79 $subentity = CRM_Utils_Array
::value('contact_type', $apiRequest['params']);
80 $action = CRM_Utils_Array
::value('action', $apiRequest['params']);
81 $sequential = empty($apiRequest['params']['sequential']) ?
0 : 1;
82 $apiRequest['params']['options'] = CRM_Utils_Array
::value('options', $apiRequest['params'], []);
83 $optionsToResolve = (array) CRM_Utils_Array
::value('get_options', $apiRequest['params']['options'], []);
85 if (!$action ||
$action == 'getvalue' ||
$action == 'getcount') {
88 // If no options, return results from cache
89 if (!$apiRequest['params']['options'] && isset($results[$entity . $subentity]) && isset($action, $results[$entity . $subentity])
90 && isset($action, $results[$entity . $subentity][$sequential])) {
91 return $results[$entity . $subentity][$action][$sequential];
93 // defaults based on data model and API policy
96 $values = _civicrm_api_get_fields($entity, FALSE, $apiRequest['params']);
97 return civicrm_api3_create_success($values, $apiRequest['params'], $entity, 'getfields');
107 $metadata = _civicrm_api_get_fields($apiRequest['entity'], $unique, $apiRequest['params']);
108 if (empty($metadata['id'])) {
109 // if id is not set we will set it eg. 'id' from 'case_id', case_id will be an alias
110 if (!empty($metadata[strtolower($apiRequest['entity']) . '_id'])) {
111 $metadata['id'] = $metadata[$lowercase_entity . '_id'];
112 unset($metadata[$lowercase_entity . '_id']);
113 $metadata['id']['api.aliases'] = [$lowercase_entity . '_id'];
117 // really the preference would be to set the unique name in the xml
118 // question is which is a less risky fix this close to a release - setting in xml for the known failure
119 // (note) or setting for all api where fields is returning 'id' & we want to accept 'note_id' @ the api layer
120 // nb we don't officially accept note_id anyway - rationale here is more about centralising a now-tested
122 $metadata['id']['api.aliases'] = [$lowercase_entity . '_id'];
129 'title' => $entity . ' ID',
131 'api.aliases' => [$lowercase_entity . '_id'],
132 'type' => CRM_Utils_Type
::T_INT
,
137 // Note: adding setvalue case here instead of in a generic spec function because
138 // some APIs override the generic setvalue fn which causes the generic spec to be overlooked.
142 'title' => 'Field name',
144 'type' => CRM_Utils_Type
::T_STRING
,
147 'title' => $entity . ' ID',
149 'type' => CRM_Utils_Type
::T_INT
,
153 'description' => "Field value to set",
157 if (array_intersect(['all', 'field'], $optionsToResolve)) {
158 $options = civicrm_api3_generic_getfields(['entity' => $entity, ['params' => ['action' => 'create']]]);
159 $metadata['field']['options'] = CRM_Utils_Array
::collect('title', $options['values']);
164 // oddballs are on their own
168 // Hack for product api to pass tests.
169 if (!is_string($apiRequest['params']['options'])) {
170 // Normalize this for the sake of spec funcions
171 $apiRequest['params']['options']['get_options'] = $optionsToResolve;
174 // find any supplemental information
175 $hypApiRequest = ['entity' => $apiRequest['entity'], 'action' => $action, 'version' => $apiRequest['version']];
176 if ($action == 'getsingle') {
177 $hypApiRequest['action'] = 'get';
180 list ($apiProvider, $hypApiRequest) = \Civi
::service('civi_api_kernel')->resolve($hypApiRequest);
181 if (isset($hypApiRequest['function'])) {
182 $helper = '_' . $hypApiRequest['function'] . '_spec';
185 // not implemented MagicFunctionProvider
189 catch (\Civi\API\Exception\NotImplementedException
$e) {
192 if (function_exists($helper)) {
194 $helper($metadata, $apiRequest);
197 foreach ($metadata as $fieldname => $fieldSpec) {
198 // Ensure 'name' is set
199 if (!isset($fieldSpec['name'])) {
200 $metadata[$fieldname]['name'] = $fieldname;
202 _civicrm_api3_generic_get_metadata_options($metadata, $apiRequest, $fieldname, $fieldSpec);
204 // Convert options to "sequential" format
205 if ($sequential && !empty($metadata[$fieldname]['options'])) {
206 $metadata[$fieldname]['options'] = CRM_Utils_Array
::makeNonAssociative($metadata[$fieldname]['options']);
210 $results[$entity][$action][$sequential] = civicrm_api3_create_success($metadata, $apiRequest['params'], $entity, 'getfields');
211 return $results[$entity][$action][$sequential];
215 * Get metadata for a field
217 * @param array $apiRequest
222 function civicrm_api3_generic_getfield($apiRequest) {
223 $params = $apiRequest['params'];
224 $sequential = !empty($params['sequential']);
225 $fieldName = _civicrm_api3_api_resolve_alias($apiRequest['entity'], $params['name'], $params['action']);
227 return civicrm_api3_create_error("The field '{$params['name']}' doesn't exist.");
229 // Turn off sequential to make the field easier to find
230 $apiRequest['params']['sequential'] = 0;
231 if (isset($params['get_options'])) {
232 $apiRequest['params']['options']['get_options_context'] = $params['get_options'];
233 $apiRequest['params']['options']['get_options'] = $fieldName;
235 $result = civicrm_api3_generic_getfields($apiRequest, FALSE);
236 $result = $result['values'][$fieldName];
237 // Fix sequential options since we forced it off
238 if ($sequential && !empty($result['options'])) {
239 $result['options'] = CRM_Utils_Array
::makeNonAssociative($result['options']);
241 return civicrm_api3_create_success($result, $apiRequest['params'], $apiRequest['entity'], 'getfield');
245 * Get metadata for getfield action.
247 * @param array $params
248 * @param array $apiRequest
250 * @throws \CiviCRM_API3_Exception
253 function _civicrm_api3_generic_getfield_spec(&$params, $apiRequest) {
256 'title' => 'Field name',
257 'description' => 'Name or alias of field to lookup',
259 'type' => CRM_Utils_Type
::T_STRING
,
262 'title' => 'API Action',
264 'type' => CRM_Utils_Type
::T_STRING
,
265 'api.aliases' => ['api_action'],
268 'title' => 'Get Options',
269 'description' => 'Context for which to get field options, or null to skip fetching options.',
270 'type' => CRM_Utils_Type
::T_STRING
,
271 'options' => CRM_Core_DAO
::buildOptionsContext(),
272 'api.aliases' => ['context'],
275 // Add available options to these params if requested
276 if (array_intersect(['all', 'action'], $apiRequest['params']['options']['get_options'])) {
277 $actions = civicrm_api3($apiRequest['entity'], 'getactions');
278 $actions = array_combine($actions['values'], $actions['values']);
279 // Let's not go meta-crazy
280 CRM_Utils_Array
::remove($actions, 'getactions', 'getoptions', 'getfields', 'getfield', 'getcount', 'getrefcount', 'getsingle', 'getlist', 'getvalue', 'setvalue', 'update');
281 $params['action']['options'] = $actions;
286 * API return function to reformat results as count.
288 * @param array $apiRequest
289 * Api request as an array. Keys are.
291 * @throws API_Exception
295 function civicrm_api3_generic_getcount($apiRequest) {
296 $apiRequest['params']['options']['is_count'] = TRUE;
297 $result = civicrm_api($apiRequest['entity'], 'get', $apiRequest['params']);
298 if (is_numeric(CRM_Utils_Array
::value('values', $result))) {
299 return (int) $result['values'];
301 if (!isset($result['count'])) {
302 throw new API_Exception(ts('Unexpected result from getcount') . print_r($result, TRUE));
304 return $result['count'];
308 * API return function to reformat results as single result.
310 * @param array $apiRequest
311 * Api request as an array. Keys are.
316 function civicrm_api3_generic_getsingle($apiRequest) {
317 // So the first entity is always result['values'][0].
318 $apiRequest['params']['sequential'] = 1;
319 $result = civicrm_api($apiRequest['entity'], 'get', $apiRequest['params']);
320 if ($result['is_error'] !== 0) {
323 if ($result['count'] === 1) {
324 return $result['values'][0];
326 if ($result['count'] !== 1) {
327 return civicrm_api3_create_error("Expected one " . $apiRequest['entity'] . " but found " . $result['count'], ['count' => $result['count']]);
329 return civicrm_api3_create_error("Undefined behavior");
333 * API return function to reformat results as single value.
335 * @param array $apiRequest
336 * Api request as an array. Keys are.
341 function civicrm_api3_generic_getvalue($apiRequest) {
342 $apiRequest['params']['sequential'] = 1;
343 $result = civicrm_api($apiRequest['entity'], 'get', $apiRequest['params']);
344 if ($result['is_error'] !== 0) {
347 if ($result['count'] !== 1) {
348 $result = civicrm_api3_create_error("Expected one " . $apiRequest['entity'] . " but found " . $result['count'], ['count' => $result['count']]);
352 // we only take "return=" as valid options
353 if (!empty($apiRequest['params']['return'])) {
354 if (!isset($result['values'][0][$apiRequest['params']['return']])) {
355 return civicrm_api3_create_error("field " . $apiRequest['params']['return'] . " unset or not existing", ['invalid_field' => $apiRequest['params']['return']]);
358 return $result['values'][0][$apiRequest['params']['return']];
361 return civicrm_api3_create_error("missing param return=field you want to read the value of", ['error_type' => 'mandatory_missing', 'missing_param' => 'return']);
365 * Get count of contact references.
367 * @param array $params
368 * @param array $apiRequest
370 function _civicrm_api3_generic_getrefcount_spec(&$params, $apiRequest) {
371 $params['id']['api.required'] = 1;
372 $params['id']['title'] = $apiRequest['entity'] . ' ID';
373 $params['id']['type'] = CRM_Utils_Type
::T_INT
;
377 * API to determine if a record is in-use.
379 * @param array $apiRequest
380 * Api request as an array.
382 * @throws API_Exception
384 * API result (int 0 or 1)
386 function civicrm_api3_generic_getrefcount($apiRequest) {
387 $entityToClassMap = CRM_Core_DAO_AllCoreTables
::daoToClass();
388 if (!isset($entityToClassMap[$apiRequest['entity']])) {
389 throw new API_Exception("The entity '{$apiRequest['entity']}' is unknown or unsupported by 'getrefcount'. Consider implementing this API.", 'getrefcount_unsupported');
391 $daoClass = $entityToClassMap[$apiRequest['entity']];
393 /* @var $dao CRM_Core_DAO */
394 $dao = new $daoClass();
395 $dao->id
= $apiRequest['params']['id'];
396 if ($dao->find(TRUE)) {
397 return civicrm_api3_create_success($dao->getReferenceCounts());
400 return civicrm_api3_create_success([]);
405 * API wrapper for replace function.
407 * @param array $apiRequest
408 * Api request as an array. Keys are.
413 function civicrm_api3_generic_replace($apiRequest) {
414 return _civicrm_api3_generic_replace($apiRequest['entity'], $apiRequest['params']);
418 * API wrapper for getoptions function.
420 * @param array $apiRequest
421 * Api request as an array.
426 function civicrm_api3_generic_getoptions($apiRequest) {
428 $fieldName = _civicrm_api3_api_resolve_alias($apiRequest['entity'], $apiRequest['params']['field']);
430 return civicrm_api3_create_error("The field '{$apiRequest['params']['field']}' doesn't exist.");
432 // Validate 'context' from params
433 $context = CRM_Utils_Array
::value('context', $apiRequest['params']);
434 CRM_Core_DAO
::buildOptionsContext($context);
435 unset($apiRequest['params']['context'], $apiRequest['params']['field'], $apiRequest['params']['condition']);
437 $baoName = _civicrm_api3_get_BAO($apiRequest['entity']);
438 $options = $baoName::buildOptions($fieldName, $context, $apiRequest['params']);
439 if ($options === FALSE) {
440 return civicrm_api3_create_error("The field '{$fieldName}' has no associated option list.");
442 // Support 'sequential' output as a non-associative array
443 if (!empty($apiRequest['params']['sequential'])) {
444 $options = CRM_Utils_Array
::makeNonAssociative($options);
446 return civicrm_api3_create_success($options, $apiRequest['params'], $apiRequest['entity'], 'getoptions');
450 * Provide metadata for this generic action
455 function _civicrm_api3_generic_getoptions_spec(&$params, $apiRequest) {
458 'title' => 'Field name',
460 'type' => CRM_Utils_Type
::T_STRING
,
463 'title' => 'Context',
464 'type' => CRM_Utils_Type
::T_STRING
,
465 'options' => CRM_Core_DAO
::buildOptionsContext(),
469 // Add available fields if requested
470 if (array_intersect(['all', 'field'], $apiRequest['params']['options']['get_options'])) {
471 $fields = civicrm_api3_generic_getfields(['entity' => $apiRequest['entity'], ['params' => ['action' => 'create']]]);
472 $params['field']['options'] = [];
473 foreach ($fields['values'] as $name => $field) {
474 if (isset($field['pseudoconstant']) || CRM_Utils_Array
::value('type', $field) == CRM_Utils_Type
::T_BOOLEAN
) {
475 $params['field']['options'][$name] = CRM_Utils_Array
::value('title', $field, $name);
480 $entityName = _civicrm_api_get_entity_name_from_camel($apiRequest['entity']);
481 $getOptionsSpecFunction = '_civicrm_api3_' . $entityName . '_getoptions_spec';
483 if (function_exists($getOptionsSpecFunction)) {
484 $getOptionsSpecFunction($params);
491 * Function fills the 'options' array on the metadata returned by getfields if
492 * 1) the param option 'get_options' is defined - e.g. $params['options']['get_options'] => array('custom_1)
493 * (this is passed in as the $fieldsToResolve array)
494 * 2) the field is a pseudoconstant and is NOT an FK
495 * - the reason for this is that checking / transformation is done on pseudoconstants but
496 * - if the field is an FK then mysql will enforce the data quality (& we have handling on failure)
497 * @todo - if may be we should define a 'resolve' key on the pseudoconstant for when these rules are not fine enough
499 * This function is only split out for the purpose of code clarity / comment block documentation
501 * @param array $metadata
502 * The array of metadata that will form the result of the getfields function.
503 * @param array $apiRequest
504 * @param string $fieldname
505 * Field currently being processed.
506 * @param array $fieldSpec
507 * Metadata for that field.
509 function _civicrm_api3_generic_get_metadata_options(&$metadata, $apiRequest, $fieldname, $fieldSpec) {
510 if (empty($fieldSpec['pseudoconstant']) && empty($fieldSpec['option_group_id'])) {
514 $fieldsToResolve = $apiRequest['params']['options']['get_options'];
516 if (!empty($metadata[$fieldname]['options']) ||
(!in_array($fieldname, $fieldsToResolve) && !in_array('all', $fieldsToResolve))) {
520 // Allow caller to specify context
521 $context = CRM_Utils_Array
::value('get_options_context', $apiRequest['params']['options']);
522 // Default to api action if it is a supported context.
524 $action = CRM_Utils_Array
::value('action', $apiRequest['params']);
525 $contexts = CRM_Core_DAO
::buildOptionsContext();
526 if (isset($contexts[$action])) {
531 $options = civicrm_api($apiRequest['entity'], 'getoptions', ['version' => 3, 'field' => $fieldname, 'context' => $context]);
532 if (is_array(CRM_Utils_Array
::value('values', $options))) {
533 $metadata[$fieldname]['options'] = $options['values'];