4 +--------------------------------------------------------------------+
5 | Copyright CiviCRM LLC. All rights reserved. |
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 +--------------------------------------------------------------------+
16 * @copyright CiviCRM LLC https://civicrm.org/licensing
22 namespace Civi\Api4\Utils
;
24 require_once 'api/v3/utils.php';
26 class FormattingUtil
{
29 * Massage values into the format the BAO expects for a write operation
34 * @throws \API_Exception
36 public static function formatWriteParams(&$params, $entity, $fields) {
37 foreach ($fields as $name => $field) {
38 if (!empty($params[$name])) {
39 $value =& $params[$name];
40 // Hack for null values -- see comment below
41 if ($value === 'null') {
44 self
::formatInputValue($value, $field, $entity);
45 // Ensure we have an array for serialized fields
46 if (!empty($field['serialize'] && !is_array($value))) {
47 $value = (array) $value;
51 * Because of the wacky way that database values are saved we need to format
52 * some of the values here. In this strange world the string 'null' is used to
53 * unset values. Hence if we encounter true null we change it to string 'null'.
55 * If we encounter the string 'null' then we assume the user actually wants to
56 * set the value to string null. However since the string null is reserved for
57 * unsetting values we must change it. Another quirk of the DB_DataObject is
58 * that it allows 'Null' to be set, but any other variation of string 'null'
59 * will be converted to true null, e.g. 'nuLL', 'NUlL' etc. so we change it to
62 elseif (array_key_exists($name, $params) && $params[$name] === NULL) {
63 $params[$name] = 'null';
67 \CRM_Utils_API_HTMLInputCoder
::singleton()->encodeRow($params);
71 * Transform raw api input to appropriate format for use in a SQL query.
73 * This is used by read AND write actions (Get, Create, Update, Replace)
77 * @param string $entity
78 * Ex: 'Contact', 'Domain'
79 * @throws \API_Exception
81 public static function formatInputValue(&$value, $fieldSpec, $entity) {
82 if (is_array($value)) {
83 foreach ($value as &$val) {
84 self
::formatInputValue($val, $fieldSpec, $entity);
88 $fk = $fieldSpec['name'] == 'id' ?
$entity : $fieldSpec['fk_entity'] ??
NULL;
90 if ($fk === 'Domain' && $value === 'current_domain') {
91 $value = \CRM_Core_Config
::domainID();
94 if ($fk === 'Contact' && !is_numeric($value)) {
95 $value = \
_civicrm_api3_resolve_contactID($value);
96 if ('unknown-user' === $value) {
97 throw new \
API_Exception("\"{$fieldSpec['name']}\" \"{$value}\" cannot be resolved to a contact ID", 2002, ['error_field' => $fieldSpec['name'], "type" => "integer"]);
101 switch ($fieldSpec['data_type'] ??
NULL) {
103 $value = date('Y-m-d H:i:s', strtotime($value));
107 $value = date('Ymd', strtotime($value));
111 $hic = \CRM_Utils_API_HTMLInputCoder
::singleton();
112 if (!$hic->isSkippedField($fieldSpec['name'])) {
113 $value = $hic->encodeValue($value);
118 * Unserialize raw DAO values and convert to correct type
120 * @param array $results
121 * @param array $fields
122 * @param string $entity
123 * @throws \CRM_Core_Exception
125 public static function formatOutputValues(&$results, $fields, $entity) {
126 foreach ($results as &$result) {
127 // Remove inapplicable contact fields
128 if ($entity === 'Contact' && !empty($result['contact_type'])) {
129 \CRM_Utils_Array
::remove($result, self
::contactFieldsToRemove($result['contact_type']));
131 foreach ($result as $field => $value) {
132 $dataType = $fields[$field]['data_type'] ??
($field == 'id' ?
'Integer' : NULL);
133 if (!empty($fields[$field]['serialize'])) {
134 if (is_string($value)) {
135 $result[$field] = $value = \CRM_Core_DAO
::unSerializeField($value, $fields[$field]['serialize']);
136 foreach ($value as $key => $val) {
137 $result[$field][$key] = self
::convertDataType($val, $dataType);
142 $result[$field] = self
::convertDataType($value, $dataType);
149 * @param mixed $value
150 * @param string $dataType
153 public static function convertDataType($value, $dataType) {
157 return (bool) $value;
164 return (float) $value;
171 * @param string $contactType
174 public static function contactFieldsToRemove($contactType) {
175 if (!isset(\Civi
::$statics[__CLASS__
][__FUNCTION__
][$contactType])) {
176 \Civi
::$statics[__CLASS__
][__FUNCTION__
][$contactType] = [];
177 foreach (\CRM_Contact_DAO_Contact
::fields() as $field) {
178 if (!empty($field['contactType']) && $field['contactType'] != $contactType) {
179 \Civi
::$statics[__CLASS__
][__FUNCTION__
][$contactType][] = $field['name'];
183 return \Civi
::$statics[__CLASS__
][__FUNCTION__
][$contactType];