api/v3/CustomValue.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  * This api exposes CiviCRM custom value.
  14  *
  15  * @package CiviCRM_APIv3
  16  */
  17
  18 /**
  19  * Sets custom values for an entity.
  20  *
  21  * @param array $params
  22  *   Expected keys are in format custom_fieldID:recordID or custom_groupName:fieldName:recordID.
  23  *
  24  * @example:
  25  * ```
  26  *   // entity ID. You do not need to specify entity type, we figure it out based on the fields you're using
  27  *   'entity_id' => 123,
  28  *   // (omitting :id) inserts or updates a field in a single-valued group
  29  *   'custom_6' => 'foo',
  30  *   // custom_24 is checkbox or multiselect, so pass items as an array
  31  *   'custom_24' => array('bar', 'baz'),
  32  *   // in this case custom_33 is part of a multi-valued group, and we're updating record id 5
  33  *   'custom_33:5' => value,
  34  *   // inserts new record in multi-valued group
  35  *   'custom_33:-1' => value,
  36  *   // inserts another new record in multi-valued group
  37  *   'custom_33:-2' => value,
  38  *   // you can use group_name:field_name instead of ID
  39  *   'custom_some_group:my_field' => 'myinfo',
  40  *   // updates record ID 8 in my_other_field in multi-valued some_big_group
  41  *   'custom_some_big_group:my_other_field:8' => 'myinfo',
  42  * ```
  43  *
  44  * @throws Exception
  45  * @return array
  46  *   ['values' => TRUE] or ['is_error' => 1, 'error_message' => 'what went wrong']
  47  */
  48 function civicrm_api3_custom_value_create($params) {
  49   // @todo it's not clear where the entity_table is used as  CRM_Core_BAO_CustomValueTable::setValues($create)
  50   // didn't seem to use it
  51   // so not clear if it's relevant
  52   if (!empty($params['entity_table']) && substr($params['entity_table'], 0, 7) == 'civicrm') {
  53     $params['entity_table'] = substr($params['entity_table'], 8, 7);
  54   }
  55   $create = ['entityID' => $params['entity_id']];
  56   // Translate names and
  57   //Convert arrays to multi-value strings
  58   $sp = CRM_Core_DAO::VALUE_SEPARATOR;
  59   foreach ($params as $id => $param) {
  60     if (is_array($param)) {
  61       $param = $sp . implode($sp, $param) . $sp;
  62     }
  63     list($c, $id) = CRM_Utils_System::explode('_', $id, 2);
  64     if ($c != 'custom') {
  65       continue;
  66     }
  67     list($i, $n, $x) = CRM_Utils_System::explode(':', $id, 3);
  68     if (is_numeric($i)) {
  69       $key = $i;
  70       $x = $n;
  71     }
  72     else {
  73       // Lookup names if ID was not supplied
  74       $key = CRM_Core_BAO_CustomField::getCustomFieldID($n, $i);
  75       if (!$key) {
  76         continue;
  77       }
  78     }
  79     if ($x && is_numeric($x)) {
  80       $key .= '_' . $x;
  81     }
  82     $create['custom_' . $key] = $param;
  83   }
  84   $result = CRM_Core_BAO_CustomValueTable::setValues($create);
  85   if ($result['is_error']) {
  86     throw new Exception($result['error_message']);
  87   }
  88   return civicrm_api3_create_success(TRUE, $params, 'CustomValue');
  89 }
  90
  91 /**
  92  * Adjust Metadata for Create action.
  93  *
  94  * The metadata is used for setting defaults, documentation & validation.
  95  *
  96  * @param array $params
  97  *   Array of parameters determined by getfields.
  98  */
  99 function _civicrm_api3_custom_value_create_spec(&$params) {
 100   $params['entity_id']['api.required'] = 1;
 101   $params['entity_id']['title'] = 'Entity ID';
 102 }
 103
 104 /**
 105  * Use this API to get existing custom values for an entity.
 106  *
 107  * @param array $params
 108  *   Array specifying the entity_id.
 109  *   Optionally include entity_type param, i.e. 'entity_type' => 'Activity'
 110  *   If no entity_type is supplied, it will be determined based on the fields you request.
 111  *   If no entity_type is supplied and no fields are specified, 'Contact' will be assumed.
 112  *   Optionally include the desired custom data to be fetched (or else all custom data for this entity will be returned)
 113  *   Example: 'entity_id' => 123, 'return.custom_6' => 1, 'return.custom_33' => 1
 114  *   If you do not know the ID, you may use group name : field name, for example 'return.foo_stuff:my_field' => 1
 115  *
 116  * @throws API_Exception
 117  * @return array
 118  */
 119 function civicrm_api3_custom_value_get($params) {
 120
 121   $getParams = [
 122     'entityID' => $params['entity_id'],
 123     'entityType' => CRM_Utils_Array::value('entity_table', $params, ''),
 124   ];
 125   if (strstr($getParams['entityType'], 'civicrm_')) {
 126     $getParams['entityType'] = ucfirst(substr($getParams['entityType'], 8));
 127   }
 128   unset($params['entity_id'], $params['entity_table']);
 129   foreach ($params as $id => $param) {
 130     if ($param && substr($id, 0, 6) == 'return') {
 131       $returnVal = $param;
 132       if (!empty(substr($id, 7))) {
 133         $returnVal = substr($id, 7);
 134       }
 135       if (!is_array($returnVal)) {
 136         $returnVal = explode(',', $returnVal);
 137       }
 138       foreach ($returnVal as $value) {
 139         list($c, $i) = CRM_Utils_System::explode('_', $value, 2);
 140         if ($c == 'custom' && is_numeric($i)) {
 141           $names['custom_' . $i] = 'custom_' . $i;
 142           $fldId = $i;
 143         }
 144         else {
 145           // Lookup names if ID was not supplied
 146           list($group, $field) = CRM_Utils_System::explode(':', $value, 2);
 147           $fldId = CRM_Core_BAO_CustomField::getCustomFieldID($field, $group);
 148           if (!$fldId) {
 149             continue;
 150           }
 151           $names['custom_' . $fldId] = 'custom_' . $i;
 152         }
 153         $getParams['custom_' . $fldId] = 1;
 154       }
 155     }
 156   }
 157
 158   $result = CRM_Core_BAO_CustomValueTable::getValues($getParams);
 159
 160   if ($result['is_error']) {
 161     if ($result['error_message'] == "No values found for the specified entity ID and custom field(s).") {
 162       $values = [];
 163       return civicrm_api3_create_success($values, $params, 'CustomValue');
 164     }
 165     else {
 166       throw new API_Exception($result['error_message']);
 167     }
 168   }
 169   else {
 170     $entity_id = $result['entityID'];
 171     unset($result['is_error'], $result['entityID']);
 172     // Convert multi-value strings to arrays
 173     $sp = CRM_Core_DAO::VALUE_SEPARATOR;
 174     foreach ($result as $id => $value) {
 175       if (strpos($value, $sp) !== FALSE) {
 176         $value = explode($sp, trim($value, $sp));
 177       }
 178
 179       $idArray = explode('_', $id);
 180       if ($idArray[0] != 'custom') {
 181         continue;
 182       }
 183       $fieldNumber = $idArray[1];
 184       $customFieldInfo = CRM_Core_BAO_CustomField::getNameFromID($fieldNumber);
 185       $info = array_pop($customFieldInfo);
 186       // id is the index for returned results
 187
 188       if (empty($idArray[2])) {
 189         $n = 0;
 190         $id = $fieldNumber;
 191       }
 192       else {
 193         $n = $idArray[2];
 194         $id = $fieldNumber . "." . $idArray[2];
 195       }
 196       if (!empty($params['format.field_names'])) {
 197         $id = $info['field_name'];
 198       }
 199       else {
 200         $id = $fieldNumber;
 201       }
 202       $values[$id]['entity_id'] = $getParams['entityID'];
 203       if (!empty($getParams['entityType'])) {
 204         $values[$id]['entity_table'] = $getParams['entityType'];
 205       }
 206       //set 'latest' -useful for multi fields but set for single for consistency
 207       $values[$id]['latest'] = $value;
 208       $values[$id]['id'] = $id;
 209       $values[$id][$n] = $value;
 210     }
 211     return civicrm_api3_create_success($values, $params, 'CustomValue');
 212   }
 213 }
 214
 215 /**
 216  * Adjust Metadata for Get action.
 217  *
 218  * The metadata is used for setting defaults, documentation & validation.
 219  *
 220  * @param array $params
 221  *   Array of parameters determined by getfields.
 222  */
 223 function _civicrm_api3_custom_value_get_spec(&$params) {
 224   $params['entity_id']['api.required'] = 1;
 225   $params['entity_id']['title'] = 'Entity ID';
 226 }
 227
 228 /**
 229  * CustomValue.gettree API specification
 230  *
 231  * @param array $spec description of fields supported by this API call
 232  *
 233  * @throws \CiviCRM_API3_Exception
 234  */
 235 function _civicrm_api3_custom_value_gettree_spec(&$spec) {
 236   $spec['entity_id'] = [
 237     'title' => 'Entity Id',
 238     'description' => 'Id of entity',
 239     'type' => CRM_Utils_Type::T_INT,
 240     'api.required' => 1,
 241   ];
 242   $entities = civicrm_api3('Entity', 'get');
 243   $entities = array_diff($entities['values'], $entities['deprecated']);
 244   $spec['entity_type'] = [
 245     'title' => 'Entity Type',
 246     'description' => 'API name of entity type, e.g. "Contact"',
 247     'type' => CRM_Utils_Type::T_STRING,
 248     'api.required' => 1,
 249     'options' => array_combine($entities, $entities),
 250   ];
 251   // Return params for custom group, field & value
 252   foreach (CRM_Core_DAO_CustomGroup::fields() as $field) {
 253     $name = 'custom_group.' . $field['name'];
 254     $spec[$name] = ['name' => $name] + $field;
 255   }
 256   foreach (CRM_Core_DAO_CustomField::fields() as $field) {
 257     $name = 'custom_field.' . $field['name'];
 258     $spec[$name] = ['name' => $name] + $field;
 259   }
 260   $spec['custom_value.id'] = [
 261     'title' => 'Custom Value Id',
 262     'description' => 'Id of record in custom value table',
 263     'type' => CRM_Utils_Type::T_INT,
 264   ];
 265   $spec['custom_value.data'] = [
 266     'title' => 'Custom Value (Raw)',
 267     'description' => 'Raw value as stored in the database',
 268     'type' => CRM_Utils_Type::T_STRING,
 269   ];
 270   $spec['custom_value.display'] = [
 271     'title' => 'Custom Value (Formatted)',
 272     'description' => 'Custom value formatted for display',
 273     'type' => CRM_Utils_Type::T_STRING,
 274   ];
 275 }
 276
 277 /**
 278  * CustomValue.gettree API
 279  *
 280  * @param array $params
 281  *
 282  * @return array API result
 283  * @throws \API_Exception
 284  * @throws \CRM_Core_Exception
 285  * @throws \CiviCRM_API3_Exception
 286  */
 287 function civicrm_api3_custom_value_gettree($params) {
 288   $ret = [];
 289   $options = _civicrm_api3_get_options_from_params($params);
 290   $toReturn = [
 291     'custom_group' => [],
 292     'custom_field' => [],
 293     'custom_value' => [],
 294   ];
 295   foreach (array_keys($options['return']) as $r) {
 296     list($type, $field) = explode('.', $r);
 297     if (isset($toReturn[$type])) {
 298       $toReturn[$type][] = $field;
 299     }
 300   }
 301   // We must have a name if not indexing sequentially
 302   if (empty($params['sequential']) && $toReturn['custom_field']) {
 303     $toReturn['custom_field'][] = 'name';
 304   }
 305   switch ($params['entity_type']) {
 306     case 'Contact':
 307       $ret = ['entityType' => 'contact_type', 'subTypes' => 'contact_sub_type'];
 308       break;
 309
 310     case 'Activity':
 311     case 'Campaign':
 312     case 'Case':
 313     case 'Contribution':
 314     case 'Event':
 315     case 'Grant':
 316     case 'Membership':
 317     case 'Relationship':
 318       $ret = ['subTypes' => strtolower($params['entity_type']) . '_type_id'];
 319       break;
 320
 321     case 'Participant':
 322       // todo
 323   }
 324   $treeParams = [
 325     'entityType' => $params['entity_type'],
 326     'subTypes' => [],
 327     'subName' => NULL,
 328   ];
 329   // Fetch entity data for custom group type/sub-type
 330   // Also verify access permissions (api3 will throw an exception if permission denied)
 331   if ($ret || !empty($params['check_permissions'])) {
 332     $entityData = civicrm_api3($params['entity_type'], 'getsingle', [
 333       'id' => $params['entity_id'],
 334       'check_permissions' => !empty($params['check_permissions']),
 335       'return' => array_merge(['id'], array_values($ret)),
 336     ]);
 337     foreach ($ret as $param => $key) {
 338       if (isset($entityData[$key])) {
 339         $treeParams[$param] = $entityData[$key];
 340       }
 341     }
 342   }
 343   $tree = CRM_Core_BAO_CustomGroup::getTree($treeParams['entityType'], $toReturn, $params['entity_id'], NULL, $treeParams['subTypes'], $treeParams['subName'], TRUE, NULL, FALSE, CRM_Utils_Array::value('check_permissions', $params, TRUE));
 344   unset($tree['info']);
 345   $result = [];
 346   foreach ($tree as $group) {
 347     $result[$group['name']] = [];
 348     $groupToReturn = $toReturn['custom_group'] ? $toReturn['custom_group'] : array_keys($group);
 349     foreach ($groupToReturn as $item) {
 350       $result[$group['name']][$item] = $group[$item] ?? NULL;
 351     }
 352     $result[$group['name']]['fields'] = [];
 353     foreach ($group['fields'] as $fieldInfo) {
 354       $field = ['value' => NULL];
 355       $fieldToReturn = $toReturn['custom_field'] ? $toReturn['custom_field'] : array_keys($fieldInfo);
 356       foreach ($fieldToReturn as $item) {
 357         $field[$item] = $fieldInfo[$item] ?? NULL;
 358       }
 359       unset($field['customValue']);
 360       if (!empty($fieldInfo['customValue'])) {
 361         $field['value'] = CRM_Utils_Array::first($fieldInfo['customValue']);
 362         if (!$toReturn['custom_value'] || in_array('display', $toReturn['custom_value'])) {
 363           $field['value']['display'] = CRM_Core_BAO_CustomField::displayValue($field['value']['data'], $fieldInfo);
 364         }
 365         foreach (array_keys($field['value']) as $key) {
 366           if ($toReturn['custom_value'] && !in_array($key, $toReturn['custom_value'])) {
 367             unset($field['value'][$key]);
 368           }
 369         }
 370       }
 371       if (empty($params['sequential'])) {
 372         $result[$group['name']]['fields'][$fieldInfo['name']] = $field;
 373       }
 374       else {
 375         $result[$group['name']]['fields'][] = $field;
 376       }
 377     }
 378   }
 379   return civicrm_api3_create_success($result, $params, 'CustomValue', 'gettree');
 380 }
 381
 382 /**
 383  * CustomValue.getdisplayvalue API specification
 384  *
 385  * @param array $spec description of fields supported by this API call
 386  */
 387 function _civicrm_api3_custom_value_getdisplayvalue_spec(&$spec) {
 388   $spec['entity_id'] = [
 389     'title' => 'Entity Id',
 390     'description' => 'Id of entity',
 391     'type' => CRM_Utils_Type::T_INT,
 392     'api.required' => 1,
 393   ];
 394   $spec['custom_field_id'] = [
 395     'title' => 'Custom Field ID',
 396     'description' => 'Id of custom field',
 397     'type' => CRM_Utils_Type::T_INT,
 398     'api.required' => 1,
 399   ];
 400   $spec['custom_field_value'] = [
 401     'title' => 'Custom Field value',
 402     'description' => 'Specify the value of the custom field to return as displayed value',
 403     'type' => CRM_Utils_Type::T_STRING,
 404     'api.required' => 0,
 405   ];
 406 }
 407
 408 /**
 409  * CustomValue.getdisplayvalue API
 410  *
 411  * @param array $params
 412  *
 413  * @return array API result
 414  * @throws \CiviCRM_API3_Exception
 415  */
 416 function civicrm_api3_custom_value_getdisplayvalue($params) {
 417   if (empty($params['custom_field_value'])) {
 418     $params['custom_field_value'] = civicrm_api3('CustomValue', 'getsingle', [
 419       'return' => ["custom_{$params['custom_field_id']}"],
 420       'entity_id' => $params['entity_id'],
 421     ]);
 422     $params['custom_field_value'] = $params['custom_field_value']['latest'];
 423   }
 424   $values[$params['custom_field_id']]['display'] = CRM_Core_BAO_CustomField::displayValue($params['custom_field_value'], $params['custom_field_id'], CRM_Utils_Array::value('entity_id', $params));
 425   $values[$params['custom_field_id']]['raw'] = $params['custom_field_value'];
 426   return civicrm_api3_create_success($values, $params, 'CustomValue', 'getdisplayvalue');
 427 }