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 /**
  14  *
  15  * @package CRM
  16  * @copyright CiviCRM LLC https://civicrm.org/licensing
  17  * $Id$
  18  *
  19  */
  20
  21
  22 namespace Civi\Api4\Utils;
  23
  24 require_once 'api/v3/utils.php';
  25
  26 class FormattingUtil {
  27
  28   public static $pseudoConstantContexts = [
  29     'name' => 'validate',
  30     'abbr' => 'abbreviate',
  31     'label' => 'get',
  32   ];
  33
  34   /**
  35    * Massage values into the format the BAO expects for a write operation
  36    *
  37    * @param array $params
  38    * @param array $fields
  39    * @throws \API_Exception
  40    */
  41   public static function formatWriteParams(&$params, $fields) {
  42     foreach ($fields as $name => $field) {
  43       if (!empty($params[$name])) {
  44         $value =& $params[$name];
  45         // Hack for null values -- see comment below
  46         if ($value === 'null') {
  47           $value = 'Null';
  48         }
  49         self::formatInputValue($value, $name, $field);
  50         // Ensure we have an array for serialized fields
  51         if (!empty($field['serialize'] && !is_array($value))) {
  52           $value = (array) $value;
  53         }
  54       }
  55       /*
  56        * Because of the wacky way that database values are saved we need to format
  57        * some of the values here. In this strange world the string 'null' is used to
  58        * unset values. Hence if we encounter true null we change it to string 'null'.
  59        *
  60        * If we encounter the string 'null' then we assume the user actually wants to
  61        * set the value to string null. However since the string null is reserved for
  62        * unsetting values we must change it. Another quirk of the DB_DataObject is
  63        * that it allows 'Null' to be set, but any other variation of string 'null'
  64        * will be converted to true null, e.g. 'nuLL', 'NUlL' etc. so we change it to
  65        * 'Null'.
  66        */
  67       elseif (array_key_exists($name, $params) && $params[$name] === NULL) {
  68         $params[$name] = 'null';
  69       }
  70     }
  71
  72     \CRM_Utils_API_HTMLInputCoder::singleton()->encodeRow($params);
  73   }
  74
  75   /**
  76    * Transform raw api input to appropriate format for use in a SQL query.
  77    *
  78    * This is used by read AND write actions (Get, Create, Update, Replace)
  79    *
  80    * @param $value
  81    * @param string $fieldName
  82    * @param array $fieldSpec
  83    * @throws \API_Exception
  84    */
  85   public static function formatInputValue(&$value, $fieldName, $fieldSpec) {
  86     // Evaluate pseudoconstant suffix
  87     $suffix = strpos($fieldName, ':');
  88     if ($suffix) {
  89       $options = self::getPseudoconstantList($fieldSpec['entity'], $fieldSpec['name'], substr($fieldName, $suffix + 1));
  90       $value = self::replacePseudoconstant($options, $value, TRUE);
  91     }
  92     elseif (is_array($value)) {
  93       foreach ($value as &$val) {
  94         self::formatInputValue($val, $fieldName, $fieldSpec);
  95       }
  96       return;
  97     }
  98     $fk = $fieldSpec['name'] == 'id' ? $fieldSpec['entity'] : $fieldSpec['fk_entity'] ?? NULL;
  99
 100     if ($fk === 'Domain' && $value === 'current_domain') {
 101       $value = \CRM_Core_Config::domainID();
 102     }
 103
 104     if ($fk === 'Contact' && !is_numeric($value)) {
 105       $value = \_civicrm_api3_resolve_contactID($value);
 106       if ('unknown-user' === $value) {
 107         throw new \API_Exception("\"{$fieldSpec['name']}\" \"{$value}\" cannot be resolved to a contact ID", 2002, ['error_field' => $fieldSpec['name'], "type" => "integer"]);
 108       }
 109     }
 110
 111     switch ($fieldSpec['data_type'] ?? NULL) {
 112       case 'Timestamp':
 113         $value = date('Y-m-d H:i:s', strtotime($value));
 114         break;
 115
 116       case 'Date':
 117         $value = date('Ymd', strtotime($value));
 118         break;
 119     }
 120
 121     $hic = \CRM_Utils_API_HTMLInputCoder::singleton();
 122     if (!$hic->isSkippedField($fieldSpec['name'])) {
 123       $value = $hic->encodeValue($value);
 124     }
 125   }
 126
 127   /**
 128    * Unserialize raw DAO values and convert to correct type
 129    *
 130    * @param array $results
 131    * @param array $fields
 132    * @param string $entity
 133    * @param string $action
 134    * @throws \API_Exception
 135    * @throws \CRM_Core_Exception
 136    */
 137   public static function formatOutputValues(&$results, $fields, $entity, $action = 'get') {
 138     $fieldOptions = [];
 139     foreach ($results as &$result) {
 140       $contactTypePaths = [];
 141       foreach ($result as $fieldExpr => $value) {
 142         $field = $fields[$fieldExpr] ?? NULL;
 143         $dataType = $field['data_type'] ?? ($fieldExpr == 'id' ? 'Integer' : NULL);
 144         if ($field) {
 145           // Evaluate pseudoconstant suffixes
 146           $suffix = strrpos($fieldExpr, ':');
 147           if ($suffix) {
 148             $fieldName = empty($field['custom_field_id']) ? $field['name'] : 'custom_' . $field['custom_field_id'];
 149             $fieldOptions[$fieldExpr] = $fieldOptions[$fieldExpr] ?? self::getPseudoconstantList($field['entity'], $fieldName, substr($fieldExpr, $suffix + 1), $result, $action);
 150             $dataType = NULL;
 151           }
 152           if (!empty($field['serialize'])) {
 153             if (is_string($value)) {
 154               $value = \CRM_Core_DAO::unSerializeField($value, $field['serialize']);
 155             }
 156           }
 157           if (isset($fieldOptions[$fieldExpr])) {
 158             $value = self::replacePseudoconstant($fieldOptions[$fieldExpr], $value);
 159           }
 160           // Keep track of contact types for self::contactFieldsToRemove
 161           if ($value && isset($field['entity']) && $field['entity'] === 'Contact' && $field['name'] === 'contact_type') {
 162             $prefix = strrpos($fieldExpr, '.');
 163             $contactTypePaths[$prefix ? substr($fieldExpr, 0, $prefix + 1) : ''] = $value;
 164           }
 165         }
 166         $result[$fieldExpr] = self::convertDataType($value, $dataType);
 167       }
 168       // Remove inapplicable contact fields
 169       foreach ($contactTypePaths as $prefix => $contactType) {
 170         \CRM_Utils_Array::remove($result, self::contactFieldsToRemove($contactType, $prefix));
 171       }
 172     }
 173   }
 174
 175   /**
 176    * Retrieves pseudoconstant option list for a field.
 177    *
 178    * @param string $entity
 179    *   Name of api entity
 180    * @param string $fieldName
 181    * @param string $valueType
 182    *   name|label|abbr from self::$pseudoConstantContexts
 183    * @param array $params
 184    *   Other values for this object
 185    * @param string $action
 186    * @return array
 187    * @throws \API_Exception
 188    */
 189   public static function getPseudoconstantList($entity, $fieldName, $valueType, $params = [], $action = 'get') {
 190     $context = self::$pseudoConstantContexts[$valueType] ?? NULL;
 191     if (!$context) {
 192       throw new \API_Exception('Illegal expression');
 193     }
 194     $baoName = CoreUtil::getBAOFromApiName($entity);
 195     // Use BAO::buildOptions if possible
 196     if ($baoName) {
 197       $options = $baoName::buildOptions($fieldName, $context, $params);
 198     }
 199     // Fallback for option lists that exist in the api but not the BAO - note: $valueType gets ignored here
 200     if (!isset($options) || $options === FALSE) {
 201       $options = civicrm_api4($entity, 'getFields', ['action' => $action, 'loadOptions' => TRUE, 'where' => [['name', '=', $fieldName]]])[0]['options'] ?? NULL;
 202     }
 203     if (is_array($options)) {
 204       return $options;
 205     }
 206     throw new \API_Exception("No option list found for '$fieldName'");
 207   }
 208
 209   /**
 210    * Replaces value (or an array of values) with options from a pseudoconstant list.
 211    *
 212    * The direction of lookup defaults to transforming ids to option values for api output;
 213    * for api input, set $reverse = TRUE to transform option values to ids.
 214    *
 215    * @param array $options
 216    * @param string|string[] $value
 217    * @param bool $reverse
 218    *   Is this a reverse lookup (for transforming input instead of output)
 219    * @return array|mixed|null
 220    */
 221   public static function replacePseudoconstant($options, $value, $reverse = FALSE) {
 222     $matches = [];
 223     foreach ((array) $value as $val) {
 224       if (!$reverse && isset($options[$val])) {
 225         $matches[] = $options[$val];
 226       }
 227       elseif ($reverse && array_search($val, $options) !== FALSE) {
 228         $matches[] = array_search($val, $options);
 229       }
 230     }
 231     return is_array($value) ? $matches : $matches[0] ?? NULL;
 232   }
 233
 234   /**
 235    * @param mixed $value
 236    * @param string $dataType
 237    * @return mixed
 238    */
 239   public static function convertDataType($value, $dataType) {
 240     if (isset($value) && $dataType) {
 241       if (is_array($value)) {
 242         foreach ($value as $key => $val) {
 243           $value[$key] = self::convertDataType($val, $dataType);
 244         }
 245         return $value;
 246       }
 247
 248       switch ($dataType) {
 249         case 'Boolean':
 250           return (bool) $value;
 251
 252         case 'Integer':
 253           return (int) $value;
 254
 255         case 'Money':
 256         case 'Float':
 257           return (float) $value;
 258       }
 259     }
 260     return $value;
 261   }
 262
 263   /**
 264    * Lists all field names (including suffixed variants) that should be removed for a given contact type.
 265    *
 266    * @param string $contactType
 267    *   Individual|Organization|Household
 268    * @param string $prefix
 269    *   Path at which these fields are found, e.g. "address.contact."
 270    * @return array
 271    */
 272   public static function contactFieldsToRemove($contactType, $prefix) {
 273     if (!isset(\Civi::$statics[__CLASS__][__FUNCTION__][$contactType])) {
 274       \Civi::$statics[__CLASS__][__FUNCTION__][$contactType] = [];
 275       foreach (\CRM_Contact_DAO_Contact::fields() as $field) {
 276         if (!empty($field['contactType']) && $field['contactType'] != $contactType) {
 277           \Civi::$statics[__CLASS__][__FUNCTION__][$contactType][] = $field['name'];
 278           // Include suffixed variants like prefix_id:label
 279           if (!empty($field['pseudoconstant'])) {
 280             foreach (array_keys(self::$pseudoConstantContexts) as $suffix) {
 281               \Civi::$statics[__CLASS__][__FUNCTION__][$contactType][] = $field['name'] . ':' . $suffix;
 282             }
 283           }
 284         }
 285       }
 286     }
 287     // Add prefix paths
 288     return array_map(function($name) use ($prefix) {
 289       return $prefix . $name;
 290     }, \Civi::$statics[__CLASS__][__FUNCTION__][$contactType]);
 291   }
 292
 293 }