Civi/API/Request.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.4                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2013                                |
   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 class Request {
  30   private static $nextId = 1;
  31
  32   /**
  33    * Create a formatted/normalized request object.
  34    *
  35    * @param string $entity
  36    * @param string $action
  37    * @param array $params
  38    * @param mixed $extra
  39    * @return array the request descriptor; keys:
  40    *   - version: int
  41    *   - entity: string
  42    *   - action: string
  43    *   - params: array (string $key => mixed $value) [deprecated in v4]
  44    *   - extra: unspecified
  45    *   - fields: NULL|array (string $key => array $fieldSpec)
  46    *   - options: \CRM_Utils_OptionBag derived from params [v4-only]
  47    *   - data: \CRM_Utils_OptionBag derived from params [v4-only]
  48    *   - chains: unspecified derived from params [v4-only]
  49    */
  50   public static function create($entity, $action, $params, $extra) {
  51     $apiRequest = array(); // new \Civi\API\Request();
  52     $apiRequest['id'] = self::$nextId++;
  53     $apiRequest['version'] = self::parseVersion($params);
  54     $apiRequest['params'] = $params;
  55     $apiRequest['extra'] = $extra;
  56     $apiRequest['fields'] = NULL;
  57
  58     if ($apiRequest['version'] <= 3) {
  59       // APIv1-v3 munges entity/action names, which means that the same name can be written
  60       // multiple ways. That makes it harder to work with.
  61       $apiRequest['entity'] = \CRM_Utils_String::munge($entity);
  62       $action = \CRM_Utils_String::munge($action);
  63       $apiRequest['action'] = strtolower($action{0}) . substr($action, 1);
  64     }
  65     else {
  66       // APIv4 requires exact entity/action name; deviations should cause errors
  67       if (!preg_match('/^[a-zA-Z][a-zA-Z0-9]*$/', $entity)) {
  68         throw new \API_Exception("Malformed entity");
  69       }
  70       if (!preg_match('/^[a-zA-Z][a-zA-Z0-9]*$/', $action)) {
  71         throw new \API_Exception("Malformed action");
  72       }
  73       $apiRequest['entity'] = $entity;
  74       $apiRequest['action'] = strtolower($action{0}) . substr($action, 1);
  75     }
  76
  77     // APIv1-v3 mix data+options in $params which means that each API callback is responsible
  78     // for splitting the two. In APIv4, the split is done systematically so that we don't
  79     // so much parsing logic spread around.
  80     if ($apiRequest['version'] >= 4) {
  81       $options = array();
  82       $data = array();
  83       $chains = array();
  84       foreach ($params as $key => $value) {
  85         if ($key == 'options') {
  86           $options = array_merge($options, $value);
  87         }
  88         elseif ($key == 'return') {
  89           if (!isset($options['return'])) {
  90             $options['return'] = array();
  91           }
  92           $options['return'] = array_merge($options['return'], $value);
  93         }
  94         elseif (preg_match('/^option\.(.*)$/', $key, $matches)) {
  95           $options[$matches[1]] = $value;
  96         }
  97         elseif (preg_match('/^return\.(.*)$/', $key, $matches)) {
  98           if ($value) {
  99             if (!isset($options['return'])) {
 100               $options['return'] = array();
 101             }
 102             $options['return'][] = $matches[1];
 103           }
 104         }
 105         elseif (preg_match('/^format\.(.*)$/', $key, $matches)) {
 106           if ($value) {
 107             if (!isset($options['format'])) {
 108               $options['format'] = $matches[1];
 109             }
 110             else {
 111               throw new \API_Exception("Too many API formats specified");
 112             }
 113           }
 114         }
 115         elseif (preg_match('/^api\./', $key)) {
 116           // FIXME: represent subrequests as instances of "Request"
 117           $chains[$key] = $value;
 118         }
 119         elseif ($key == 'debug') {
 120           $options['debug'] = $value;
 121         }
 122         elseif ($key == 'version') {
 123           // ignore
 124         }
 125         else {
 126           $data[$key] = $value;
 127
 128         }
 129       }
 130       $apiRequest['options'] = new \CRM_Utils_OptionBag($options);
 131       $apiRequest['data'] = new \CRM_Utils_OptionBag($data);
 132       $apiRequest['chains'] = $chains;
 133     }
 134
 135     return $apiRequest;
 136   }
 137
 138   /**
 139    * We must be sure that every request uses only one version of the API.
 140    *
 141    * @param array $params
 142    * @return int
 143    */
 144   protected static function parseVersion($params) {
 145     $desired_version = empty($params['version']) ? NULL : (int) $params['version'];
 146     if (isset($desired_version) && is_integer($desired_version)) {
 147       return $desired_version;
 148     }
 149     else {
 150       // we will set the default to version 3 as soon as we find that it works.
 151       return 3;
 152     }
 153   }
 154
 155 }