3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.7 |
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 $apiRequest['entity'] = $entity = self
::normalizeEntityName($entity, $apiRequest['version']);
70 $apiRequest['action'] = $action = self
::normalizeActionName($action, $apiRequest['version']);
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) {
79 foreach ($params as $key => $value) {
80 if ($key == 'options') {
81 $options = array_merge($options, $value);
83 elseif ($key == 'return') {
84 if (!isset($options['return'])) {
85 $options['return'] = array();
87 $options['return'] = array_merge($options['return'], $value);
89 elseif (preg_match('/^option\.(.*)$/', $key, $matches)) {
90 $options[$matches[1]] = $value;
92 elseif (preg_match('/^return\.(.*)$/', $key, $matches)) {
94 if (!isset($options['return'])) {
95 $options['return'] = array();
97 $options['return'][] = $matches[1];
100 elseif (preg_match('/^format\.(.*)$/', $key, $matches)) {
102 if (!isset($options['format'])) {
103 $options['format'] = $matches[1];
106 throw new \
API_Exception("Too many API formats specified");
110 elseif (preg_match('/^api\./', $key)) {
111 // FIXME: represent subrequests as instances of "Request"
112 $chains[$key] = $value;
114 elseif ($key == 'debug') {
115 $options['debug'] = $value;
117 elseif ($key == 'version') {
121 $data[$key] = $value;
125 $apiRequest['options'] = new \
CRM_Utils_OptionBag($options);
126 $apiRequest['data'] = new \
CRM_Utils_OptionBag($data);
127 $apiRequest['chains'] = $chains;
134 * Normalize/validate entity and action names
136 * @param string $entity
137 * @param int $version
139 * @throws \API_Exception
141 public static function normalizeEntityName($entity, $version) {
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));
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");
156 public static function normalizeActionName($action, $version) {
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));
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");
167 // TODO: Not sure about camelCase actions - in v3 they are all lowercase.
168 return strtolower($action{0}) . substr($action, 1);
173 * We must be sure that every request uses only one version of the API.
175 * @param array $params
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;
185 // we will set the default to version 3 as soon as we find that it works.