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