api/v3/Generic.php

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