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
20 namespace Civi\Api4\Generic
;
23 * Replaces an existing set of $ENTITIES with a new one.
25 * This will select a group of existing $ENTITIES based on the `where` parameter.
26 * Each will be compared with the $ENTITIES passed in as `records`:
28 * - $ENTITIES in `records` that don't already exist will be created.
29 * - Existing $ENTITIES that are included in `records` will be updated.
30 * - Existing $ENTITIES that are omitted from `records` will be deleted.
32 * @method $this setRecords(array $records) Set array of records.
33 * @method array getRecords()
34 * @method $this setDefaults(array $defaults) Set array of defaults.
35 * @method array getDefaults()
36 * @method $this setReload(bool $reload) Specify whether complete objects will be returned after saving.
37 * @method bool getReload()
39 class BasicReplaceAction
extends AbstractBatchAction
{
42 * Array of $ENTITY records.
44 * Should be in the same format as returned by `Get`.
49 protected $records = [];
52 * Array of default values.
54 * These defaults will be merged into every $ENTITY in `records` before saving.
55 * Values set in `records` will override these defaults if set in both places,
56 * but updating existing $ENTITIES will overwrite current values with these defaults.
58 * **Note:** Values from the `where` clause that use the `=` operator are _also_ treated as default values;
59 * those do not need to be repeated here.
63 protected $defaults = [];
66 * Reload $ENTITIES after saving.
68 * By default this action typically returns partial records containing only the fields
69 * that were updated. Set `reload` to `true` to do an additional lookup after saving
70 * to return complete values for every $ENTITY.
74 protected $reload = FALSE;
77 * @return \Civi\Api4\Result\ReplaceResult
79 public function execute() {
80 return parent
::execute();
86 public function _run(Result
$result) {
87 $items = $this->getBatchRecords();
89 // Copy defaults from where clause if the operator is =
90 foreach ($this->where
as $clause) {
91 if (is_array($clause) && $clause[1] === '=') {
92 $this->defaults
[$clause[0]] = $clause[2];
96 $idField = $this->getSelect()[0];
97 $toDelete = array_diff_key(array_column($items, NULL, $idField), array_flip(array_filter(\CRM_Utils_Array
::collect($idField, $this->records
))));
99 $saveAction = \Civi\API\Request
::create($this->getEntityName(), 'save', ['version' => 4]);
101 ->setCheckPermissions($this->getCheckPermissions())
102 ->setReload($this->reload
)
103 ->setRecords($this->records
)
104 ->setDefaults($this->defaults
);
105 $result->exchangeArray((array) $saveAction->execute());
108 $result->deleted
= (array) civicrm_api4($this->getEntityName(), 'delete', [
109 'where' => [[$idField, 'IN', array_keys($toDelete)]],
110 'checkPermissions' => $this->getCheckPermissions(),
116 * Set default value for a field.
117 * @param string $fieldName
118 * @param mixed $defaultValue
121 public function addDefault(string $fieldName, $defaultValue) {
122 $this->defaults
[$fieldName] = $defaultValue;
127 * Add one or more records
128 * @param array ...$records
131 public function addRecord(array ...$records) {
132 $this->records
= array_merge($this->records
, $records);