Commit | Line | Data |
---|---|---|
6a488035 | 1 | <?php |
6a488035 TO |
2 | |
3 | /** | |
ade83e4b CB |
4 | * |
5 | * This class allows to consume the API, either from within a module that knows civicrm already: | |
6 | * | |
7 | * @code | |
0cd417ef | 8 | * require_once('api/class.api.php'); |
ade83e4b CB |
9 | * $api = new civicrm_api3(); |
10 | * @endcode | |
11 | * | |
12 | * or from any code on the same server as civicrm | |
13 | * | |
14 | * @code | |
15 | * require_once('/your/civi/folder/api/class.api.php'); | |
16 | * // the path to civicrm.settings.php | |
17 | * $api = new civicrm_api3 (array('conf_path'=> '/your/path/to/your/civicrm/or/joomla/site)); | |
18 | * @endcode | |
19 | * | |
20 | * or to query a remote server via the rest api | |
21 | * | |
22 | * @code | |
0cd417ef KW |
23 | * $api = new civicrm_api3 (array ('server' => 'http://example.org', |
24 | * 'api_key'=>'theusersecretkey', | |
25 | * 'key'=>'thesitesecretkey')); | |
ade83e4b CB |
26 | * @endcode |
27 | * | |
28 | * No matter how initialised and if civicrm is local or remote, you use the class the same way. | |
29 | * | |
30 | * @code | |
31 | * $api->{entity}->{action}($params); | |
32 | * @endcode | |
33 | * | |
34 | * So, to get the individual contacts: | |
35 | * | |
36 | * @code | |
37 | * if ($api->Contact->Get(array('contact_type'=>'Individual','return'=>'sort_name,current_employer')) { | |
38 | * // each key of the result array is an attribute of the api | |
39 | * echo "\n contacts found " . $api->count; | |
40 | * foreach ($api->values as $c) { | |
41 | * echo "\n".$c->sort_name. " working for ". $c->current_employer; | |
42 | * } | |
43 | * // in theory, doesn't append | |
44 | * } else { | |
45 | * echo $api->errorMsg(); | |
46 | * } | |
47 | * @endcode | |
48 | * | |
49 | * Or, to create an event: | |
50 | * | |
51 | * @code | |
52 | * if ($api->Event->Create(array('title'=>'Test','event_type_id' => 1,'is_public' => 1,'start_date' => 19430429))) { | |
53 | * echo "created event id:". $api->id; | |
54 | * } else { | |
55 | * echo $api->errorMsg(); | |
56 | * } | |
57 | * @endcode | |
58 | * | |
59 | * To make it easier, the Actions can either take for input an | |
60 | * associative array $params, or simply an id. The following two lines | |
61 | * are equivalent. | |
62 | * | |
63 | * @code | |
64 | * $api->Activity->Get (42); | |
65 | * $api->Activity->Get (array('id'=>42)); | |
66 | * @endcode | |
67 | * | |
68 | * | |
69 | * You can also get the result like civicrm_api does, but as an object | |
70 | * instead of an array (eg $entity->attribute instead of | |
71 | * $entity['attribute']). | |
72 | * | |
73 | * @code | |
74 | * $result = $api->result; | |
75 | * // is the json encoded result | |
76 | * echo $api; | |
77 | * @endcode | |
6a488035 TO |
78 | */ |
79 | class civicrm_api3 { | |
ade83e4b CB |
80 | |
81 | /** | |
dc64d047 EM |
82 | * Class constructor. |
83 | * | |
decce855 | 84 | * @param array $config API configuration. |
ade83e4b | 85 | */ |
3bdca100 | 86 | public function __construct($config = NULL) { |
6a488035 TO |
87 | $this->local = TRUE; |
88 | $this->input = array(); | |
89 | $this->lastResult = array(); | |
90 | if (isset($config) && isset($config['server'])) { | |
91 | // we are calling a remote server via REST | |
92 | $this->local = FALSE; | |
93 | $this->uri = $config['server']; | |
94 | if (isset($config['path'])) { | |
95 | $this->uri .= "/" . $config['path']; | |
96 | } | |
ade83e4b CB |
97 | else { |
98 | $this->uri .= '/sites/all/modules/civicrm/extern/rest.php'; | |
99 | } | |
6a488035 TO |
100 | if (isset($config['key'])) { |
101 | $this->key = $config['key']; | |
102 | } | |
103 | else { | |
104 | die("\nFATAL:param['key] missing\n"); | |
105 | } | |
106 | if (isset($config['api_key'])) { | |
107 | $this->api_key = $config['api_key']; | |
108 | } | |
109 | else { | |
110 | die("\nFATAL:param['api_key] missing\n"); | |
111 | } | |
6a488035 TO |
112 | return; |
113 | } | |
114 | if (isset($config) && isset($config['conf_path'])) { | |
a788b190 | 115 | if (!defined('CIVICRM_SETTINGS_PATH')) { |
116 | define('CIVICRM_SETTINGS_PATH', $config['conf_path'] . '/civicrm.settings.php'); | |
117 | } | |
6a488035 | 118 | require_once CIVICRM_SETTINGS_PATH; |
f9c7ce43 | 119 | require_once 'CRM/Core/ClassLoader.php'; |
6a488035 TO |
120 | require_once 'api/api.php'; |
121 | require_once "api/v3/utils.php"; | |
f9c7ce43 | 122 | CRM_Core_ClassLoader::singleton()->register(); |
6a488035 TO |
123 | $this->cfg = CRM_Core_Config::singleton(); |
124 | $this->init(); | |
125 | } | |
126 | else { | |
127 | $this->cfg = CRM_Core_Config::singleton(); | |
128 | } | |
129 | } | |
130 | ||
ade83e4b | 131 | /** |
dc64d047 EM |
132 | * Convert to string. |
133 | * | |
c490a46a | 134 | * @return string |
ade83e4b | 135 | */ |
6a488035 TO |
136 | public function __toString() { |
137 | return json_encode($this->lastResult); | |
138 | } | |
139 | ||
ade83e4b | 140 | /** |
dc64d047 EM |
141 | * Perform action. |
142 | * | |
645ee340 EM |
143 | * @param $action |
144 | * @param $params | |
dc64d047 | 145 | * |
645ee340 | 146 | * @return bool |
ade83e4b | 147 | */ |
6a488035 | 148 | public function __call($action, $params) { |
ade83e4b | 149 | // @TODO Check if it's a valid action. |
6a488035 TO |
150 | if (isset($params[0])) { |
151 | return $this->call($this->currentEntity, $action, $params[0]); | |
152 | } | |
153 | else { | |
154 | return $this->call($this->currentEntity, $action, $this->input); | |
155 | } | |
156 | } | |
157 | ||
ade83e4b | 158 | /** |
dc64d047 EM |
159 | * Call via rest. |
160 | * | |
645ee340 EM |
161 | * @param $entity |
162 | * @param $action | |
163 | * @param array $params | |
dc64d047 | 164 | * |
645ee340 | 165 | * @return \stdClass |
ade83e4b | 166 | */ |
5a28e17c | 167 | private function remoteCall($entity, $action, $params = array()) { |
735682e9 | 168 | $query = $this->uri . "?entity=$entity&action=$action"; |
5a28e17c CW |
169 | $fields = http_build_query(array( |
170 | 'key' => $this->key, | |
171 | 'api_key' => $this->api_key, | |
172 | 'json' => json_encode($params), | |
173 | )); | |
735682e9 | 174 | |
6a488035 | 175 | if (function_exists('curl_init')) { |
ade83e4b CB |
176 | // To facilitate debugging without leaking info, entity & action |
177 | // are GET, other data is POST. | |
6a488035 TO |
178 | $ch = curl_init(); |
179 | curl_setopt($ch, CURLOPT_URL, $query); | |
735682e9 | 180 | curl_setopt($ch, CURLOPT_POST, TRUE); |
6a488035 TO |
181 | curl_setopt($ch, CURLOPT_POSTFIELDS, $fields); |
182 | curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); | |
6a488035 | 183 | $result = curl_exec($ch); |
7a514fb1 CB |
184 | // CiviCRM expects to get back a CiviCRM error object. |
185 | if (curl_errno($ch)) { | |
3bdca100 | 186 | $res = new stdClass(); |
ade83e4b | 187 | $res->is_error = 1; |
7922c1d3 XD |
188 | $res->error_message = curl_error($ch); |
189 | $res->level = "cURL"; | |
ade83e4b CB |
190 | $res->error = array('cURL error' => curl_error($ch)); |
191 | return $res; | |
8ef12e64 | 192 | } |
6a488035 | 193 | curl_close($ch); |
6a488035 TO |
194 | } |
195 | else { | |
ade83e4b CB |
196 | // Should be discouraged, because the API credentials and data |
197 | // are submitted as GET data, increasing chance of exposure.. | |
6a488035 | 198 | $result = file_get_contents($query . '&' . $fields); |
6a488035 | 199 | } |
78a069a9 | 200 | if (!$res = json_decode($result)) { |
3bdca100 | 201 | $res = new stdClass(); |
78a069a9 CB |
202 | $res->is_error = 1; |
203 | $res->error_message = 'Unable to parse returned JSON'; | |
204 | $res->level = 'json_decode'; | |
205 | $res->error = array('Unable to parse returned JSON' => $result); | |
206 | $res->row_result = $result; | |
207 | } | |
208 | return $res; | |
6a488035 TO |
209 | } |
210 | ||
aa1b1481 | 211 | /** |
dc64d047 EM |
212 | * Call api function. |
213 | * | |
aa1b1481 EM |
214 | * @param $entity |
215 | * @param string $action | |
216 | * @param array $params | |
217 | * | |
218 | * @return bool | |
219 | */ | |
5a28e17c | 220 | private function call($entity, $action = 'Get', $params = array()) { |
6a488035 TO |
221 | if (is_int($params)) { |
222 | $params = array('id' => $params); | |
223 | } | |
224 | elseif (is_string($params)) { | |
225 | $params = json_decode($params); | |
226 | } | |
227 | ||
228 | if (!isset($params['version'])) { | |
6a488035 TO |
229 | $params['version'] = 3; |
230 | } | |
231 | if (!isset($params['sequential'])) { | |
232 | $params['sequential'] = 1; | |
233 | } | |
234 | ||
235 | if (!$this->local) { | |
236 | $this->lastResult = $this->remoteCall($entity, $action, $params); | |
237 | } | |
238 | else { | |
ade83e4b | 239 | // Converts a multi-dimentional array into an object. |
6a488035 TO |
240 | $this->lastResult = json_decode(json_encode(civicrm_api($entity, $action, $params))); |
241 | } | |
ade83e4b | 242 | // Reset the input to be ready for a new call. |
6a488035 TO |
243 | $this->input = array(); |
244 | if (property_exists($this->lastResult, 'is_error')) { | |
245 | return !$this->lastResult->is_error; | |
246 | } | |
ade83e4b | 247 | // getsingle doesn't have is_error. |
6a488035 TO |
248 | return TRUE; |
249 | } | |
250 | ||
ade83e4b CB |
251 | /** |
252 | * Helper method for long running programs (eg bots). | |
253 | */ | |
3bdca100 | 254 | public function ping() { |
6a488035 TO |
255 | global $_DB_DATAOBJECT; |
256 | foreach ($_DB_DATAOBJECT['CONNECTIONS'] as & $c) { | |
257 | if (!$c->connection->ping()) { | |
258 | $c->connect($this->cfg->dsn); | |
259 | if (!$c->connection->ping()) { | |
260 | die("we couldn't connect"); | |
261 | } | |
262 | } | |
263 | } | |
264 | } | |
265 | ||
ade83e4b CB |
266 | /** |
267 | * Return the last error message. | |
c490a46a | 268 | * @return string |
ade83e4b | 269 | */ |
3bdca100 | 270 | public function errorMsg() { |
6a488035 TO |
271 | return $this->lastResult->error_message; |
272 | } | |
273 | ||
ade83e4b | 274 | /** |
1747ab99 | 275 | * Initialize. |
ade83e4b | 276 | */ |
3bdca100 | 277 | public function init() { |
6a488035 TO |
278 | CRM_Core_DAO::init($this->cfg->dsn); |
279 | } | |
280 | ||
ade83e4b | 281 | /** |
1747ab99 EM |
282 | * Get attribute. |
283 | * | |
645ee340 EM |
284 | * @param $name |
285 | * @param null $value | |
1747ab99 | 286 | * |
c490a46a | 287 | * @return $this |
6a488035 | 288 | */ |
6a488035 TO |
289 | public function attr($name, $value = NULL) { |
290 | if ($value === NULL) { | |
291 | if (property_exists($this->lastResult, $name)) { | |
292 | return $this->lastResult->$name; | |
293 | } | |
294 | } | |
295 | else { | |
296 | $this->input[$name] = $value; | |
297 | } | |
298 | return $this; | |
299 | } | |
300 | ||
ade83e4b | 301 | /** |
dc64d047 EM |
302 | * Is this an error. |
303 | * | |
c490a46a | 304 | * @return bool |
ade83e4b | 305 | */ |
6a488035 TO |
306 | public function is_error() { |
307 | return (property_exists($this->lastResult, 'is_error') && $this->lastResult->is_error); | |
308 | } | |
309 | ||
ade83e4b | 310 | /** |
1747ab99 EM |
311 | * Check if var is set. |
312 | * | |
100fef9d | 313 | * @param string $name |
dc64d047 | 314 | * |
c490a46a | 315 | * @return bool |
ade83e4b | 316 | */ |
6a488035 TO |
317 | public function is_set($name) { |
318 | return (isset($this->lastResult->$name)); | |
319 | } | |
320 | ||
ade83e4b | 321 | /** |
1747ab99 EM |
322 | * Get object. |
323 | * | |
324 | * @param string $name | |
dc64d047 | 325 | * |
c490a46a | 326 | * @return $this |
ade83e4b | 327 | */ |
6a488035 | 328 | public function __get($name) { |
ade83e4b | 329 | // @TODO Test if valid entity. |
6a488035 | 330 | if (strtolower($name) !== $name) { |
ade83e4b CB |
331 | // Cheap and dumb test to differentiate call to |
332 | // $api->Entity->Action & value retrieval. | |
6a488035 TO |
333 | $this->currentEntity = $name; |
334 | return $this; | |
335 | } | |
6a488035 | 336 | if ($name === 'result') { |
6a488035 TO |
337 | return $this->lastResult; |
338 | } | |
339 | if ($name === 'values') { | |
340 | return $this->lastResult->values; | |
341 | } | |
6a488035 | 342 | if (property_exists($this->lastResult, $name)) { |
6a488035 TO |
343 | return $this->lastResult->$name; |
344 | } | |
6a488035 TO |
345 | $this->currentEntity = $name; |
346 | return $this; | |
347 | } | |
348 | ||
ade83e4b CB |
349 | /** |
350 | * Or use $api->value. | |
c490a46a | 351 | * @return array |
ade83e4b | 352 | */ |
6a488035 TO |
353 | public function values() { |
354 | if (is_array($this->lastResult)) { | |
355 | return $this->lastResult['values']; | |
356 | } | |
ade83e4b CB |
357 | else { |
358 | return $this->lastResult->values; | |
359 | } | |
6a488035 TO |
360 | } |
361 | ||
ade83e4b CB |
362 | /** |
363 | * Or use $api->result. | |
c490a46a | 364 | * @return array |
ade83e4b | 365 | */ |
6a488035 TO |
366 | public function result() { |
367 | return $this->lastResult; | |
368 | } | |
96025800 | 369 | |
6a488035 | 370 | } |