3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.6 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2014 |
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 if ($apiRequest['version'] <= 3) {
70 // APIv1-v3 munges entity/action names, which means that the same name can be written
71 // multiple ways. That makes it harder to work with.
72 $apiRequest['entity'] = \CRM_Utils_String
::munge($entity);
73 $action = \CRM_Utils_String
::munge($action);
74 $apiRequest['action'] = strtolower($action{0}) . substr($action, 1);
77 // APIv4 requires exact entity/action name; deviations should cause errors
78 if (!preg_match('/^[a-zA-Z][a-zA-Z0-9]*$/', $entity)) {
79 throw new \
API_Exception("Malformed entity");
81 if (!preg_match('/^[a-zA-Z][a-zA-Z0-9]*$/', $action)) {
82 throw new \
API_Exception("Malformed action");
84 $apiRequest['entity'] = $entity;
85 $apiRequest['action'] = strtolower($action{0}) . substr($action, 1);
88 // APIv1-v3 mix data+options in $params which means that each API callback is responsible
89 // for splitting the two. In APIv4, the split is done systematically so that we don't
90 // so much parsing logic spread around.
91 if ($apiRequest['version'] >= 4) {
95 foreach ($params as $key => $value) {
96 if ($key == 'options') {
97 $options = array_merge($options, $value);
99 elseif ($key == 'return') {
100 if (!isset($options['return'])) {
101 $options['return'] = array();
103 $options['return'] = array_merge($options['return'], $value);
105 elseif (preg_match('/^option\.(.*)$/', $key, $matches)) {
106 $options[$matches[1]] = $value;
108 elseif (preg_match('/^return\.(.*)$/', $key, $matches)) {
110 if (!isset($options['return'])) {
111 $options['return'] = array();
113 $options['return'][] = $matches[1];
116 elseif (preg_match('/^format\.(.*)$/', $key, $matches)) {
118 if (!isset($options['format'])) {
119 $options['format'] = $matches[1];
122 throw new \
API_Exception("Too many API formats specified");
126 elseif (preg_match('/^api\./', $key)) {
127 // FIXME: represent subrequests as instances of "Request"
128 $chains[$key] = $value;
130 elseif ($key == 'debug') {
131 $options['debug'] = $value;
133 elseif ($key == 'version') {
137 $data[$key] = $value;
141 $apiRequest['options'] = new \
CRM_Utils_OptionBag($options);
142 $apiRequest['data'] = new \
CRM_Utils_OptionBag($data);
143 $apiRequest['chains'] = $chains;
150 * We must be sure that every request uses only one version of the API.
152 * @param array $params
156 protected static function parseVersion($params) {
157 $desired_version = empty($params['version']) ?
NULL : (int) $params['version'];
158 if (isset($desired_version) && is_int($desired_version)) {
159 return $desired_version;
162 // we will set the default to version 3 as soon as we find that it works.