Civi/API/Request.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2019                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  10  | CiviCRM is free software; you can copy, modify, and distribute it  |
  11  | under the terms of the GNU Affero General Public License           |
  12  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13  |                                                                    |
  14  | CiviCRM is distributed in the hope that it will be useful, but     |
  15  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17  | See the GNU Affero General Public License for more details.        |
  18  |                                                                    |
  19  | You should have received a copy of the GNU Affero General Public   |
  20  | License and the CiviCRM Licensing Exception along                  |
  21  | with this program; if not, contact CiviCRM LLC                     |
  22  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23  | GNU Affero General Public License or the licensing of CiviCRM,     |
  24  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25  +--------------------------------------------------------------------+
  26  */
  27 namespace Civi\API;
  28
  29 /**
  30  * Class Request
  31  * @package Civi\API
  32  */
  33 class Request {
  34   private static $nextId = 1;
  35
  36   /**
  37    * Create a formatted/normalized request object.
  38    *
  39    * @param string $entity
  40    *   API entity name.
  41    * @param string $action
  42    *   API action name.
  43    * @param array $params
  44    *   API parameters.
  45    * @param mixed $extra
  46    *   Who knows? ...
  47    *
  48    * @throws \API_Exception
  49    * @return array
  50    *   the request descriptor; keys:
  51    *   - version: int
  52    *   - entity: string
  53    *   - action: string
  54    *   - params: array (string $key => mixed $value) [deprecated in v4]
  55    *   - extra: unspecified
  56    *   - fields: NULL|array (string $key => array $fieldSpec)
  57    *   - options: \CRM_Utils_OptionBag derived from params [v4-only]
  58    *   - data: \CRM_Utils_OptionBag derived from params [v4-only]
  59    *   - chains: unspecified derived from params [v4-only]
  60    */
  61   public static function create($entity, $action, $params, $extra = NULL) {
  62     $version = \CRM_Utils_Array::value('version', $params);
  63     switch ($version) {
  64       default:
  65         $apiRequest = array();
  66         $apiRequest['id'] = self::$nextId++;
  67         $apiRequest['version'] = (int) $version;
  68         $apiRequest['params'] = $params;
  69         $apiRequest['extra'] = $extra;
  70         $apiRequest['fields'] = NULL;
  71         $apiRequest['entity'] = self::normalizeEntityName($entity, $apiRequest['version']);
  72         $apiRequest['action'] = self::normalizeActionName($action, $apiRequest['version']);
  73         return $apiRequest;
  74
  75       case 4:
  76         $callable = array("Civi\\Api4\\$entity", $action);
  77         if (!is_callable($callable)) {
  78           throw new Exception\NotImplementedException("API ($entity, $action) does not exist (join the API team and implement it!)");
  79         }
  80         $apiCall = call_user_func($callable);
  81         $apiRequest['id'] = self::$nextId++;
  82         unset($params['version']);
  83         foreach ($params as $name => $param) {
  84           $setter = 'set' . ucfirst($name);
  85           $apiCall->$setter($param);
  86         }
  87         return $apiCall;
  88     }
  89
  90   }
  91
  92   /**
  93    * Normalize entity to be CamelCase.
  94    *
  95    * APIv1-v3 munges entity/action names, and accepts any mixture of case and underscores.
  96    *
  97    * @param string $entity
  98    * @param int $version
  99    * @return string
 100    */
 101   public static function normalizeEntityName($entity, $version) {
 102     return \CRM_Utils_String::convertStringToCamel(\CRM_Utils_String::munge($entity));
 103   }
 104
 105   /**
 106    * Normalize api action name to be lowercase.
 107    *
 108    * APIv1-v3 munges entity/action names, and accepts any mixture of case and underscores.
 109    *
 110    * @param $action
 111    * @param $version
 112    * @return string
 113    */
 114   public static function normalizeActionName($action, $version) {
 115     return strtolower(\CRM_Utils_String::munge($action));
 116   }
 117
 118 }