crm.fsf.org/20131203/files/sites/all/modules-old/civicrm/Civi/API/Request.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.6                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2015                                |
   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) {
  62     $apiRequest = array(); // new \Civi\API\Request();
  63     $apiRequest['id'] = self::$nextId++;
  64     $apiRequest['version'] = self::parseVersion($params);
  65     $apiRequest['params'] = $params;
  66     $apiRequest['extra'] = $extra;
  67     $apiRequest['fields'] = NULL;
  68
  69     $apiRequest['entity'] = $entity = self::normalizeEntityName($entity, $apiRequest['version']);
  70     $apiRequest['action'] = $action = self::normalizeActionName($action, $apiRequest['version']);
  71
  72     // APIv1-v3 mix data+options in $params which means that each API callback is responsible
  73     // for splitting the two. In APIv4, the split is done systematically so that we don't
  74     // so much parsing logic spread around.
  75     if ($apiRequest['version'] >= 4) {
  76       $options = array();
  77       $data = array();
  78       $chains = array();
  79       foreach ($params as $key => $value) {
  80         if ($key == 'options') {
  81           $options = array_merge($options, $value);
  82         }
  83         elseif ($key == 'return') {
  84           if (!isset($options['return'])) {
  85             $options['return'] = array();
  86           }
  87           $options['return'] = array_merge($options['return'], $value);
  88         }
  89         elseif (preg_match('/^option\.(.*)$/', $key, $matches)) {
  90           $options[$matches[1]] = $value;
  91         }
  92         elseif (preg_match('/^return\.(.*)$/', $key, $matches)) {
  93           if ($value) {
  94             if (!isset($options['return'])) {
  95               $options['return'] = array();
  96             }
  97             $options['return'][] = $matches[1];
  98           }
  99         }
 100         elseif (preg_match('/^format\.(.*)$/', $key, $matches)) {
 101           if ($value) {
 102             if (!isset($options['format'])) {
 103               $options['format'] = $matches[1];
 104             }
 105             else {
 106               throw new \API_Exception("Too many API formats specified");
 107             }
 108           }
 109         }
 110         elseif (preg_match('/^api\./', $key)) {
 111           // FIXME: represent subrequests as instances of "Request"
 112           $chains[$key] = $value;
 113         }
 114         elseif ($key == 'debug') {
 115           $options['debug'] = $value;
 116         }
 117         elseif ($key == 'version') {
 118           // ignore
 119         }
 120         else {
 121           $data[$key] = $value;
 122
 123         }
 124       }
 125       $apiRequest['options'] = new \CRM_Utils_OptionBag($options);
 126       $apiRequest['data'] = new \CRM_Utils_OptionBag($data);
 127       $apiRequest['chains'] = $chains;
 128     }
 129
 130     return $apiRequest;
 131   }
 132
 133   /**
 134    * Normalize/validate entity and action names
 135    *
 136    * @param string $entity
 137    * @param int $version
 138    * @return string
 139    * @throws \API_Exception
 140    */
 141   public static function normalizeEntityName($entity, $version) {
 142     if ($version <= 3) {
 143       // APIv1-v3 munges entity/action names, and accepts any mixture of case and underscores.
 144       // We normalize entity to be CamelCase.
 145       return \CRM_Utils_String::convertStringToCamel(\CRM_Utils_String::munge($entity));
 146     }
 147     else {
 148       // APIv4 requires exact spelling & capitalization of entity/action name; deviations should cause errors
 149       if (!preg_match('/^[a-zA-Z][a-zA-Z0-9]*$/', $entity)) {
 150         throw new \API_Exception("Malformed entity");
 151       }
 152       return $entity;
 153     }
 154   }
 155
 156   public static function normalizeActionName($action, $version) {
 157     if ($version <= 3) {
 158       // APIv1-v3 munges entity/action names, and accepts any mixture of case and underscores.
 159       // We normalize action to be lowercase.
 160       return strtolower(\CRM_Utils_String::munge($action));
 161     }
 162     else {
 163       // APIv4 requires exact spelling & capitalization of entity/action name; deviations should cause errors
 164       if (!preg_match('/^[a-zA-Z][a-zA-Z0-9]*$/', $action)) {
 165         throw new \API_Exception("Malformed action");
 166       }
 167       // TODO: Not sure about camelCase actions - in v3 they are all lowercase.
 168       return strtolower($action{0}) . substr($action, 1);
 169     }
 170   }
 171
 172   /**
 173    * We must be sure that every request uses only one version of the API.
 174    *
 175    * @param array $params
 176    *   API parameters.
 177    * @return int
 178    */
 179   protected static function parseVersion($params) {
 180     $desired_version = empty($params['version']) ? NULL : (int) $params['version'];
 181     if (isset($desired_version) && is_int($desired_version)) {
 182       return $desired_version;
 183     }
 184     else {
 185       // we will set the default to version 3 as soon as we find that it works.
 186       return 3;
 187     }
 188   }
 189
 190 }