Civi/Api4/Generic/BasicEntity.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 /**
  16  * Base class for ad-hoc entities that implement CRUD actions.
  17  *
  18  * This is one of 3 possible base classes for an APIv4 Entity
  19  * (the others are `DAOEntity` and `AbstractEntity`).
  20  *
  21  * This base class is for entities that do not have an associated DAO but do implement CRUD actions.
  22  * It can be used in one of these ways:
  23  *
  24  * 1. Extend this class and define the static variables `$getter`, `$setter` & `$deleter` with callbacks to handle CRUD operations.
  25  *    In that case there is no need to implement any actions other than `getFields`.
  26  * 2. Override the `get`, `create`, `delete`, etc. methods with custom BasicAction implementations.
  27  * 3. Some combination of the above two options, e.g. defining a callback for `$getter` and using the default `get` action,
  28  *    but leaving `$deleter` unset and overriding the `delete` method with a custom BasicBatchAction to handle deletion.
  29  *
  30  * Note: the `replace` action does not require any callback as it internally calls the entity's `get`, `save` and `delete` actions.
  31  */
  32 abstract class BasicEntity extends AbstractEntity {
  33
  34   /**
  35    * Unique identifier for this entity.
  36    *
  37    * @var string|string[]
  38    */
  39   protected static $idField = 'id';
  40
  41   /**
  42    * Function to read records. Used by `get` action.
  43    *
  44    * @var callable
  45    *   Function(BasicGetAction $thisAction): array[]
  46    *
  47    * This function should return an array of records, and is passed a copy of the BasicGetAction object as its first argument.
  48    * The simplest implementation is for it to return every record and the BasicGetAction automatically handle sorting and filtering.
  49    *
  50    * If performance is a concern, it can take advantage of some helper functions for e.g. fetching item(s) by id.
  51    * @see BasicGetAction::getRecords()
  52    */
  53   protected static $getter;
  54
  55   /**
  56    * Function to write a record. Used by `create`, `update` and `save`.
  57    *
  58    * @var callable
  59    *   Function(array $item, BasicCreateAction|BasicSaveAction|BasicUpdateAction $thisAction): array
  60    *
  61    * This function is called once per write. It takes a single record as the first param, and a reference to
  62    * the action object as the second.
  63    *
  64    * This callback should check the $idField of the record to determine whether the operation is a create or update.
  65    *
  66    * It should return the updated record as an array.
  67    */
  68   protected static $setter;
  69
  70   /**
  71    * Function to delete records. Used by `delete` action.
  72    *
  73    * @var callable
  74    *   Function(array $item, BasicBatchAction $thisAction): array
  75    *
  76    * This function is called once per delete. It takes a single record as the first param, and a reference to
  77    * the action object as the second.
  78    *
  79    * This callback should check the $idField of the item to determine which record to delete.
  80    *
  81    * It should return the deleted record as an array.
  82    */
  83   protected static $deleter;
  84
  85   /**
  86    * @param bool $checkPermissions
  87    * @return BasicGetAction
  88    */
  89   public static function get($checkPermissions = TRUE) {
  90     return (new BasicGetAction(static::getEntityName(), __FUNCTION__, static::$getter))
  91       ->setCheckPermissions($checkPermissions);
  92   }
  93
  94   /**
  95    * @param bool $checkPermissions
  96    * @return BasicCreateAction
  97    */
  98   public static function create($checkPermissions = TRUE) {
  99     return (new BasicCreateAction(static::getEntityName(), __FUNCTION__, static::$setter))
 100       ->setCheckPermissions($checkPermissions);
 101   }
 102
 103   /**
 104    * @param bool $checkPermissions
 105    * @return BasicSaveAction
 106    */
 107   public static function save($checkPermissions = TRUE) {
 108     return (new BasicSaveAction(static::getEntityName(), __FUNCTION__, static::$setter))
 109       ->setCheckPermissions($checkPermissions);
 110   }
 111
 112   /**
 113    * @param bool $checkPermissions
 114    * @return BasicUpdateAction
 115    */
 116   public static function update($checkPermissions = TRUE) {
 117     return (new BasicUpdateAction(static::getEntityName(), __FUNCTION__, static::$setter))
 118       ->setCheckPermissions($checkPermissions);
 119   }
 120
 121   /**
 122    * @param bool $checkPermissions
 123    * @return BasicBatchAction
 124    */
 125   public static function delete($checkPermissions = TRUE) {
 126     return (new BasicBatchAction(static::getEntityName(), __FUNCTION__, static::$deleter))
 127       ->setCheckPermissions($checkPermissions);
 128   }
 129
 130   /**
 131    * @param bool $checkPermissions
 132    * @return BasicReplaceAction
 133    */
 134   public static function replace($checkPermissions = TRUE) {
 135     return (new BasicReplaceAction(static::getEntityName(), __FUNCTION__))
 136       ->setCheckPermissions($checkPermissions);
 137   }
 138
 139   /**
 140    * @inheritDoc
 141    */
 142   public static function getInfo() {
 143     $info = parent::getInfo();
 144     $info['primary_key'] = (array) static::$idField;
 145     return $info;
 146   }
 147
 148 }