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 +--------------------------------------------------------------------+
13 namespace Civi\Api4\Generic\Traits
;
15 use Civi\Api4\CustomField
;
16 use Civi\Api4\Service\Schema\Joinable\CustomGroupJoinable
;
17 use Civi\Api4\Utils\FormattingUtil
;
18 use Civi\Api4\Utils\CoreUtil
;
21 * @method string getLanguage()
22 * @method $this setLanguage(string $language)
24 trait DAOActionTrait
{
27 * Specify the language to use if this is a multi-lingual environment.
29 * E.g. "en_US" or "fr_CA"
35 private $_maxWeights = [];
38 * @return \CRM_Core_DAO|string
40 protected function getBaoName() {
41 return CoreUtil
::getBAOFromApiName($this->getEntityName());
45 * Convert saved object to array
47 * Used by create, update & save actions
49 * @param \CRM_Core_DAO $bao
53 public function baoToArray($bao, $input) {
54 $allFields = array_column($bao->fields(), 'name');
55 if (!empty($this->reload
)) {
56 $inputFields = $allFields;
60 $inputFields = array_keys($input);
61 // Convert 'null' input to true null
62 foreach ($input as $key => $val) {
63 if ($val === 'null') {
69 foreach ($allFields as $field) {
70 if (isset($bao->$field) ||
in_array($field, $inputFields)) {
71 $values[$field] = $bao->$field ??
NULL;
78 * Fill field defaults which were declared by the api.
80 * Note: default values from core are ignored because the BAO or database layer will supply them.
82 * @param array $params
84 protected function fillDefaults(&$params) {
85 $fields = $this->entityFields();
86 $bao = $this->getBaoName();
87 $coreFields = array_column($bao::fields(), NULL, 'name');
89 foreach ($fields as $name => $field) {
90 // If a default value in the api field is different than in core, the api should override it.
91 if (!isset($params[$name]) && !empty($field['default_value']) && $field['default_value'] != \CRM_Utils_Array
::pathGet($coreFields, [$name, 'default'])) {
92 $params[$name] = $field['default_value'];
98 * Write bao objects as part of a create/update/save action.
100 * @param array $items
101 * The records to write to the DB.
104 * The records after being written to the DB (e.g. including newly assigned "id").
105 * @throws \API_Exception
106 * @throws \CRM_Core_Exception
108 protected function writeObjects(&$items) {
109 $baoName = $this->getBaoName();
110 $updateWeights = FALSE;
112 // TODO: Opt-in more entities to use the new writeRecords BAO method.
115 'CustomField' => 'writeRecords',
116 'EntityTag' => 'add',
117 'GroupContact' => 'add',
118 'Navigation' => 'writeRecords',
119 'WordReplacement' => 'writeRecords',
121 $method = $functionNames[$this->getEntityName()] ??
NULL;
122 if (!isset($method)) {
123 $method = method_exists($baoName, 'create') ?
'create' : (method_exists($baoName, 'add') ?
'add' : 'writeRecords');
126 // Adjust weights for sortable entities
127 if (in_array('SortableEntity', CoreUtil
::getInfoItem($this->getEntityName(), 'type'))) {
128 $weightField = CoreUtil
::getInfoItem($this->getEntityName(), 'order_by');
129 // Only take action if updating a single record, or if no weights are specified in any record
130 // This avoids messing up a bulk update with multiple recalculations
131 if (count($items) === 1 ||
!array_filter(array_column($items, $weightField))) {
132 $updateWeights = TRUE;
138 foreach ($items as &$item) {
139 $entityId = $item['id'] ??
NULL;
140 FormattingUtil
::formatWriteParams($item, $this->entityFields());
141 $this->formatCustomParams($item, $entityId);
143 // Adjust weights for sortable entities
144 if ($updateWeights) {
145 $this->updateWeight($item);
148 // Skip individual processing if using writeRecords
149 if ($method === 'writeRecords') {
152 $item['check_permissions'] = $this->getCheckPermissions();
154 // For some reason the contact bao requires this
155 if ($entityId && $this->getEntityName() === 'Contact') {
156 $item['contact_id'] = $entityId;
159 if ($this->getEntityName() === 'Address') {
160 $createResult = $baoName::$method($item, $this->fixAddress
);
163 $createResult = $baoName::$method($item);
166 if (!$createResult) {
167 $errMessage = sprintf('%s write operation failed', $this->getEntityName());
168 throw new \
API_Exception($errMessage);
171 $result[] = $this->baoToArray($createResult, $item);
174 // Use bulk `writeRecords` method if the BAO doesn't have a create or add method
175 // TODO: reverse this from opt-in to opt-out and default to using `writeRecords` for all BAOs
176 if ($method === 'writeRecords') {
177 $items = array_values($items);
178 foreach ($baoName::writeRecords($items) as $i => $createResult) {
179 $result[] = $this->baoToArray($createResult, $items[$i]);
183 \CRM_Utils_API_HTMLInputCoder
::singleton()->decodeRows($result);
184 FormattingUtil
::formatOutputValues($result, $this->entityFields());
191 protected function formatWriteValues(&$record) {
192 $this->resolveFKValues($record);
193 parent
::formatWriteValues($record);
197 * Looks up an id based on some other property of an fk entity
199 * @param array $record
201 private function resolveFKValues(array &$record): void
{
202 // Resolve domain id first
203 uksort($record, function($a, $b) {
204 return substr($a, 0, 9) == 'domain_id' ?
-1 : 1;
206 foreach ($record as $key => $value) {
207 if (!$value ||
substr_count($key, '.') !== 1) {
210 [$fieldName, $fkField] = explode('.', $key);
211 $field = $this->entityFields()[$fieldName] ??
NULL;
212 if (!$field ||
empty($field['fk_entity'])) {
215 $fkDao = CoreUtil
::getBAOFromApiName($field['fk_entity']);
216 // Constrain search to the domain of the current entity
217 $domainConstraint = NULL;
218 if (isset($fkDao::getSupportedFields()['domain_id'])) {
219 if (!empty($record['domain_id'])) {
220 $domainConstraint = $record['domain_id'] === 'current_domain' ? \CRM_Core_Config
::domainID() : $record['domain_id'];
222 elseif (!empty($record['id']) && isset($this->entityFields()['domain_id'])) {
223 $domainConstraint = \CRM_Core_DAO
::getFieldValue($this->getBaoName(), $record['id'], 'domain_id');
226 if ($domainConstraint) {
227 $fkSearch = new $fkDao();
228 $fkSearch->domain_id
= $domainConstraint;
229 $fkSearch->$fkField = $value;
230 $fkSearch->find(TRUE);
231 $record[$fieldName] = $fkSearch->id
;
233 // Simple lookup without all the fuss about domains
235 $record[$fieldName] = \CRM_Core_DAO
::getFieldValue($fkDao, $value, 'id', $fkField);
237 unset($record[$key]);
242 * Converts params from flat array e.g. ['GroupName.Fieldname' => value] to the
243 * hierarchy expected by the BAO, nested within $params['custom'].
245 * @param array $params
246 * @param int $entityId
248 * @throws \API_Exception
249 * @throws \CRM_Core_Exception
251 protected function formatCustomParams(&$params, $entityId) {
254 foreach ($params as $name => $value) {
255 $field = $this->getCustomFieldInfo($name);
260 // Null and empty string are interchangeable as far as the custom bao understands
261 if (NULL === $value) {
265 if ($field['suffix']) {
266 $options = FormattingUtil
::getPseudoconstantList($field, $name, $params, $this->getActionName());
267 $value = FormattingUtil
::replacePseudoconstant($options, $value, TRUE);
270 if ($field['html_type'] === 'CheckBox') {
271 // this function should be part of a class
272 formatCheckBoxField($value, 'custom_' . $field['id'], $this->getEntityName());
275 // Match contact id to strings like "user_contact_id"
276 // FIXME handle arrays for multi-value contact reference fields, etc.
277 if ($field['data_type'] === 'ContactReference' && is_string($value) && !is_numeric($value)) {
278 // FIXME decouple from v3 API
279 require_once 'api/v3/utils.php';
280 $value = \
_civicrm_api3_resolve_contactID($value);
281 if ('unknown-user' === $value) {
282 throw new \
API_Exception("\"{$field['name']}\" \"{$value}\" cannot be resolved to a contact ID", 2002, ['error_field' => $field['name'], "type" => "integer"]);
286 \CRM_Core_BAO_CustomField
::formatCustomField(
290 $field['custom_group_id.extends'],
291 // todo check when this is needed
295 $this->getCheckPermissions(),
300 $params['custom'] = $customParams ?
: NULL;
304 * Gets field info needed to save custom data
306 * @param string $fieldExpr
307 * Field identifier with possible suffix, e.g. MyCustomGroup.MyField1:label
308 * @return array{id: int, name: string, entity: string, suffix: string, html_type: string, data_type: string}|NULL
310 protected function getCustomFieldInfo(string $fieldExpr) {
311 if (strpos($fieldExpr, '.') === FALSE) {
314 [$groupName, $fieldName] = explode('.', $fieldExpr);
315 [$fieldName, $suffix] = array_pad(explode(':', $fieldName), 2, NULL);
316 $cacheKey = "APIv4_Custom_Fields-$groupName";
317 $info = \Civi
::cache('metadata')->get($cacheKey);
318 if (!isset($info[$fieldName])) {
320 $fields = CustomField
::get(FALSE)
321 ->addSelect('id', 'name', 'html_type', 'data_type', 'custom_group_id.extends')
322 ->addWhere('custom_group_id.name', '=', $groupName)
323 ->execute()->indexBy('name');
324 foreach ($fields as $name => $field) {
325 $field['custom_field_id'] = $field['id'];
326 $field['name'] = $groupName . '.' . $name;
327 $field['entity'] = CustomGroupJoinable
::getEntityFromExtends($field['custom_group_id.extends']);
328 $info[$name] = $field;
330 \Civi
::cache('metadata')->set($cacheKey, $info);
332 return isset($info[$fieldName]) ?
['suffix' => $suffix] +
$info[$fieldName] : NULL;
336 * Update weights when inserting or updating a sortable entity
337 * @param array $record
338 * @see SortableEntity
340 protected function updateWeight(array &$record) {
341 /** @var \CRM_Core_DAO|string $daoName */
342 $daoName = CoreUtil
::getInfoItem($this->getEntityName(), 'dao');
343 $weightField = CoreUtil
::getInfoItem($this->getEntityName(), 'order_by');
344 $idField = CoreUtil
::getIdFieldName($this->getEntityName());
345 // If updating an existing record without changing weight, do nothing
346 if (!isset($record[$weightField]) && !empty($record[$idField])) {
349 $daoFields = $daoName::getSupportedFields();
350 $newWeight = $record[$weightField] ??
NULL;
351 $oldWeight = empty($record[$idField]) ?
NULL : \CRM_Core_DAO
::getFieldValue($daoName, $record[$idField], $weightField);
353 // FIXME: Need a more metadata-ish approach. For now here's a hardcoded list of the fields sortable entities use for grouping.
354 $guesses = ['option_group_id', 'price_set_id', 'price_field_id', 'premiums_id', 'uf_group_id', 'custom_group_id', 'parent_id', 'domain_id'];
356 foreach (array_intersect($guesses, array_keys($daoFields)) as $filter) {
357 $filters[$filter] = $record[$filter] ??
(empty($record[$idField]) ?
NULL : \CRM_Core_DAO
::getFieldValue($daoName, $record[$idField], $filter));
359 // Supply default weight for new record
360 if (!isset($record[$weightField]) && empty($record[$idField])) {
361 $record[$weightField] = $this->getMaxWeight($daoName, $filters, $weightField);
364 $record[$weightField] = \CRM_Utils_Weight
::updateOtherWeights($daoName, $oldWeight, $newWeight, $filters, $weightField);
369 * Looks up max weight for a set of sortable entities
371 * Keeps it in memory in case this operation is writing more than one record
375 * @param $weightField
378 private function getMaxWeight($daoName, $filters, $weightField) {
379 $key = $daoName . json_encode($filters);
380 if (!isset($this->_maxWeights
[$key])) {
381 $this->_maxWeights
[$key] = \CRM_Utils_Weight
::getMax($daoName, $filters, $weightField) +
1;
384 ++
$this->_maxWeights
[$key];
386 return $this->_maxWeights
[$key];