Civi/Api4/Generic/AbstractEntity.php

   1 <?php
   2
   3 /*
   4  +--------------------------------------------------------------------+
   5  | CiviCRM version 5                                                  |
   6  +--------------------------------------------------------------------+
   7  | Copyright CiviCRM LLC (c) 2004-2019                                |
   8  +--------------------------------------------------------------------+
   9  | This file is a part of CiviCRM.                                    |
  10  |                                                                    |
  11  | CiviCRM is free software; you can copy, modify, and distribute it  |
  12  | under the terms of the GNU Affero General Public License           |
  13  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  14  |                                                                    |
  15  | CiviCRM is distributed in the hope that it will be useful, but     |
  16  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  17  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  18  | See the GNU Affero General Public License for more details.        |
  19  |                                                                    |
  20  | You should have received a copy of the GNU Affero General Public   |
  21  | License and the CiviCRM Licensing Exception along                  |
  22  | with this program; if not, contact CiviCRM LLC                     |
  23  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  24  | GNU Affero General Public License or the licensing of CiviCRM,     |
  25  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  26  +--------------------------------------------------------------------+
  27  */
  28
  29 /**
  30  *
  31  * @package CRM
  32  * @copyright CiviCRM LLC (c) 2004-2019
  33  * $Id$
  34  *
  35  */
  36
  37 namespace Civi\Api4\Generic;
  38
  39 use Civi\API\Exception\NotImplementedException;
  40
  41 /**
  42  * Base class for all api entities.
  43  *
  44  * When adding your own api from an extension, extend this class only
  45  * if your entity does not have an associated DAO. Otherwise extend DAOEntity.
  46  *
  47  * The recommended way to create a non-DAO-based api is to extend this class
  48  * and then add a getFields function and any other actions you wish, e.g.
  49  * - a get() function which returns BasicGetAction using your custom getter callback
  50  * - a create() function which returns BasicCreateAction using your custom setter callback
  51  * - an update() function which returns BasicUpdateAction using your custom setter callback
  52  * - a delete() function which returns BasicBatchAction using your custom delete callback
  53  * - a replace() function which returns BasicReplaceAction (no callback needed but
  54  *   depends on the existence of get, create, update & delete actions)
  55  *
  56  * Note that you can use the same setter callback function for update as create -
  57  * that function can distinguish between new & existing records by checking if the
  58  * unique identifier has been set (identifier field defaults to "id" but you can change
  59  * that when constructing BasicUpdateAction)
  60  */
  61 abstract class AbstractEntity {
  62
  63   /**
  64    * @return \Civi\Api4\Action\GetActions
  65    */
  66   public static function getActions() {
  67     return new \Civi\Api4\Action\GetActions(self::getEntityName(), __FUNCTION__);
  68   }
  69
  70   /**
  71    * Should return \Civi\Api4\Generic\BasicGetFieldsAction
  72    * @todo make this function abstract when we require php 7.
  73    * @throws \Civi\API\Exception\NotImplementedException
  74    */
  75   public static function getFields() {
  76     throw new NotImplementedException(self::getEntityName() . ' should implement getFields action.');
  77   }
  78
  79   /**
  80    * Returns a list of permissions needed to access the various actions in this api.
  81    *
  82    * @return array
  83    */
  84   public static function permissions() {
  85     $permissions = \CRM_Core_Permission::getEntityActionPermissions();
  86
  87     // For legacy reasons the permissions are keyed by lowercase entity name
  88     // Note: Convert to camel & back in order to circumvent all the api3 naming oddities
  89     $lcentity = _civicrm_api_get_entity_name_from_camel(\CRM_Utils_String::convertStringToCamel(self::getEntityName()));
  90     // Merge permissions for this entity with the defaults
  91     return \CRM_Utils_Array::value($lcentity, $permissions, []) + $permissions['default'];
  92   }
  93
  94   /**
  95    * Get entity name from called class
  96    *
  97    * @return string
  98    */
  99   protected static function getEntityName() {
 100     return substr(static::class, strrpos(static::class, '\\') + 1);
 101   }
 102
 103   /**
 104    * Magic method to return the action object for an api.
 105    *
 106    * @param string $action
 107    * @param null $args
 108    * @return AbstractAction
 109    * @throws NotImplementedException
 110    */
 111   public static function __callStatic($action, $args) {
 112     $entity = self::getEntityName();
 113     // Find class for this action
 114     $entityAction = "\\Civi\\Api4\\Action\\$entity\\" . ucfirst($action);
 115     if (class_exists($entityAction)) {
 116       $actionObject = new $entityAction($entity, $action);
 117     }
 118     else {
 119       throw new NotImplementedException("Api $entity $action version 4 does not exist.");
 120     }
 121     return $actionObject;
 122   }
 123
 124 }