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) Array of records.
  28  * @method $this addRecord($record) Add a record to update.
  29  * @method array getRecords()
  30  * @method $this setDefaults(array $defaults) Array of defaults.
  31  * @method $this addDefault($name, $value) Add a default value.
  32  * @method array getDefaults()
  33  * @method $this setReload(bool $reload) Specify whether complete objects will be returned after saving.
  34  * @method bool getReload()
  35  *
  36  * @package Civi\Api4\Generic
  37  */
  38 abstract class AbstractSaveAction extends AbstractAction {
  39
  40   /**
  41    * Array of records.
  42    *
  43    * Should be in the same format as returned by Get.
  44    *
  45    * @var array
  46    * @required
  47    */
  48   protected $records = [];
  49
  50   /**
  51    * Array of default values.
  52    *
  53    * These defaults will be applied to all records unless they specify otherwise.
  54    *
  55    * @var array
  56    */
  57   protected $defaults = [];
  58
  59   /**
  60    * Reload records after saving.
  61    *
  62    * By default this api 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 records.
  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 }