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 +--------------------------------------------------------------------+
16 * @copyright CiviCRM LLC https://civicrm.org/licensing
19 namespace Civi\Api4\Generic
;
21 use Civi\API\Exception\NotImplementedException
;
22 use Civi\Api4\Utils\ReflectionUtils
;
25 * Base class for all api entities.
27 * When adding your own api from an extension, extend this class only
28 * if your entity does not have an associated DAO. Otherwise extend DAOEntity.
30 * The recommended way to create a non-DAO-based api is to extend this class
31 * and then add a getFields function and any other actions you wish, e.g.
32 * - a get() function which returns BasicGetAction using your custom getter callback.
33 * - a create() function which returns BasicCreateAction using your custom setter callback.
34 * - a save() function which returns BasicSaveAction using your custom setter callback.
35 * - an update() function which returns BasicUpdateAction using your custom setter callback.
36 * - a delete() function which returns BasicBatchAction using your custom delete callback.
37 * - a replace() function which returns BasicReplaceAction (no callback needed but
38 * depends on the existence of get, save & delete actions).
40 * Note that you can use the same setter callback function for update as create -
41 * that function can distinguish between new & existing records by checking if the
42 * unique identifier has been set (identifier field defaults to "id" but you can change
43 * that when constructing BasicUpdateAction).
45 * @see https://lab.civicrm.org/extensions/api4example
47 abstract class AbstractEntity
{
50 * @param bool $checkPermissions
51 * @return \Civi\Api4\Action\GetActions
53 public static function getActions($checkPermissions = TRUE) {
54 return (new \Civi\Api4\Action\
GetActions(self
::getEntityName(), __FUNCTION__
))
55 ->setCheckPermissions($checkPermissions);
59 * @return \Civi\Api4\Generic\BasicGetFieldsAction
61 abstract public static function getFields();
64 * Returns a list of permissions needed to access the various actions in this api.
68 public static function permissions() {
69 $permissions = \CRM_Core_Permission
::getEntityActionPermissions();
71 // For legacy reasons the permissions are keyed by lowercase entity name
72 $lcentity = \CRM_Core_DAO_AllCoreTables
::convertEntityNameToLower(self
::getEntityName());
73 // Merge permissions for this entity with the defaults
74 return ($permissions[$lcentity] ??
[]) +
$permissions['default'];
78 * Get entity name from called class
82 protected static function getEntityName() {
83 return substr(static::class, strrpos(static::class, '\\') +
1);
87 * Overridable function to return a localized title for this entity.
91 protected static function getEntityTitle() {
92 return static::getEntityName();
96 * Magic method to return the action object for an api.
98 * @param string $action
100 * @return AbstractAction
101 * @throws NotImplementedException
103 public static function __callStatic($action, $args) {
104 $entity = self
::getEntityName();
105 // Find class for this action
106 $entityAction = "\\Civi\\Api4\\Action\\$entity\\" . ucfirst($action);
107 if (class_exists($entityAction)) {
108 $actionObject = new $entityAction($entity, $action);
109 if (isset($args[0]) && $args[0] === FALSE) {
110 $actionObject->setCheckPermissions(FALSE);
114 throw new NotImplementedException("Api $entity $action version 4 does not exist.");
116 return $actionObject;
120 * Reflection function called by Entity::get()
122 * @see \Civi\Api4\Action\Entity\Get
125 public static function getInfo() {
127 'name' => static::getEntityName(),
128 'title' => static::getEntityTitle(),
130 $reflection = new \
ReflectionClass(static::class);
131 $info +
= ReflectionUtils
::getCodeDocs($reflection, NULL, ['entity' => $info['name']]);
132 unset($info['package'], $info['method']);