api/v3/Generic.php

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