Civi/Api4/Utils/FormattingUtil.php

   1 <?php
   2
   3 /*
   4  +--------------------------------------------------------------------+
   5  | Copyright CiviCRM LLC. All rights reserved.                        |
   6  |                                                                    |
   7  | This work is published under the GNU AGPLv3 license with some      |
   8  | permitted exceptions and without any warranty. For full license    |
   9  | and copyright information, see https://civicrm.org/licensing       |
  10  +--------------------------------------------------------------------+
  11  */
  12
  13 namespace Civi\Api4\Utils;
  14
  15 use Civi\Api4\Query\SqlExpression;
  16
  17 require_once 'api/v3/utils.php';
  18
  19 class FormattingUtil {
  20
  21   /**
  22    * @var string[]
  23    */
  24   public static $pseudoConstantContexts = [
  25     'name' => 'validate',
  26     'abbr' => 'abbreviate',
  27     'label' => 'get',
  28   ];
  29
  30   /**
  31    * @var string[]
  32    */
  33   public static $pseudoConstantSuffixes = ['name', 'abbr', 'label', 'color', 'description', 'icon'];
  34
  35   /**
  36    * Massage values into the format the BAO expects for a write operation
  37    *
  38    * @param array $params
  39    * @param array $fields
  40    * @throws \API_Exception
  41    */
  42   public static function formatWriteParams(&$params, $fields) {
  43     foreach ($fields as $name => $field) {
  44       if (!empty($params[$name])) {
  45         $value =& $params[$name];
  46         // Hack for null values -- see comment below
  47         if ($value === 'null') {
  48           $value = 'Null';
  49         }
  50         self::formatInputValue($value, $name, $field);
  51         // Ensure we have an array for serialized fields
  52         if (!empty($field['serialize'] && !is_array($value))) {
  53           $value = (array) $value;
  54         }
  55       }
  56       /*
  57        * Because of the wacky way that database values are saved we need to format
  58        * some of the values here. In this strange world the string 'null' is used to
  59        * unset values. Hence if we encounter true null we change it to string 'null'.
  60        *
  61        * If we encounter the string 'null' then we assume the user actually wants to
  62        * set the value to string null. However since the string null is reserved for
  63        * unsetting values we must change it. Another quirk of the DB_DataObject is
  64        * that it allows 'Null' to be set, but any other variation of string 'null'
  65        * will be converted to true null, e.g. 'nuLL', 'NUlL' etc. so we change it to
  66        * 'Null'.
  67        */
  68       elseif (array_key_exists($name, $params) && $params[$name] === NULL) {
  69         $params[$name] = 'null';
  70       }
  71     }
  72
  73     \CRM_Utils_API_HTMLInputCoder::singleton()->encodeRow($params);
  74   }
  75
  76   /**
  77    * Transform raw api input to appropriate format for use in a SQL query.
  78    *
  79    * This is used by read AND write actions (Get, Create, Update, Replace)
  80    *
  81    * @param $value
  82    * @param string $fieldName
  83    * @param array $fieldSpec
  84    * @param string $operator (only for 'get' actions)
  85    * @param int $index (for recursive loops)
  86    * @throws \API_Exception
  87    * @throws \CRM_Core_Exception
  88    */
  89   public static function formatInputValue(&$value, $fieldName, $fieldSpec, &$operator = NULL, $index = NULL) {
  90     // Evaluate pseudoconstant suffix
  91     $suffix = strpos($fieldName, ':');
  92     if ($suffix) {
  93       $options = self::getPseudoconstantList($fieldSpec, $fieldName, [], $operator ? 'get' : 'create');
  94       $value = self::replacePseudoconstant($options, $value, TRUE);
  95       return;
  96     }
  97     elseif (is_array($value)) {
  98       $i = 0;
  99       foreach ($value as &$val) {
 100         self::formatInputValue($val, $fieldName, $fieldSpec, $operator, $i++);
 101       }
 102       return;
 103     }
 104     $fk = $fieldSpec['name'] == 'id' ? $fieldSpec['entity'] : $fieldSpec['fk_entity'] ?? NULL;
 105
 106     if ($fk === 'Domain' && $value === 'current_domain') {
 107       $value = \CRM_Core_Config::domainID();
 108     }
 109
 110     if ($fk === 'Contact' && !is_numeric($value)) {
 111       $value = \_civicrm_api3_resolve_contactID($value);
 112       if ('unknown-user' === $value) {
 113         throw new \API_Exception("\"{$fieldSpec['name']}\" \"{$value}\" cannot be resolved to a contact ID", 2002, ['error_field' => $fieldSpec['name'], "type" => "integer"]);
 114       }
 115     }
 116
 117     switch ($fieldSpec['data_type'] ?? NULL) {
 118       case 'Timestamp':
 119         $value = self::formatDateValue('Y-m-d H:i:s', $value, $operator, $index);
 120         break;
 121
 122       case 'Date':
 123         $value = self::formatDateValue('Ymd', $value, $operator, $index);
 124         break;
 125     }
 126
 127     $hic = \CRM_Utils_API_HTMLInputCoder::singleton();
 128     if (is_string($value) && !$hic->isSkippedField($fieldSpec['name'])) {
 129       $value = $hic->encodeValue($value);
 130     }
 131   }
 132
 133   /**
 134    * Parse date expressions.
 135    *
 136    * Expands relative date range expressions, modifying the sql operator if necessary
 137    *
 138    * @param $format
 139    * @param $value
 140    * @param $operator
 141    * @param $index
 142    * @return array|string
 143    */
 144   private static function formatDateValue($format, $value, &$operator = NULL, $index = NULL) {
 145     // Non-relative dates (or if no search operator)
 146     if (!$operator || !array_key_exists($value, \CRM_Core_OptionGroup::values('relative_date_filters'))) {
 147       return date($format, strtotime($value));
 148     }
 149     if (isset($index) && !strstr($operator, 'BETWEEN')) {
 150       throw new \API_Exception("Relative dates cannot be in an array using the $operator operator.");
 151     }
 152     [$dateFrom, $dateTo] = \CRM_Utils_Date::getFromTo($value);
 153     switch ($operator) {
 154       // Convert relative date filters to use BETWEEN/NOT BETWEEN operator
 155       case '=':
 156       case '!=':
 157       case '<>':
 158       case 'LIKE':
 159       case 'NOT LIKE':
 160         $operator = ($operator === '=' || $operator === 'LIKE') ? 'BETWEEN' : 'NOT BETWEEN';
 161         return [self::formatDateValue($format, $dateFrom), self::formatDateValue($format, $dateTo)];
 162
 163       // Less-than or greater-than-equal-to comparisons use the lower value
 164       case '<':
 165       case '>=':
 166         return self::formatDateValue($format, $dateFrom);
 167
 168       // Greater-than or less-than-equal-to comparisons use the higher value
 169       case '>':
 170       case '<=':
 171         return self::formatDateValue($format, $dateTo);
 172
 173       // For BETWEEN expressions, we are already inside a loop of the 2 values, so give the lower value if index=0, higher value if index=1
 174       case 'BETWEEN':
 175       case 'NOT BETWEEN':
 176         return self::formatDateValue($format, $index ? $dateTo : $dateFrom);
 177
 178       default:
 179         throw new \API_Exception("Relative dates cannot be used with the $operator operator.");
 180     }
 181   }
 182
 183   /**
 184    * Unserialize raw DAO values and convert to correct type
 185    *
 186    * @param array $results
 187    * @param array $fields
 188    * @param string $action
 189    * @param array $selectAliases
 190    * @throws \API_Exception
 191    * @throws \CRM_Core_Exception
 192    */
 193   public static function formatOutputValues(&$results, $fields, $action = 'get', $selectAliases = []) {
 194     $fieldOptions = [];
 195     foreach ($results as &$result) {
 196       $contactTypePaths = [];
 197       foreach ($result as $key => $value) {
 198         $fieldExpr = SqlExpression::convert($selectAliases[$key] ?? $key);
 199         $fieldName = \CRM_Utils_Array::first($fieldExpr->getFields());
 200         $baseName = $fieldName ? \CRM_Utils_Array::first(explode(':', $fieldName)) : NULL;
 201         $field = $fields[$fieldName] ?? $fields[$baseName] ?? NULL;
 202         $dataType = $field['data_type'] ?? ($fieldName == 'id' ? 'Integer' : NULL);
 203         // Allow Sql Functions to do special formatting and/or alter the $dataType
 204         if (method_exists($fieldExpr, 'formatOutputValue') && is_string($value)) {
 205           $result[$key] = $value = $fieldExpr->formatOutputValue($value, $dataType);
 206         }
 207         if (!empty($field['output_formatters'])) {
 208           self::applyFormatters($result, $fieldName, $field, $value);
 209           $dataType = NULL;
 210         }
 211         // Evaluate pseudoconstant suffixes
 212         $suffix = strrpos($fieldName, ':');
 213         if ($suffix) {
 214           $fieldOptions[$fieldName] = $fieldOptions[$fieldName] ?? self::getPseudoconstantList($field, $fieldName, $result, $action);
 215           $dataType = NULL;
 216         }
 217         if ($fieldExpr->supportsExpansion) {
 218           if (!empty($field['serialize']) && is_string($value)) {
 219             $value = \CRM_Core_DAO::unSerializeField($value, $field['serialize']);
 220           }
 221           if (isset($fieldOptions[$fieldName])) {
 222             $value = self::replacePseudoconstant($fieldOptions[$fieldName], $value);
 223           }
 224         }
 225         // Keep track of contact types for self::contactFieldsToRemove
 226         if ($value && isset($field['entity']) && $field['entity'] === 'Contact' && $field['name'] === 'contact_type') {
 227           $prefix = strrpos($fieldName, '.');
 228           $contactTypePaths[$prefix ? substr($fieldName, 0, $prefix + 1) : ''] = $value;
 229         }
 230         $result[$key] = self::convertDataType($value, $dataType);
 231       }
 232       // Remove inapplicable contact fields
 233       foreach ($contactTypePaths as $prefix => $contactType) {
 234         \CRM_Utils_Array::remove($result, self::contactFieldsToRemove($contactType, $prefix));
 235       }
 236     }
 237   }
 238
 239   /**
 240    * Retrieves pseudoconstant option list for a field.
 241    *
 242    * @param array $field
 243    * @param string $fieldAlias
 244    *   Field path plus pseudoconstant suffix, e.g. 'contact.employer_id.contact_sub_type:label'
 245    * @param array $params
 246    *   Other values for this object
 247    * @param string $action
 248    * @return array
 249    * @throws \API_Exception
 250    */
 251   public static function getPseudoconstantList(array $field, string $fieldAlias, $params = [], $action = 'get') {
 252     [$fieldPath, $valueType] = explode(':', $fieldAlias);
 253     $context = self::$pseudoConstantContexts[$valueType] ?? NULL;
 254     // For create actions, only unique identifiers can be used.
 255     // For get actions any valid suffix is ok.
 256     if (($action === 'create' && !$context) || !in_array($valueType, self::$pseudoConstantSuffixes, TRUE)) {
 257       throw new \API_Exception('Illegal expression');
 258     }
 259     $baoName = $context ? CoreUtil::getBAOFromApiName($field['entity']) : NULL;
 260     // Use BAO::buildOptions if possible
 261     if ($baoName) {
 262       $fieldName = empty($field['custom_field_id']) ? $field['name'] : 'custom_' . $field['custom_field_id'];
 263       $options = $baoName::buildOptions($fieldName, $context, self::filterByPrefix($params, $fieldPath, $field['name']));
 264     }
 265     // Fallback for option lists that exist in the api but not the BAO
 266     if (!isset($options) || $options === FALSE) {
 267       $options = civicrm_api4($field['entity'], 'getFields', ['action' => $action, 'loadOptions' => ['id', $valueType], 'where' => [['name', '=', $field['name']]]])[0]['options'] ?? NULL;
 268       $options = $options ? array_column($options, $valueType, 'id') : $options;
 269     }
 270     if (is_array($options)) {
 271       return $options;
 272     }
 273     throw new \API_Exception("No option list found for '{$field['name']}'");
 274   }
 275
 276   /**
 277    * Replaces value (or an array of values) with options from a pseudoconstant list.
 278    *
 279    * The direction of lookup defaults to transforming ids to option values for api output;
 280    * for api input, set $reverse = TRUE to transform option values to ids.
 281    *
 282    * @param array $options
 283    * @param string|string[] $value
 284    * @param bool $reverse
 285    *   Is this a reverse lookup (for transforming input instead of output)
 286    * @return array|mixed|null
 287    */
 288   public static function replacePseudoconstant($options, $value, $reverse = FALSE) {
 289     $matches = [];
 290     foreach ((array) $value as $val) {
 291       if (!$reverse && isset($options[$val])) {
 292         $matches[] = $options[$val];
 293       }
 294       elseif ($reverse && array_search($val, $options) !== FALSE) {
 295         $matches[] = array_search($val, $options);
 296       }
 297     }
 298     return is_array($value) ? $matches : $matches[0] ?? NULL;
 299   }
 300
 301   /**
 302    * Apply a field's output_formatters callback functions
 303    *
 304    * @param array $result
 305    * @param string $fieldPath
 306    * @param array $field
 307    * @param mixed $value
 308    */
 309   private static function applyFormatters(array $result, string $fieldPath, array $field, &$value) {
 310     $row = self::filterByPrefix($result, $fieldPath, $field['name']);
 311
 312     foreach ($field['output_formatters'] as $formatter) {
 313       $formatter($value, $row, $field);
 314     }
 315   }
 316
 317   /**
 318    * @param mixed $value
 319    * @param string $dataType
 320    * @return mixed
 321    */
 322   public static function convertDataType($value, $dataType) {
 323     if (isset($value) && $dataType) {
 324       if (is_array($value)) {
 325         foreach ($value as $key => $val) {
 326           $value[$key] = self::convertDataType($val, $dataType);
 327         }
 328         return $value;
 329       }
 330
 331       switch ($dataType) {
 332         case 'Boolean':
 333           return (bool) $value;
 334
 335         case 'Integer':
 336           return (int) $value;
 337
 338         case 'Money':
 339         case 'Float':
 340           return (float) $value;
 341       }
 342     }
 343     return $value;
 344   }
 345
 346   /**
 347    * Lists all field names (including suffixed variants) that should be removed for a given contact type.
 348    *
 349    * @param string $contactType
 350    *   Individual|Organization|Household
 351    * @param string $prefix
 352    *   Path at which these fields are found, e.g. "address.contact."
 353    * @return array
 354    */
 355   public static function contactFieldsToRemove($contactType, $prefix) {
 356     if (!isset(\Civi::$statics[__CLASS__][__FUNCTION__][$contactType])) {
 357       \Civi::$statics[__CLASS__][__FUNCTION__][$contactType] = [];
 358       foreach (\CRM_Contact_DAO_Contact::fields() as $field) {
 359         if (!empty($field['contactType']) && $field['contactType'] != $contactType) {
 360           \Civi::$statics[__CLASS__][__FUNCTION__][$contactType][] = $field['name'];
 361           // Include suffixed variants like prefix_id:label
 362           if (!empty($field['pseudoconstant'])) {
 363             foreach (self::$pseudoConstantSuffixes as $suffix) {
 364               \Civi::$statics[__CLASS__][__FUNCTION__][$contactType][] = $field['name'] . ':' . $suffix;
 365             }
 366           }
 367         }
 368       }
 369     }
 370     // Add prefix paths
 371     return array_map(function($name) use ($prefix) {
 372       return $prefix . $name;
 373     }, \Civi::$statics[__CLASS__][__FUNCTION__][$contactType]);
 374   }
 375
 376   /**
 377    * Given a field belonging to either the main entity or a joined entity,
 378    * and a values array of [path => value], this returns all values which share the same root path.
 379    *
 380    * Works by filtering array keys to only include those with the same prefix as a given field,
 381    * stripping them of that prefix.
 382    *
 383    * Ex:
 384    * ```
 385    * $values = [
 386    *   'first_name' => 'a',
 387    *   'middle_name' => 'b',
 388    *   'related_contact.first_name' => 'c',
 389    *   'related_contact.last_name' => 'd',
 390    *   'activity.subject' => 'e',
 391    * ]
 392    * $fieldPath = 'related_contact.id'
 393    * $fieldName = 'id'
 394    *
 395    * filterByPrefix($values, $fieldPath, $fieldName)
 396    * returns [
 397    *   'first_name' => 'c',
 398    *   'last_name' => 'd',
 399    * ]
 400    * ```
 401    *
 402    * @param array $values
 403    * @param string $fieldPath
 404    * @param string $fieldName
 405    * @return array
 406    */
 407   public static function filterByPrefix(array $values, string $fieldPath, string $fieldName): array {
 408     $filtered = [];
 409     $prefix = substr($fieldPath, 0, strpos($fieldPath, $fieldName));
 410     foreach ($values as $key => $val) {
 411       if (!$prefix || strpos($key, $prefix) === 0) {
 412         $filtered[substr($key, strlen($prefix))] = $val;
 413       }
 414     }
 415     return $filtered;
 416   }
 417
 418 }