4 +--------------------------------------------------------------------+
5 | Copyright CiviCRM LLC. All rights reserved. |
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 +--------------------------------------------------------------------+
13 namespace Civi\Api4\Generic
;
16 * Base class for ad-hoc entities that implement CRUD actions.
18 * This is one of 3 possible base classes for an APIv4 Entity
19 * (the others are `DAOEntity` and `AbstractEntity`).
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:
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.
30 * Note: the `replace` action does not require any callback as it internally calls the entity's `get`, `save` and `delete` actions.
32 abstract class BasicEntity
extends AbstractEntity
{
35 * Unique identifier for this entity.
39 protected static $idField = 'id';
42 * Function to read records. Used by `get` action.
45 * Function(BasicGetAction $thisAction): array[]
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.
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()
53 protected static $getter;
56 * Function to write a record. Used by `create`, `update` and `save`.
59 * Function(array $item, BasicCreateAction|BasicSaveAction|BasicUpdateAction $thisAction): array
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.
64 * This callback should check the $idField of the record to determine whether the operation is a create or update.
66 * It should return the updated record as an array.
68 protected static $setter;
71 * Function to delete records. Used by `delete` action.
74 * Function(array $item, BasicBatchAction $thisAction): array
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.
79 * This callback should check the $idField of the item to determine which record to delete.
81 * It should return the deleted record as an array.
83 protected static $deleter;
86 * @param bool $checkPermissions
87 * @return BasicGetAction
89 public static function get($checkPermissions = TRUE) {
90 return (new BasicGetAction(static::getEntityName(), __FUNCTION__
, static::$getter))
91 ->setCheckPermissions($checkPermissions);
95 * @param bool $checkPermissions
96 * @return BasicCreateAction
98 public static function create($checkPermissions = TRUE) {
99 return (new BasicCreateAction(static::getEntityName(), __FUNCTION__
, static::$setter))
100 ->setCheckPermissions($checkPermissions);
104 * @param bool $checkPermissions
105 * @return BasicSaveAction
107 public static function save($checkPermissions = TRUE) {
108 return (new BasicSaveAction(static::getEntityName(), __FUNCTION__
, static::$setter))
109 ->setCheckPermissions($checkPermissions);
113 * @param bool $checkPermissions
114 * @return BasicUpdateAction
116 public static function update($checkPermissions = TRUE) {
117 return (new BasicUpdateAction(static::getEntityName(), __FUNCTION__
, static::$setter))
118 ->setCheckPermissions($checkPermissions);
122 * @param bool $checkPermissions
123 * @return BasicBatchAction
125 public static function delete($checkPermissions = TRUE) {
126 return (new BasicBatchAction(static::getEntityName(), __FUNCTION__
, static::$deleter))
127 ->setCheckPermissions($checkPermissions);
131 * @param bool $checkPermissions
132 * @return BasicReplaceAction
134 public static function replace($checkPermissions = TRUE) {
135 return (new BasicReplaceAction(static::getEntityName(), __FUNCTION__
))
136 ->setCheckPermissions($checkPermissions);
142 public static function getInfo() {
143 $info = parent
::getInfo();
144 $info['primary_key'] = (array) static::$idField;