api/v3/CustomField.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2019                                |
   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  * This api exposes CiviCRM custom field.
  30  *
  31  * @package CiviCRM_APIv3
  32  */
  33
  34 /**
  35  * Create a 'custom field' within a custom field group.
  36  *
  37  * We also empty the static var in the getfields
  38  * function after deletion so that the field is available for us (getfields manages date conversion
  39  * among other things
  40  *
  41  * @param array $params
  42  *   Array per getfields metadata.
  43  *
  44  * @return array
  45  *   API success array
  46  */
  47 function civicrm_api3_custom_field_create($params) {
  48
  49   // Array created for passing options in params.
  50   if (isset($params['option_values']) && is_array($params['option_values'])) {
  51     $weight = 0;
  52     foreach ($params['option_values'] as $key => $value) {
  53       // Translate simple key/value pairs into full-blown option values
  54       if (!is_array($value)) {
  55         $value = array(
  56           'label' => $value,
  57           'value' => $key,
  58           'is_active' => 1,
  59           'weight' => $weight,
  60         );
  61         $key = $weight++;
  62       }
  63       $params['option_label'][$key] = $value['label'];
  64       $params['option_value'][$key] = $value['value'];
  65       $params['option_status'][$key] = $value['is_active'];
  66       $params['option_weight'][$key] = $value['weight'];
  67     }
  68   }
  69   $values = array();
  70   $customField = CRM_Core_BAO_CustomField::create($params);
  71   _civicrm_api3_object_to_array_unique_fields($customField, $values[$customField->id]);
  72   _civicrm_api3_custom_field_flush_static_caches();
  73   return civicrm_api3_create_success($values, $params, 'CustomField', $customField);
  74 }
  75
  76 /**
  77  * Flush static caches in functions that might have stored available custom fields.
  78  */
  79 function _civicrm_api3_custom_field_flush_static_caches() {
  80   civicrm_api('CustomField', 'getfields', array('version' => 3, 'cache_clear' => 1));
  81   CRM_Core_BAO_UFField::getAvailableFieldsFlat(TRUE);
  82 }
  83
  84 /**
  85  * Adjust Metadata for Create action.
  86  *
  87  * @param array $params
  88  *   Array of parameters determined by getfields.
  89  */
  90 function _civicrm_api3_custom_field_create_spec(&$params) {
  91   $params['label']['api.required'] = 1;
  92   $params['custom_group_id']['api.required'] = 1;
  93   $params['is_active']['api.default'] = 1;
  94   $params['option_values'] = array(
  95     'title' => 'Option Values',
  96     'description' => "Pass an array of options (value => label) to create this field's option values",
  97   );
  98   // TODO: Why expose this to the api at all?
  99   $params['option_type'] = array(
 100     'title' => 'Option Type',
 101     'description' => 'This (boolean) field tells the BAO to create an option group for the field if the field type is appropriate',
 102     'api.default' => 1,
 103     'type' => CRM_Utils_Type::T_BOOLEAN,
 104   );
 105   $params['data_type']['api.default'] = 'String';
 106   $params['is_active']['api.default'] = 1;
 107 }
 108
 109 /**
 110  * Use this API to delete an existing custom field.
 111  *
 112  * @param array $params
 113  *   Array id of the field to be deleted.
 114  *
 115  * @return array
 116  */
 117 function civicrm_api3_custom_field_delete($params) {
 118   $field = new CRM_Core_BAO_CustomField();
 119   $field->id = $params['id'];
 120   $field->find(TRUE);
 121   $customFieldDelete = CRM_Core_BAO_CustomField::deleteField($field);
 122   civicrm_api('CustomField', 'getfields', array('version' => 3, 'cache_clear' => 1));
 123   return $customFieldDelete ? civicrm_api3_create_error('Error while deleting custom field') : civicrm_api3_create_success();
 124 }
 125
 126 /**
 127  * Use this API to get existing custom fields.
 128  *
 129  * @param array $params
 130  *   Array to search on.
 131  *
 132  * @return array
 133  */
 134 function civicrm_api3_custom_field_get($params) {
 135   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
 136 }
 137
 138 /**
 139  * Helper function to validate custom field value.
 140  *
 141  * @deprecated
 142  *
 143  * @param string $fieldName
 144  *   Custom field name (eg: custom_8 ).
 145  * @param mixed $value
 146  *   Field value to be validate.
 147  * @param array $fieldDetails
 148  *   Field Details.
 149  * @param array $errors
 150  *   Collect validation errors.
 151  *
 152  * @return array|NULL
 153  *   Validation errors
 154  * @todo remove this function - not in use but need to review functionality before
 155  * removing as it might be useful in wrapper layer
 156  */
 157 function _civicrm_api3_custom_field_validate_field($fieldName, $value, $fieldDetails, &$errors = array()) {
 158   return NULL;
 159   //see comment block
 160   if (!$value) {
 161     return $errors;
 162   }
 163
 164   $dataType = $fieldDetails['data_type'];
 165   $htmlType = $fieldDetails['html_type'];
 166
 167   switch ($dataType) {
 168     case 'Int':
 169       if (!CRM_Utils_Rule::integer($value)) {
 170         $errors[$fieldName] = 'Invalid integer value for ' . $fieldName;
 171       }
 172       break;
 173
 174     case 'Float':
 175       if (!CRM_Utils_Rule::numeric($value)) {
 176         $errors[$fieldName] = 'Invalid numeric value for ' . $fieldName;
 177       }
 178       break;
 179
 180     case 'Money':
 181       if (!CRM_Utils_Rule::money($value)) {
 182         $errors[$fieldName] = 'Invalid numeric value for ' . $fieldName;
 183       }
 184       break;
 185
 186     case 'Link':
 187       if (!CRM_Utils_Rule::url($value)) {
 188         $errors[$fieldName] = 'Invalid link for ' . $fieldName;
 189       }
 190       break;
 191
 192     case 'Boolean':
 193       if ($value != '1' && $value != '0') {
 194         $errors[$fieldName] = 'Invalid boolean (use 1 or 0) value for ' . $fieldName;
 195       }
 196       break;
 197
 198     case 'Country':
 199       if (empty($value)) {
 200         break;
 201       }
 202       if ($htmlType != 'Multi-Select Country' && is_array($value)) {
 203         $errors[$fieldName] = 'Invalid country for ' . $fieldName;
 204         break;
 205       }
 206
 207       if (!is_array($value)) {
 208         $value = array($value);
 209       }
 210
 211       $query = "SELECT count(*) FROM civicrm_country WHERE id IN (" . implode(',', $value) . ")";
 212       if (CRM_Core_DAO::singleValueQuery($query) < count($value)) {
 213         $errors[$fieldName] = 'Invalid country(s) for ' . $fieldName;
 214       }
 215       break;
 216
 217     case 'StateProvince':
 218       if (empty($value)) {
 219         break;
 220       }
 221
 222       if ($htmlType != 'Multi-Select State/Province' && is_array($value)) {
 223         $errors[$fieldName] = 'Invalid State/Province for ' . $fieldName;
 224         break;
 225       }
 226
 227       if (!is_array($value)) {
 228         $value = array($value);
 229       }
 230
 231       $query = "
 232 SELECT count(*)
 233   FROM civicrm_state_province
 234  WHERE id IN ('" . implode("','", $value) . "')";
 235       if (CRM_Core_DAO::singleValueQuery($query) < count($value)) {
 236         $errors[$fieldName] = 'Invalid State/Province for ' . $fieldName;
 237       }
 238       break;
 239
 240     case 'ContactReference':
 241       //FIX ME
 242       break;
 243   }
 244
 245   if (in_array($htmlType, array(
 246     'Select', 'Multi-Select', 'CheckBox', 'Radio')) &&
 247     !isset($errors[$fieldName])
 248   ) {
 249     $options = CRM_Core_OptionGroup::valuesByID($fieldDetails['option_group_id']);
 250     if (!is_array($value)) {
 251       $value = array($value);
 252     }
 253
 254     $invalidOptions = array_diff($value, array_keys($options));
 255     if (!empty($invalidOptions)) {
 256       $errors[$fieldName] = "Invalid option(s) for field '{$fieldName}': " . implode(',', $invalidOptions);
 257     }
 258   }
 259
 260   return $errors;
 261 }
 262
 263 /**
 264  * CRM-15191 - Hack to ensure the cache gets cleared after updating a custom field.
 265  *
 266  * @param array $params
 267  *   Array per getfields metadata.
 268  *
 269  * @return array
 270  */
 271 function civicrm_api3_custom_field_setvalue($params) {
 272   require_once 'api/v3/Generic/Setvalue.php';
 273   $result = civicrm_api3_generic_setValue(array("entity" => 'CustomField', 'params' => $params));
 274   if (empty($result['is_error'])) {
 275     CRM_Utils_System::flushCache();
 276   }
 277   return $result;
 278 }