3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.4 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2013 |
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
40 * @param string $action
41 * @param array $params
44 * @throws \API_Exception
45 * @return array the request descriptor; keys:
49 * - params: array (string $key => mixed $value) [deprecated in v4]
50 * - extra: unspecified
51 * - fields: NULL|array (string $key => array $fieldSpec)
52 * - options: \CRM_Utils_OptionBag derived from params [v4-only]
53 * - data: \CRM_Utils_OptionBag derived from params [v4-only]
54 * - chains: unspecified derived from params [v4-only]
56 public static function create($entity, $action, $params, $extra) {
57 $apiRequest = array(); // new \Civi\API\Request();
58 $apiRequest['id'] = self
::$nextId++
;
59 $apiRequest['version'] = self
::parseVersion($params);
60 $apiRequest['params'] = $params;
61 $apiRequest['extra'] = $extra;
62 $apiRequest['fields'] = NULL;
64 if ($apiRequest['version'] <= 3) {
65 // APIv1-v3 munges entity/action names, which means that the same name can be written
66 // multiple ways. That makes it harder to work with.
67 $apiRequest['entity'] = \CRM_Utils_String
::munge($entity);
68 $action = \CRM_Utils_String
::munge($action);
69 $apiRequest['action'] = strtolower($action{0}) . substr($action, 1);
72 // APIv4 requires exact entity/action name; deviations should cause errors
73 if (!preg_match('/^[a-zA-Z][a-zA-Z0-9]*$/', $entity)) {
74 throw new \
API_Exception("Malformed entity");
76 if (!preg_match('/^[a-zA-Z][a-zA-Z0-9]*$/', $action)) {
77 throw new \
API_Exception("Malformed action");
79 $apiRequest['entity'] = $entity;
80 $apiRequest['action'] = strtolower($action{0}) . substr($action, 1);
83 // APIv1-v3 mix data+options in $params which means that each API callback is responsible
84 // for splitting the two. In APIv4, the split is done systematically so that we don't
85 // so much parsing logic spread around.
86 if ($apiRequest['version'] >= 4) {
90 foreach ($params as $key => $value) {
91 if ($key == 'options') {
92 $options = array_merge($options, $value);
94 elseif ($key == 'return') {
95 if (!isset($options['return'])) {
96 $options['return'] = array();
98 $options['return'] = array_merge($options['return'], $value);
100 elseif (preg_match('/^option\.(.*)$/', $key, $matches)) {
101 $options[$matches[1]] = $value;
103 elseif (preg_match('/^return\.(.*)$/', $key, $matches)) {
105 if (!isset($options['return'])) {
106 $options['return'] = array();
108 $options['return'][] = $matches[1];
111 elseif (preg_match('/^format\.(.*)$/', $key, $matches)) {
113 if (!isset($options['format'])) {
114 $options['format'] = $matches[1];
117 throw new \
API_Exception("Too many API formats specified");
121 elseif (preg_match('/^api\./', $key)) {
122 // FIXME: represent subrequests as instances of "Request"
123 $chains[$key] = $value;
125 elseif ($key == 'debug') {
126 $options['debug'] = $value;
128 elseif ($key == 'version') {
132 $data[$key] = $value;
136 $apiRequest['options'] = new \
CRM_Utils_OptionBag($options);
137 $apiRequest['data'] = new \
CRM_Utils_OptionBag($data);
138 $apiRequest['chains'] = $chains;
145 * We must be sure that every request uses only one version of the API.
147 * @param array $params
150 protected static function parseVersion($params) {
151 $desired_version = empty($params['version']) ?
NULL : (int) $params['version'];
152 if (isset($desired_version) && is_integer($desired_version)) {
153 return $desired_version;
156 // we will set the default to version 3 as soon as we find that it works.