Civi/Api4/Generic/BasicUpdateAction.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 namespace Civi\Api4\Generic;
  14
  15 use Civi\API\Exception\NotImplementedException;
  16
  17 /**
  18  * Update one or more $ENTITY with new values.
  19  *
  20  * Use the `where` clause (required) to select them.
  21  */
  22 class BasicUpdateAction extends AbstractUpdateAction {
  23
  24   /**
  25    * @var callable
  26    *   Function(array $item, BasicUpdateAction $thisAction): array
  27    */
  28   private $setter;
  29
  30   /**
  31    * BasicUpdateAction constructor.
  32    *
  33    * @param string $entityName
  34    * @param string $actionName
  35    * @param callable $setter
  36    */
  37   public function __construct($entityName, $actionName, $setter = NULL) {
  38     parent::__construct($entityName, $actionName);
  39     // Accept setter as 4th param for now, but emit deprecated warning
  40     $this->setter = func_get_args()[3] ?? NULL;
  41     if ($this->setter) {
  42       \CRM_Core_Error::deprecatedWarning(__CLASS__ . ' constructor received $setter as 4th param; it should be the 3rd as the $select param has been removed');
  43     }
  44     else {
  45       $this->setter = $setter;
  46     }
  47   }
  48
  49   /**
  50    * @param array $items
  51    * @return array
  52    * @throws \API_Exception
  53    */
  54   protected function updateRecords(array $items): array {
  55     return array_map([$this, 'writeRecord'], $items);
  56   }
  57
  58   /**
  59    * This Basic Update class can be used in one of two ways:
  60    *
  61    * 1. Use this class directly by passing a callable ($setter) to the constructor.
  62    * 2. Extend this class and override this function.
  63    *
  64    * Either way, this function should return an array representing the one modified object.
  65    *
  66    * @param array $item
  67    * @return array
  68    * @throws \Civi\API\Exception\NotImplementedException
  69    */
  70   protected function writeRecord($item) {
  71     if (is_callable($this->setter)) {
  72       $this->addCallbackToDebugOutput($this->setter);
  73       return call_user_func($this->setter, $item, $this);
  74     }
  75     throw new NotImplementedException('Setter function not found for api4 ' . $this->getEntityName() . '::' . $this->getActionName());
  76   }
  77
  78 }