Civi/API/Request.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11 namespace Civi\API;
  12
  13 /**
  14  * Class Request
  15  * @package Civi\API
  16  */
  17 class Request {
  18   private static $nextId = 1;
  19
  20   /**
  21    * Create a formatted/normalized request object.
  22    *
  23    * @param string $entity
  24    *   API entity name.
  25    * @param string $action
  26    *   API action name.
  27    * @param array $params
  28    *   API parameters.
  29    * @param mixed $extra
  30    *   Who knows? ...
  31    *
  32    * @throws \API_Exception
  33    * @return array
  34    *   the request descriptor; keys:
  35    *   - version: int
  36    *   - entity: string
  37    *   - action: string
  38    *   - params: array (string $key => mixed $value) [deprecated in v4]
  39    *   - extra: unspecified
  40    *   - fields: NULL|array (string $key => array $fieldSpec)
  41    *   - options: \CRM_Utils_OptionBag derived from params [v4-only]
  42    *   - data: \CRM_Utils_OptionBag derived from params [v4-only]
  43    *   - chains: unspecified derived from params [v4-only]
  44    */
  45   public static function create($entity, $action, $params, $extra = NULL) {
  46     $version = \CRM_Utils_Array::value('version', $params);
  47     switch ($version) {
  48       default:
  49         $apiRequest = [];
  50         $apiRequest['id'] = self::$nextId++;
  51         $apiRequest['version'] = (int) $version;
  52         $apiRequest['params'] = $params;
  53         $apiRequest['extra'] = $extra;
  54         $apiRequest['fields'] = NULL;
  55         $apiRequest['entity'] = self::normalizeEntityName($entity, $apiRequest['version']);
  56         $apiRequest['action'] = self::normalizeActionName($action, $apiRequest['version']);
  57         return $apiRequest;
  58
  59       case 4:
  60         $callable = ["Civi\\Api4\\$entity", $action];
  61         if (!is_callable($callable)) {
  62           throw new Exception\NotImplementedException("API ($entity, $action) does not exist (join the API team and implement it!)");
  63         }
  64         $apiCall = call_user_func($callable);
  65         $apiRequest['id'] = self::$nextId++;
  66         unset($params['version']);
  67         foreach ($params as $name => $param) {
  68           $setter = 'set' . ucfirst($name);
  69           $apiCall->$setter($param);
  70         }
  71         return $apiCall;
  72     }
  73
  74   }
  75
  76   /**
  77    * Normalize entity to be CamelCase.
  78    *
  79    * APIv1-v3 munges entity/action names, and accepts any mixture of case and underscores.
  80    *
  81    * @param string $entity
  82    * @param int $version
  83    * @return string
  84    */
  85   public static function normalizeEntityName($entity, $version) {
  86     return \CRM_Utils_String::convertStringToCamel(\CRM_Utils_String::munge($entity));
  87   }
  88
  89   /**
  90    * Normalize api action name to be lowercase.
  91    *
  92    * APIv1-v3 munges entity/action names, and accepts any mixture of case and underscores.
  93    *
  94    * @param $action
  95    * @param $version
  96    * @return string
  97    */
  98   public static function normalizeActionName($action, $version) {
  99     return strtolower(\CRM_Utils_String::munge($action));
 100   }
 101
 102   public static function getNextId() {
 103     return self::$nextId++;
 104   }
 105
 106 }