Civi/Api4/Generic/AbstractSaveAction.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 /**
  25  * Base class for all `Save` api actions.
  26  *
  27  * @method $this setRecords(array $records) Set array of records to be saved.
  28  * @method array getRecords()
  29  * @method $this setDefaults(array $defaults) Array of defaults.
  30  * @method array getDefaults()
  31  * @method $this setReload(bool $reload) Specify whether complete objects will be returned after saving.
  32  * @method bool getReload()
  33  *
  34  * @package Civi\Api4\Generic
  35  */
  36 abstract class AbstractSaveAction extends AbstractAction {
  37
  38   /**
  39    * Array of $ENTITIES to save.
  40    *
  41    * Should be in the same format as returned by `Get`.
  42    *
  43    * @var array
  44    * @required
  45    */
  46   protected $records = [];
  47
  48   /**
  49    * Array of default values.
  50    *
  51    * These defaults will be merged into every $ENTITY in `records` before saving.
  52    * Values set in `records` will override these defaults if set in both places,
  53    * but updating existing $ENTITIES will overwrite current values with these defaults.
  54    *
  55    * @var array
  56    */
  57   protected $defaults = [];
  58
  59   /**
  60    * Reload $ENTITIES after saving.
  61    *
  62    * By default this action typically returns partial records containing only the fields
  63    * that were updated. Set `reload` to `true` to do an additional lookup after saving
  64    * to return complete values for every $ENTITY.
  65    *
  66    * @var bool
  67    */
  68   protected $reload = FALSE;
  69
  70   /**
  71    * @var string
  72    */
  73   private $idField;
  74
  75   /**
  76    * BatchAction constructor.
  77    * @param string $entityName
  78    * @param string $actionName
  79    * @param string $idField
  80    */
  81   public function __construct($entityName, $actionName, $idField = 'id') {
  82     // $idField should be a string but some apis (e.g. CustomValue) give us an array
  83     $this->idField = array_values((array) $idField)[0];
  84     parent::__construct($entityName, $actionName);
  85   }
  86
  87   /**
  88    * @throws \API_Exception
  89    */
  90   protected function validateValues() {
  91     $unmatched = [];
  92     foreach ($this->records as $record) {
  93       if (empty($record[$this->idField])) {
  94         $unmatched = array_unique(array_merge($unmatched, $this->checkRequiredFields($record)));
  95       }
  96     }
  97     if ($unmatched) {
  98       throw new \API_Exception("Mandatory values missing from Api4 {$this->getEntityName()}::{$this->getActionName()}: " . implode(", ", $unmatched), "mandatory_missing", ["fields" => $unmatched]);
  99     }
 100   }
 101
 102   /**
 103    * @return string
 104    */
 105   protected function getIdField() {
 106     return $this->idField;
 107   }
 108
 109   /**
 110    * Add one or more records to be saved.
 111    * @param array ...$records
 112    * @return $this
 113    */
 114   public function addRecord(array ...$records) {
 115     $this->records = array_merge($this->records, $records);
 116     return $this;
 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 }