api/v3/Generic.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  * @package CiviCRM_APIv3
  14  */
  15
  16 /**
  17  * Get information about fields for a given api request.
  18  *
  19  * Getfields information is used for documentation, validation, default setting
  20  * We first query the scheme using the $dao->fields function & then augment
  21  * that information by calling the _spec functions that apply to the relevant function
  22  * Note that we use 'unique' field names as described in the xml/schema files
  23  * for get requests & just field name for create. This is because some get functions
  24  * access multiple objects e.g. contact api accesses is_deleted from the activity
  25  * table & from the contact table
  26  *
  27  * @param array $apiRequest
  28  *   Api request as an array. Keys are.
  29  *   - entity: string
  30  *   - action: string
  31  *   - version: string
  32  *   - function: callback (mixed)
  33  *   - params: array, varies
  34  *
  35  * @param bool $unique
  36  *   Determines whether to key by unique field names (only affects get-type) actions
  37  *
  38  * @return array
  39  *   API success object
  40  */
  41 function civicrm_api3_generic_getfields($apiRequest, $unique = TRUE) {
  42   static $results = [];
  43   if ((CRM_Utils_Array::value('cache_clear', $apiRequest['params']))) {
  44     $results = [];
  45     // we will also clear pseudoconstants here - should potentially be moved to relevant BAO classes
  46     CRM_Core_PseudoConstant::flush();
  47     if (!empty($apiRequest['params']['fieldname'])) {
  48       CRM_Utils_PseudoConstant::flushConstant($apiRequest['params']['fieldname']);
  49     }
  50     if (!empty($apiRequest['params']['option_group_id'])) {
  51       $optionGroupName = civicrm_api('option_group', 'getvalue', [
  52         'version' => 3,
  53         'id' => $apiRequest['params']['option_group_id'],
  54         'return' => 'name',
  55       ]);
  56       if (is_string($optionGroupName)) {
  57         CRM_Utils_PseudoConstant::flushConstant(_civicrm_api_get_camel_name($optionGroupName));
  58       }
  59     }
  60   }
  61   $entity = $apiRequest['entity'];
  62   $lowercase_entity = _civicrm_api_get_entity_name_from_camel($entity);
  63   $subentity    = $apiRequest['params']['contact_type'] ?? NULL;
  64   $action = $apiRequest['params']['action'] ?? NULL;
  65   $sequential = empty($apiRequest['params']['sequential']) ? 0 : 1;
  66   $apiRequest['params']['options'] = CRM_Utils_Array::value('options', $apiRequest['params'], []);
  67   $optionsToResolve = (array) CRM_Utils_Array::value('get_options', $apiRequest['params']['options'], []);
  68
  69   if (!$action || $action == 'getvalue' || $action == 'getcount') {
  70     $action = 'get';
  71   }
  72   // If no options, return results from cache
  73   if (!$apiRequest['params']['options'] && isset($results[$entity . $subentity]) && isset($action, $results[$entity . $subentity])
  74     && isset($action, $results[$entity . $subentity][$sequential])) {
  75     return $results[$entity . $subentity][$action][$sequential];
  76   }
  77   // defaults based on data model and API policy
  78   switch ($action) {
  79     case 'getfields':
  80       $values = _civicrm_api_get_fields($entity, FALSE, $apiRequest['params']);
  81       return civicrm_api3_create_success($values, $apiRequest['params'], $entity, 'getfields');
  82
  83     case 'create':
  84     case 'update':
  85     case 'replace':
  86       $unique = FALSE;
  87     case 'get':
  88     case 'getsingle':
  89     case 'getcount':
  90     case 'getstat':
  91       $metadata = _civicrm_api_get_fields($apiRequest['entity'], $unique, $apiRequest['params']);
  92       if (empty($metadata['id'])) {
  93         // if id is not set we will set it eg. 'id' from 'case_id', case_id will be an alias
  94         if (!empty($metadata[strtolower($apiRequest['entity']) . '_id'])) {
  95           $metadata['id'] = $metadata[$lowercase_entity . '_id'];
  96           unset($metadata[$lowercase_entity . '_id']);
  97           $metadata['id']['api.aliases'] = [$lowercase_entity . '_id'];
  98         }
  99       }
 100       else {
 101         // really the preference would be to set the unique name in the xml
 102         // question is which is a less risky fix this close to a release - setting in xml for the known failure
 103         // (note) or setting for all api where fields is returning 'id' & we want to accept 'note_id' @ the api layer
 104         // nb we don't officially accept note_id anyway - rationale here is more about centralising a now-tested
 105         // inconsistency
 106         $metadata['id']['api.aliases'] = [$lowercase_entity . '_id'];
 107       }
 108       break;
 109
 110     case 'delete':
 111       $metadata = [
 112         'id' => [
 113           'title' => $entity . ' ID',
 114           'api.required' => 1,
 115           'api.aliases' => [$lowercase_entity . '_id'],
 116           'type' => CRM_Utils_Type::T_INT,
 117         ],
 118       ];
 119       break;
 120
 121     // Note: adding setvalue case here instead of in a generic spec function because
 122     // some APIs override the generic setvalue fn which causes the generic spec to be overlooked.
 123     case 'setvalue':
 124       $metadata = [
 125         'field' => [
 126           'title' => 'Field name',
 127           'api.required' => 1,
 128           'type' => CRM_Utils_Type::T_STRING,
 129         ],
 130         'id' => [
 131           'title' => $entity . ' ID',
 132           'api.required' => 1,
 133           'type' => CRM_Utils_Type::T_INT,
 134         ],
 135         'value' => [
 136           'title' => 'Value',
 137           'description' => "Field value to set",
 138           'api.required' => 1,
 139         ],
 140       ];
 141       if (array_intersect(['all', 'field'], $optionsToResolve)) {
 142         $options = civicrm_api3_generic_getfields(['entity' => $entity, ['params' => ['action' => 'create']]]);
 143         $metadata['field']['options'] = CRM_Utils_Array::collect('title', $options['values']);
 144       }
 145       break;
 146
 147     default:
 148       // oddballs are on their own
 149       $metadata = [];
 150   }
 151
 152   // Hack for product api to pass tests.
 153   if (!is_string($apiRequest['params']['options'])) {
 154     // Normalize this for the sake of spec funcions
 155     $apiRequest['params']['options']['get_options'] = $optionsToResolve;
 156   }
 157
 158   // find any supplemental information
 159   $hypApiRequest = ['entity' => $apiRequest['entity'], 'action' => $action, 'version' => $apiRequest['version']];
 160   if ($action == 'getsingle') {
 161     $hypApiRequest['action'] = 'get';
 162   }
 163   try {
 164     list ($apiProvider, $hypApiRequest) = \Civi::service('civi_api_kernel')->resolve($hypApiRequest);
 165     if (isset($hypApiRequest['function'])) {
 166       $helper = '_' . $hypApiRequest['function'] . '_spec';
 167     }
 168     else {
 169       // not implemented MagicFunctionProvider
 170       $helper = NULL;
 171     }
 172   }
 173   catch (\Civi\API\Exception\NotImplementedException $e) {
 174     $helper = NULL;
 175   }
 176   if (function_exists($helper)) {
 177     // alter
 178     $helper($metadata, $apiRequest);
 179   }
 180
 181   foreach ($metadata as $fieldname => $fieldSpec) {
 182     // Ensure 'name' is set
 183     if (!isset($fieldSpec['name'])) {
 184       $metadata[$fieldname]['name'] = $fieldname;
 185     }
 186     _civicrm_api3_generic_get_metadata_options($metadata, $apiRequest, $fieldname, $fieldSpec);
 187
 188     // Convert options to "sequential" format
 189     if ($sequential && !empty($metadata[$fieldname]['options'])) {
 190       $metadata[$fieldname]['options'] = CRM_Utils_Array::makeNonAssociative($metadata[$fieldname]['options']);
 191     }
 192   }
 193
 194   $results[$entity][$action][$sequential] = civicrm_api3_create_success($metadata, $apiRequest['params'], $entity, 'getfields');
 195   return $results[$entity][$action][$sequential];
 196 }
 197
 198 /**
 199  * Get metadata for a field
 200  *
 201  * @param array $apiRequest
 202  *
 203  * @return array
 204  *   API success object
 205  */
 206 function civicrm_api3_generic_getfield($apiRequest) {
 207   $params = $apiRequest['params'];
 208   $sequential = !empty($params['sequential']);
 209   $fieldName = _civicrm_api3_api_resolve_alias($apiRequest['entity'], $params['name'], $params['action']);
 210   if (!$fieldName) {
 211     return civicrm_api3_create_error("The field '{$params['name']}' doesn't exist.");
 212   }
 213   // Turn off sequential to make the field easier to find
 214   $apiRequest['params']['sequential'] = 0;
 215   if (isset($params['get_options'])) {
 216     $apiRequest['params']['options']['get_options_context'] = $params['get_options'];
 217     $apiRequest['params']['options']['get_options'] = $fieldName;
 218   }
 219   $result = civicrm_api3_generic_getfields($apiRequest, FALSE);
 220   $result = $result['values'][$fieldName];
 221   // Fix sequential options since we forced it off
 222   if ($sequential && !empty($result['options'])) {
 223     $result['options'] = CRM_Utils_Array::makeNonAssociative($result['options']);
 224   }
 225   return civicrm_api3_create_success($result, $apiRequest['params'], $apiRequest['entity'], 'getfield');
 226 }
 227
 228 /**
 229  * Get metadata for getfield action.
 230  *
 231  * @param array $params
 232  * @param array $apiRequest
 233  *
 234  * @throws \CiviCRM_API3_Exception
 235  * @throws \Exception
 236  */
 237 function _civicrm_api3_generic_getfield_spec(&$params, $apiRequest) {
 238   $params = [
 239     'name' => [
 240       'title' => 'Field name',
 241       'description' => 'Name or alias of field to lookup',
 242       'api.required' => 1,
 243       'type' => CRM_Utils_Type::T_STRING,
 244     ],
 245     'action' => [
 246       'title' => 'API Action',
 247       'api.required' => 1,
 248       'type' => CRM_Utils_Type::T_STRING,
 249       'api.aliases' => ['api_action'],
 250     ],
 251     'get_options' => [
 252       'title' => 'Get Options',
 253       'description' => 'Context for which to get field options, or null to skip fetching options.',
 254       'type' => CRM_Utils_Type::T_STRING,
 255       'options' => CRM_Core_DAO::buildOptionsContext(),
 256       'api.aliases' => ['context'],
 257     ],
 258   ];
 259   // Add available options to these params if requested
 260   if (array_intersect(['all', 'action'], $apiRequest['params']['options']['get_options'])) {
 261     $actions = civicrm_api3($apiRequest['entity'], 'getactions');
 262     $actions = array_combine($actions['values'], $actions['values']);
 263     // Let's not go meta-crazy
 264     CRM_Utils_Array::remove($actions, 'getactions', 'getoptions', 'getfields', 'getfield', 'getcount', 'getrefcount', 'getsingle', 'getlist', 'getvalue', 'setvalue', 'update');
 265     $params['action']['options'] = $actions;
 266   }
 267 }
 268
 269 /**
 270  * API return function to reformat results as count.
 271  *
 272  * @param array $apiRequest
 273  *   Api request as an array. Keys are.
 274  *
 275  * @throws API_Exception
 276  * @return int
 277  *   count of results
 278  */
 279 function civicrm_api3_generic_getcount($apiRequest) {
 280   $apiRequest['params']['options']['is_count'] = TRUE;
 281   $result = civicrm_api($apiRequest['entity'], 'get', $apiRequest['params']);
 282   if (is_numeric(CRM_Utils_Array::value('values', $result))) {
 283     return (int) $result['values'];
 284   }
 285   if (!isset($result['count'])) {
 286     throw new API_Exception(ts('Unexpected result from getcount') . print_r($result, TRUE));
 287   }
 288   return $result['count'];
 289 }
 290
 291 /**
 292  * API return function to reformat results as single result.
 293  *
 294  * @param array $apiRequest
 295  *   Api request as an array. Keys are.
 296  *
 297  * @return int
 298  *   count of results
 299  */
 300 function civicrm_api3_generic_getsingle($apiRequest) {
 301   // So the first entity is always result['values'][0].
 302   $apiRequest['params']['sequential'] = 1;
 303   $result = civicrm_api($apiRequest['entity'], 'get', $apiRequest['params']);
 304   if ($result['is_error'] !== 0) {
 305     return $result;
 306   }
 307   if ($result['count'] === 1) {
 308     return $result['values'][0];
 309   }
 310   if ($result['count'] !== 1) {
 311     return civicrm_api3_create_error("Expected one " . $apiRequest['entity'] . " but found " . $result['count'], ['count' => $result['count']]);
 312   }
 313   return civicrm_api3_create_error("Undefined behavior");
 314 }
 315
 316 /**
 317  * API return function to reformat results as single value.
 318  *
 319  * @param array $apiRequest
 320  *   Api request as an array. Keys are.
 321  *
 322  * @return int
 323  *   count of results
 324  */
 325 function civicrm_api3_generic_getvalue($apiRequest) {
 326   $apiRequest['params']['sequential'] = 1;
 327   $result = civicrm_api($apiRequest['entity'], 'get', $apiRequest['params']);
 328   if ($result['is_error'] !== 0) {
 329     return $result;
 330   }
 331   if ($result['count'] !== 1) {
 332     $result = civicrm_api3_create_error("Expected one " . $apiRequest['entity'] . " but found " . $result['count'], ['count' => $result['count']]);
 333     return $result;
 334   }
 335
 336   // we only take "return=" as valid options
 337   if (!empty($apiRequest['params']['return'])) {
 338     if (!isset($result['values'][0][$apiRequest['params']['return']])) {
 339       return civicrm_api3_create_error("field " . $apiRequest['params']['return'] . " unset or not existing", ['invalid_field' => $apiRequest['params']['return']]);
 340     }
 341
 342     return $result['values'][0][$apiRequest['params']['return']];
 343   }
 344
 345   return civicrm_api3_create_error("missing param return=field you want to read the value of", ['error_type' => 'mandatory_missing', 'missing_param' => 'return']);
 346 }
 347
 348 /**
 349  * Get count of contact references.
 350  *
 351  * @param array $params
 352  * @param array $apiRequest
 353  */
 354 function _civicrm_api3_generic_getrefcount_spec(&$params, $apiRequest) {
 355   $params['id']['api.required'] = 1;
 356   $params['id']['title'] = $apiRequest['entity'] . ' ID';
 357   $params['id']['type'] = CRM_Utils_Type::T_INT;
 358 }
 359
 360 /**
 361  * API to determine if a record is in-use.
 362  *
 363  * @param array $apiRequest
 364  *   Api request as an array.
 365  *
 366  * @throws API_Exception
 367  * @return array
 368  *   API result (int 0 or 1)
 369  */
 370 function civicrm_api3_generic_getrefcount($apiRequest) {
 371   $entityToClassMap = CRM_Core_DAO_AllCoreTables::daoToClass();
 372   if (!isset($entityToClassMap[$apiRequest['entity']])) {
 373     throw new API_Exception("The entity '{$apiRequest['entity']}' is unknown or unsupported by 'getrefcount'. Consider implementing this API.", 'getrefcount_unsupported');
 374   }
 375   $daoClass = $entityToClassMap[$apiRequest['entity']];
 376
 377   /* @var $dao CRM_Core_DAO */
 378   $dao = new $daoClass();
 379   $dao->id = $apiRequest['params']['id'];
 380   if ($dao->find(TRUE)) {
 381     return civicrm_api3_create_success($dao->getReferenceCounts());
 382   }
 383   else {
 384     return civicrm_api3_create_success([]);
 385   }
 386 }
 387
 388 /**
 389  * API wrapper for replace function.
 390  *
 391  * @param array $apiRequest
 392  *   Api request as an array. Keys are.
 393  *
 394  * @return int
 395  *   count of results
 396  */
 397 function civicrm_api3_generic_replace($apiRequest) {
 398   return _civicrm_api3_generic_replace($apiRequest['entity'], $apiRequest['params']);
 399 }
 400
 401 /**
 402  * API wrapper for getoptions function.
 403  *
 404  * @param array $apiRequest
 405  *   Api request as an array.
 406  *
 407  * @return array
 408  *   Array of results
 409  * @throws \CiviCRM_API3_Exception
 410  */
 411 function civicrm_api3_generic_getoptions($apiRequest) {
 412   // Resolve aliases.
 413   $fieldName = _civicrm_api3_api_resolve_alias($apiRequest['entity'], $apiRequest['params']['field']);
 414   if (!$fieldName) {
 415     return civicrm_api3_create_error("The field '{$apiRequest['params']['field']}' doesn't exist.");
 416   }
 417   // Validate 'context' from params
 418   $context = $apiRequest['params']['context'] ?? NULL;
 419   CRM_Core_DAO::buildOptionsContext($context);
 420   unset($apiRequest['params']['context'], $apiRequest['params']['field'], $apiRequest['params']['condition']);
 421
 422   $baoName = _civicrm_api3_get_BAO($apiRequest['entity']);
 423   $options = $baoName::buildOptions($fieldName, $context, $apiRequest['params']);
 424   if ($options === FALSE) {
 425     return civicrm_api3_create_error("The field '{$fieldName}' has no associated option list.");
 426   }
 427   // Support 'sequential' output as a non-associative array
 428   if (!empty($apiRequest['params']['sequential'])) {
 429     $options = CRM_Utils_Array::makeNonAssociative($options);
 430   }
 431   return civicrm_api3_create_success($options, $apiRequest['params'], $apiRequest['entity'], 'getoptions');
 432 }
 433
 434 /**
 435  * Provide metadata for this generic action
 436  *
 437  * @param $params
 438  * @param $apiRequest
 439  */
 440 function _civicrm_api3_generic_getoptions_spec(&$params, $apiRequest) {
 441   $params += [
 442     'field' => [
 443       'title' => 'Field name',
 444       'api.required' => 1,
 445       'type' => CRM_Utils_Type::T_STRING,
 446     ],
 447     'context' => [
 448       'title' => 'Context',
 449       'type' => CRM_Utils_Type::T_STRING,
 450       'options' => CRM_Core_DAO::buildOptionsContext(),
 451     ],
 452   ];
 453
 454   // Add available fields if requested
 455   if (array_intersect(['all', 'field'], $apiRequest['params']['options']['get_options'])) {
 456     $fields = civicrm_api3_generic_getfields(['entity' => $apiRequest['entity'], ['params' => ['action' => 'create']]]);
 457     $params['field']['options'] = [];
 458     foreach ($fields['values'] as $name => $field) {
 459       if (isset($field['pseudoconstant']) || CRM_Utils_Array::value('type', $field) == CRM_Utils_Type::T_BOOLEAN) {
 460         $params['field']['options'][$name] = CRM_Utils_Array::value('title', $field, $name);
 461       }
 462     }
 463   }
 464
 465   $entityName = _civicrm_api_get_entity_name_from_camel($apiRequest['entity']);
 466   $getOptionsSpecFunction = '_civicrm_api3_' . $entityName . '_getoptions_spec';
 467
 468   if (function_exists($getOptionsSpecFunction)) {
 469     $getOptionsSpecFunction($params);
 470   }
 471 }
 472
 473 /**
 474  * Get metadata.
 475  *
 476  * Function fills the 'options' array on the metadata returned by getfields if
 477  * 1) the param option 'get_options' is defined - e.g. $params['options']['get_options'] => array('custom_1)
 478  * (this is passed in as the $fieldsToResolve array)
 479  * 2) the field is a pseudoconstant and is NOT an FK
 480  * - the reason for this is that checking / transformation is done on pseudoconstants but
 481  * - if the field is an FK then mysql will enforce the data quality (& we have handling on failure)
 482  * @todo - if may be we should define a 'resolve' key on the pseudoconstant for when these rules are not fine enough
 483  *
 484  * This function is only split out for the purpose of code clarity / comment block documentation
 485  *
 486  * @param array $metadata
 487  *   The array of metadata that will form the result of the getfields function.
 488  * @param array $apiRequest
 489  * @param string $fieldname
 490  *   Field currently being processed.
 491  * @param array $fieldSpec
 492  *   Metadata for that field.
 493  */
 494 function _civicrm_api3_generic_get_metadata_options(&$metadata, $apiRequest, $fieldname, $fieldSpec) {
 495   if (empty($fieldSpec['pseudoconstant']) && empty($fieldSpec['option_group_id'])) {
 496     return;
 497   }
 498
 499   $fieldsToResolve = $apiRequest['params']['options']['get_options'];
 500
 501   if (!empty($metadata[$fieldname]['options']) || (!in_array($fieldname, $fieldsToResolve) && !in_array('all', $fieldsToResolve))) {
 502     return;
 503   }
 504
 505   // Allow caller to specify context
 506   $context = $apiRequest['params']['options']['get_options_context'] ?? NULL;
 507   // Default to api action if it is a supported context.
 508   if (!$context) {
 509     $action = $apiRequest['params']['action'] ?? NULL;
 510     $contexts = CRM_Core_DAO::buildOptionsContext();
 511     if (isset($contexts[$action])) {
 512       $context = $action;
 513     }
 514   }
 515
 516   $options = civicrm_api($apiRequest['entity'], 'getoptions', ['version' => 3, 'field' => $fieldname, 'context' => $context]);
 517   if (isset($options['values']) && is_array($options['values'])) {
 518     $metadata[$fieldname]['options'] = $options['values'];
 519   }
 520 }