Commit | Line | Data |
---|---|---|
19b53e5b C |
1 | <?php |
2 | ||
380f3545 TO |
3 | /* |
4 | +--------------------------------------------------------------------+ | |
41498ac5 | 5 | | Copyright CiviCRM LLC. All rights reserved. | |
380f3545 | 6 | | | |
41498ac5 TO |
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 | | |
380f3545 TO |
10 | +--------------------------------------------------------------------+ |
11 | */ | |
12 | ||
13 | /** | |
14 | * | |
15 | * @package CRM | |
ca5cec67 | 16 | * @copyright CiviCRM LLC https://civicrm.org/licensing |
380f3545 TO |
17 | * $Id$ |
18 | * | |
19 | */ | |
20 | ||
21 | ||
19b53e5b C |
22 | namespace Civi\Api4\Generic; |
23 | ||
19b53e5b | 24 | /** |
e3c6d5ff | 25 | * Replaces an existing set of $ENTITIES with a new one. |
19b53e5b | 26 | * |
e3c6d5ff CW |
27 | * This will select a group of existing $ENTITIES based on the `where` parameter. |
28 | * Each will be compared with the $ENTITIES passed in as `records`: | |
fc95d9a5 | 29 | * |
e3c6d5ff CW |
30 | * - $ENTITIES in `records` that don't already exist will be created. |
31 | * - Existing $ENTITIES that are included in `records` will be updated. | |
32 | * - Existing $ENTITIES that are omitted from `records` will be deleted. | |
fc95d9a5 CW |
33 | * |
34 | * @method $this setRecords(array $records) Set array of records. | |
19b53e5b | 35 | * @method array getRecords() |
fc95d9a5 | 36 | * @method $this setDefaults(array $defaults) Set array of defaults. |
19b53e5b C |
37 | * @method array getDefaults() |
38 | * @method $this setReload(bool $reload) Specify whether complete objects will be returned after saving. | |
39 | * @method bool getReload() | |
40 | */ | |
41 | class BasicReplaceAction extends AbstractBatchAction { | |
42 | ||
43 | /** | |
fc95d9a5 | 44 | * Array of $ENTITY records. |
19b53e5b | 45 | * |
fc95d9a5 | 46 | * Should be in the same format as returned by `Get`. |
19b53e5b C |
47 | * |
48 | * @var array | |
49 | * @required | |
50 | */ | |
51 | protected $records = []; | |
52 | ||
53 | /** | |
54 | * Array of default values. | |
55 | * | |
9fe720f0 CW |
56 | * These defaults will be merged into every $ENTITY in `records` before saving. |
57 | * Values set in `records` will override these defaults if set in both places, | |
e3c6d5ff | 58 | * but updating existing $ENTITIES will overwrite current values with these defaults. |
fc95d9a5 | 59 | * |
9fe720f0 | 60 | * **Note:** Values from the `where` clause that use the `=` operator are _also_ treated as default values; |
fc95d9a5 | 61 | * those do not need to be repeated here. |
19b53e5b C |
62 | * |
63 | * @var array | |
64 | */ | |
65 | protected $defaults = []; | |
66 | ||
67 | /** | |
e3c6d5ff | 68 | * Reload $ENTITIES after saving. |
19b53e5b | 69 | * |
fc95d9a5 CW |
70 | * By default this action typically returns partial records containing only the fields |
71 | * that were updated. Set `reload` to `true` to do an additional lookup after saving | |
72 | * to return complete values for every $ENTITY. | |
19b53e5b C |
73 | * |
74 | * @var bool | |
75 | */ | |
76 | protected $reload = FALSE; | |
77 | ||
78 | /** | |
79 | * @return \Civi\Api4\Result\ReplaceResult | |
80 | */ | |
81 | public function execute() { | |
82 | return parent::execute(); | |
83 | } | |
84 | ||
85 | /** | |
86 | * @inheritDoc | |
87 | */ | |
88 | public function _run(Result $result) { | |
89 | $items = $this->getBatchRecords(); | |
90 | ||
91 | // Copy defaults from where clause if the operator is = | |
92 | foreach ($this->where as $clause) { | |
93 | if (is_array($clause) && $clause[1] === '=') { | |
94 | $this->defaults[$clause[0]] = $clause[2]; | |
95 | } | |
96 | } | |
97 | ||
98 | $idField = $this->getSelect()[0]; | |
99 | $toDelete = array_diff_key(array_column($items, NULL, $idField), array_flip(array_filter(\CRM_Utils_Array::collect($idField, $this->records)))); | |
100 | ||
3a8dc228 | 101 | $saveAction = \Civi\API\Request::create($this->getEntityName(), 'save', ['version' => 4]); |
fc2332aa CW |
102 | $saveAction |
103 | ->setCheckPermissions($this->getCheckPermissions()) | |
104 | ->setReload($this->reload) | |
105 | ->setRecords($this->records) | |
106 | ->setDefaults($this->defaults); | |
107 | $result->exchangeArray((array) $saveAction->execute()); | |
19b53e5b C |
108 | |
109 | if ($toDelete) { | |
110 | $result->deleted = (array) civicrm_api4($this->getEntityName(), 'delete', [ | |
111 | 'where' => [[$idField, 'IN', array_keys($toDelete)]], | |
112 | 'checkPermissions' => $this->getCheckPermissions(), | |
113 | ]); | |
114 | } | |
115 | } | |
116 | ||
121ec912 CW |
117 | /** |
118 | * Set default value for a field. | |
119 | * @param string $fieldName | |
120 | * @param mixed $defaultValue | |
121 | * @return $this | |
122 | */ | |
123 | public function addDefault(string $fieldName, $defaultValue) { | |
124 | $this->defaults[$fieldName] = $defaultValue; | |
125 | return $this; | |
126 | } | |
127 | ||
128 | /** | |
129 | * Add one or more records | |
130 | * @param array ...$records | |
131 | * @return $this | |
132 | */ | |
133 | public function addRecord(array ...$records) { | |
134 | $this->records = array_merge($this->records, $records); | |
135 | return $this; | |
136 | } | |
137 | ||
19b53e5b | 138 | } |