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