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  * This is the most generic of 3 possible base classes for an APIv4 Entity
  28  * (the other 2, which extend this class, are `BasicEntity` and `DAOEntity`).
  29  *
  30  * Implementing an API by extending this class directly is appropriate when it does not implement
  31  * all of the CRUD actions, or only a subset like `get` without `create`, `update` or `delete`;
  32  * for example the RelationshipCache entity.
  33  *
  34  * For all other APIs that do implement CRUD it is recommended to use:
  35  * 1. `DAOEntity` for all entities with a DAO (sql table).
  36  * 2. `BasicEntity` for all others, e.g. file-based entities.
  37  *
  38  * An entity which extends this class directly must, at minimum, implement the `getFields` action.
  39  *
  40  * @see https://lab.civicrm.org/extensions/api4example
  41  */
  42 abstract class AbstractEntity {
  43
  44   /**
  45    * @param bool $checkPermissions
  46    * @return \Civi\Api4\Action\GetActions
  47    */
  48   public static function getActions($checkPermissions = TRUE) {
  49     return (new \Civi\Api4\Action\GetActions(self::getEntityName(), __FUNCTION__))
  50       ->setCheckPermissions($checkPermissions);
  51   }
  52
  53   /**
  54    * @return \Civi\Api4\Generic\BasicGetFieldsAction
  55    */
  56   abstract public static function getFields();
  57
  58   /**
  59    * Returns a list of permissions needed to access the various actions in this api.
  60    *
  61    * @return array
  62    */
  63   public static function permissions() {
  64     $permissions = \CRM_Core_Permission::getEntityActionPermissions();
  65
  66     // For legacy reasons the permissions are keyed by lowercase entity name
  67     $lcentity = \CRM_Core_DAO_AllCoreTables::convertEntityNameToLower(self::getEntityName());
  68     // Merge permissions for this entity with the defaults
  69     return ($permissions[$lcentity] ?? []) + $permissions['default'];
  70   }
  71
  72   /**
  73    * Get entity name from called class
  74    *
  75    * @return string
  76    */
  77   protected static function getEntityName() {
  78     return self::stripNamespace(static::class);
  79   }
  80
  81   /**
  82    * Overridable function to return a localized title for this entity.
  83    *
  84    * @param bool $plural
  85    *   Whether to return a plural title.
  86    * @return string
  87    */
  88   protected static function getEntityTitle($plural = FALSE) {
  89     return static::getEntityName();
  90   }
  91
  92   /**
  93    * Magic method to return the action object for an api.
  94    *
  95    * @param string $action
  96    * @param array $args
  97    * @return AbstractAction
  98    * @throws NotImplementedException
  99    */
 100   public static function __callStatic($action, $args) {
 101     $entity = self::getEntityName();
 102     // Find class for this action
 103     $entityAction = "\\Civi\\Api4\\Action\\$entity\\" . ucfirst($action);
 104     if (class_exists($entityAction)) {
 105       $actionObject = new $entityAction($entity, $action);
 106       if (isset($args[0]) && $args[0] === FALSE) {
 107         $actionObject->setCheckPermissions(FALSE);
 108       }
 109     }
 110     else {
 111       throw new NotImplementedException("Api $entity $action version 4 does not exist.");
 112     }
 113     return $actionObject;
 114   }
 115
 116   /**
 117    * Reflection function called by Entity::get()
 118    *
 119    * @see \Civi\Api4\Action\Entity\Get
 120    * @return array
 121    */
 122   public static function getInfo() {
 123     $info = [
 124       'name' => static::getEntityName(),
 125       'title' => static::getEntityTitle(),
 126       'titlePlural' => static::getEntityTitle(TRUE),
 127       'type' => self::stripNamespace(get_parent_class(static::class)),
 128     ];
 129     $reflection = new \ReflectionClass(static::class);
 130     $info += ReflectionUtils::getCodeDocs($reflection, NULL, ['entity' => $info['name']]);
 131     unset($info['package'], $info['method']);
 132     return $info;
 133   }
 134
 135   /**
 136    * Remove namespace prefix from a class name
 137    *
 138    * @param string $className
 139    * @return string
 140    */
 141   private static function stripNamespace($className) {
 142     return substr($className, strrpos($className, '\\') + 1);
 143   }
 144
 145 }