Civi/Api4/Generic/AbstractEntity.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  */
  18
  19 namespace Civi\Api4\Generic;
  20
  21 use Civi\API\Exception\NotImplementedException;
  22 use Civi\Api4\Utils\ReflectionUtils;
  23
  24 /**
  25  * Base class for all api entities.
  26  *
  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.
  29  *
  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).
  39  *
  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).
  44  *
  45  * @see https://lab.civicrm.org/extensions/api4example
  46  */
  47 abstract class AbstractEntity {
  48
  49   /**
  50    * @return \Civi\Api4\Action\GetActions
  51    */
  52   public static function getActions() {
  53     return new \Civi\Api4\Action\GetActions(self::getEntityName(), __FUNCTION__);
  54   }
  55
  56   /**
  57    * @return \Civi\Api4\Generic\BasicGetFieldsAction
  58    */
  59   abstract public static function getFields();
  60
  61   /**
  62    * Returns a list of permissions needed to access the various actions in this api.
  63    *
  64    * @return array
  65    */
  66   public static function permissions() {
  67     $permissions = \CRM_Core_Permission::getEntityActionPermissions();
  68
  69     // For legacy reasons the permissions are keyed by lowercase entity name
  70     $lcentity = \CRM_Core_DAO_AllCoreTables::convertEntityNameToLower(self::getEntityName());
  71     // Merge permissions for this entity with the defaults
  72     return ($permissions[$lcentity] ?? []) + $permissions['default'];
  73   }
  74
  75   /**
  76    * Get entity name from called class
  77    *
  78    * @return string
  79    */
  80   protected static function getEntityName() {
  81     return substr(static::class, strrpos(static::class, '\\') + 1);
  82   }
  83
  84   /**
  85    * Overridable function to return a localized title for this entity.
  86    *
  87    * @return string
  88    */
  89   protected static function getEntityTitle() {
  90     return static::getEntityName();
  91   }
  92
  93   /**
  94    * Magic method to return the action object for an api.
  95    *
  96    * @param string $action
  97    * @param null $args
  98    * @return AbstractAction
  99    * @throws NotImplementedException
 100    */
 101   public static function __callStatic($action, $args) {
 102     $entity = self::getEntityName();
 103     // Find class for this action
 104     $entityAction = "\\Civi\\Api4\\Action\\$entity\\" . ucfirst($action);
 105     if (class_exists($entityAction)) {
 106       $actionObject = new $entityAction($entity, $action);
 107     }
 108     else {
 109       throw new NotImplementedException("Api $entity $action version 4 does not exist.");
 110     }
 111     return $actionObject;
 112   }
 113
 114   /**
 115    * Reflection function called by Entity::get()
 116    *
 117    * @see \Civi\Api4\Action\Entity\Get
 118    * @return array
 119    */
 120   public static function getInfo() {
 121     $info = [
 122       'name' => static::getEntityName(),
 123       'title' => static::getEntityTitle(),
 124     ];
 125     $reflection = new \ReflectionClass(static::class);
 126     $info += ReflectionUtils::getCodeDocs($reflection, NULL, ['entity' => $info['name']]);
 127     unset($info['package'], $info['method']);
 128     return $info;
 129   }
 130
 131 }