3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.6 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2015 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
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. |
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. |
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 +--------------------------------------------------------------------+
34 private static $nextId = 1;
37 * Create a formatted/normalized request object.
39 * @param string $entity
41 * @param string $action
43 * @param array $params
48 * @throws \API_Exception
50 * the request descriptor; keys:
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]
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;
69 self
::normalizeNames($entity, $action, $apiRequest);
71 // APIv1-v3 mix data+options in $params which means that each API callback is responsible
72 // for splitting the two. In APIv4, the split is done systematically so that we don't
73 // so much parsing logic spread around.
74 if ($apiRequest['version'] >= 4) {
78 foreach ($params as $key => $value) {
79 if ($key == 'options') {
80 $options = array_merge($options, $value);
82 elseif ($key == 'return') {
83 if (!isset($options['return'])) {
84 $options['return'] = array();
86 $options['return'] = array_merge($options['return'], $value);
88 elseif (preg_match('/^option\.(.*)$/', $key, $matches)) {
89 $options[$matches[1]] = $value;
91 elseif (preg_match('/^return\.(.*)$/', $key, $matches)) {
93 if (!isset($options['return'])) {
94 $options['return'] = array();
96 $options['return'][] = $matches[1];
99 elseif (preg_match('/^format\.(.*)$/', $key, $matches)) {
101 if (!isset($options['format'])) {
102 $options['format'] = $matches[1];
105 throw new \
API_Exception("Too many API formats specified");
109 elseif (preg_match('/^api\./', $key)) {
110 // FIXME: represent subrequests as instances of "Request"
111 $chains[$key] = $value;
113 elseif ($key == 'debug') {
114 $options['debug'] = $value;
116 elseif ($key == 'version') {
120 $data[$key] = $value;
124 $apiRequest['options'] = new \
CRM_Utils_OptionBag($options);
125 $apiRequest['data'] = new \
CRM_Utils_OptionBag($data);
126 $apiRequest['chains'] = $chains;
133 * Normalize/validate entity and action names
135 * @param string $entity
136 * @param string $action
137 * @param array $apiRequest
138 * @throws \API_Exception
140 protected static function normalizeNames(&$entity, &$action, &$apiRequest) {
141 if ($apiRequest['version'] <= 3) {
142 // APIv1-v3 munges entity/action names, and accepts any mixture of case and underscores.
143 // We normalize entity to be CamelCase and action to be lowercase.
144 $apiRequest['entity'] = $entity = \CRM_Utils_String
::convertStringToCamel(\CRM_Utils_String
::munge($entity));
145 $apiRequest['action'] = $action = strtolower(\CRM_Utils_String
::munge($action));
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");
152 if (!preg_match('/^[a-zA-Z][a-zA-Z0-9]*$/', $action)) {
153 throw new \
API_Exception("Malformed action");
155 $apiRequest['entity'] = $entity;
156 // TODO: Not sure about camelCase actions - in v3 they are all lowercase.
157 $apiRequest['action'] = strtolower($action{0}) . substr($action, 1);
162 * We must be sure that every request uses only one version of the API.
164 * @param array $params
168 protected static function parseVersion($params) {
169 $desired_version = empty($params['version']) ?
NULL : (int) $params['version'];
170 if (isset($desired_version) && is_int($desired_version)) {
171 return $desired_version;
174 // we will set the default to version 3 as soon as we find that it works.