1: <?php
2: /*****************************************************************************************
3: * X2Engine Open Source Edition is a customer relationship management program developed by
4: * X2Engine, Inc. Copyright (C) 2011-2016 X2Engine Inc.
5: *
6: * This program is free software; you can redistribute it and/or modify it under
7: * the terms of the GNU Affero General Public License version 3 as published by the
8: * Free Software Foundation with the addition of the following permission added
9: * to Section 15 as permitted in Section 7(a): FOR ANY PART OF THE COVERED WORK
10: * IN WHICH THE COPYRIGHT IS OWNED BY X2ENGINE, X2ENGINE DISCLAIMS THE WARRANTY
11: * OF NON INFRINGEMENT OF THIRD PARTY RIGHTS.
12: *
13: * This program is distributed in the hope that it will be useful, but WITHOUT
14: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15: * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
16: * details.
17: *
18: * You should have received a copy of the GNU Affero General Public License along with
19: * this program; if not, see http://www.gnu.org/licenses or write to the Free
20: * Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
21: * 02110-1301 USA.
22: *
23: * You can contact X2Engine, Inc. P.O. Box 66752, Scotts Valley,
24: * California 95067, USA. or at email address contact@x2engine.com.
25: *
26: * The interactive user interfaces in modified source and object code versions
27: * of this program must display Appropriate Legal Notices, as required under
28: * Section 5 of the GNU Affero General Public License version 3.
29: *
30: * In accordance with Section 7(b) of the GNU Affero General Public License version 3,
31: * these Appropriate Legal Notices must retain the display of the "Powered by
32: * X2Engine" logo. If the display of the logo is not reasonably feasible for
33: * technical reasons, the Appropriate Legal Notices must display the words
34: * "Powered by X2Engine".
35: *****************************************************************************************/
36:
37: /**
38: * Standalone model class for interaction with X2Engine's API
39: *
40: * Remote data insertion & lookup API model. Has multiple magic methods and
41: * automatically makes cURL requests to API controller for ease of use. For each
42: * kind of request, see the method in ApiController that corresponds to it. To
43: * view this reference, look at the URL path for the method. For example 'api/create'
44: * corresponds to actionCreate in ApiController.
45: *
46: * @package application.models
47: * @author Jake Houser <jake@x2engine.com>, Demitri Morgan <demitri@x2engine.com>
48: * @property mixed $responseObject Response data from the server
49: * @property array $modelErrors Validation errors, if any, from the server.
50: * @property int $responseCode (read-only) The most recent HTTP response code
51: * sent back from the server
52: */
53: class APIModel {
54:
55: /**
56: * The user to authenticate with. Set in constructor.
57: * @var string
58: */
59: private $_user = '';
60:
61: /**
62: * The response object from the server
63: * @var array
64: */
65: private $_responseObject = null;
66:
67: /**
68: * Response code from the server
69: * @var int
70: */
71: private $_responseCode = null;
72:
73: /**
74: * The corresponding user key to authenticate with. Set in constructor.
75: * @var string
76: */
77: private $_userKey = '';
78:
79: /**
80: * The base URL of the server for the API to connect to. (i.e. www.yourserver.com/x2engine)
81: * @var string
82: */
83: private $_baseUrl = '';
84:
85: private $_modelErrors;
86:
87: /**
88: * Attributes to be used for creating/updating models.
89: * @var array
90: */
91: public $attributes;
92:
93: /**
94: * Errors generated by API calls.
95: * @var array
96: */
97: public $errors;
98:
99: /**
100: * Constructs a new API model and sets private variables.
101: * @param string $user The username to authenticate with
102: * @param string $userKey The user key to authenticate with
103: * @param string $baseUrl The base path of the server for the API to connect to (i.e. www.yourserver.com/x2engine)
104: */
105: public function __construct($user = null, $userKey = null, $baseUrl = null) {
106: $this->_user = $user;
107: $this->_userKey = $userKey;
108: $this->_baseUrl = $baseUrl;
109: if(strpos($baseUrl,'http://') !== 0) // Assume http if unspecified
110: $this->_baseUrl = "http://{$baseUrl}";
111: $lenUrl = strlen($baseUrl);
112: if(strpos($baseUrl,'index.php') !== $lenUrl-9 && strpos($baseUrl,'index-test.php') !== $lenUrl-14) { // Assume using non-test index
113: $this->_baseUrl = rtrim($this->_baseUrl,'/').'/index.php';
114: }
115: }
116:
117: /**
118: * Getter method for {@link modelErrors}
119: * @return type
120: */
121: public function getModelErrors() {
122: if(isset($this->_modelErrors))
123: return $this->_modelErrors;
124: else
125: return array();
126: }
127:
128: /**
129: * Setter for {@link responseObject}
130: * @param type $response
131: */
132: public function setResponseObject($response) {
133: if(is_string($response)) {
134: $this->_responseObject = json_decode($response,1);
135: if(is_null($this->_responseObject)) // Set it equal to the error returned
136: $this->_responseObject = $response;
137: else if (is_array($this->_responseObject)) {
138: if(array_key_exists('modelErrors', $this->_responseObject) && !empty($this->_responseObject['error'])){
139: $this->_modelErrors = $this->_responseObject['modelErrors'];
140: }else{
141: $this->_modelErrors = array();
142: }
143: } else {
144: $this->_modelErrors = array();
145: }
146:
147: } else if(is_array($response)) {
148: $this->_responseObject = $response;
149: }
150: }
151:
152: /**
153: * Magic getter for {@link responseObject}
154: * @return type
155: */
156: public function getResponseObject() {
157: return $this->_responseObject;
158: }
159:
160: /**
161: * Magic getter for {@link responseCode}
162: * @return type
163: */
164: public function getResponseCode() {
165: return $this->_responseCode;
166: }
167:
168: /**
169: * Obtain the list of tags associated with the model
170: * @param type $modelName
171: * @param type $modelId
172: * @return type
173: */
174: public function getTags($modelName,$modelId) {
175: $ch = $this->_curlHandle("api/tags?".http_build_query(array(
176: 'model' => $modelName,
177: 'id' => $modelId
178: ),'','&'));
179: return json_decode(curl_exec($ch),1);
180: }
181:
182: /**
183: * Tag the model record
184: * @param type $modelName
185: * @param type $modelId
186: * @param type $tags
187: * @return type A
188: */
189: public function addTags($modelName,$modelId,$tags){
190: return json_encode($this->_send("api/tags/$modelName/$modelId", array(
191: 'tags' => json_encode(is_array($tags) ? $tags : array($tags))
192: )),1);
193: }
194:
195: /**
196: * Delete a tag from the model record
197: * @param type $modelName
198: * @param type $modelId
199: * @param type $tag
200: * @return type
201: */
202: public function removeTag($modelName,$modelId,$tag) {
203: $ch = $this->_curlHandle("api/tags/$modelName/$modelId/".ltrim($tag,'#'),array(),array(CURLOPT_CUSTOMREQUEST=>'DELETE'));
204: return json_decode(curl_exec($ch),1);
205: }
206:
207:
208: /**
209: * Sets the model's attributes equal to those of the model contained in the
210: * response from the API, if any, and returns true or false based on how the
211: * API request returned (success or failure).
212: * @param bool $responseIsModel The response object is the attributes of the model
213: */
214: public function processResponse($responseIsModel=false) {
215: if(is_array($this->responseObject)){
216: // Server responded with a valid JSON
217: if(array_key_exists('modelErrors',$this->responseObject))
218: // Populate model errors if any:
219: $this->_modelErrors = $this->responseObject['modelErrors'];
220: if(array_key_exists('model', $this->responseObject) && array_key_exists('error',$this->responseObject)){
221: // API is responding using the data structure where the returned
222: // model's attributes are stored in the "model" property of the
223: // JSON object.
224: if(!$this->responseObject['error'] && $this->responseCode == 200) {
225: // No error. Update local attributes:
226: $this->attributes = $this->responseObject['model'];
227: return true;
228: }else{
229: // API responded with error=true due to validation error
230: $this->errors = $this->responseObject['message'];
231: return false;
232: }
233: }else if($responseIsModel && $this->responseCode == 200){
234: // The action was using the older format where the returned JSON
235: // *is* the model's attributes. Update local attributes:
236: $this->attributes = $this->responseObject;
237: return true;
238: }else if($this->responseCode == 200){
239: // API responded with error=false, but there's no "model" property.
240: // Whatever happened, it succeeded, so do nothing else (nothing
241: // else is necessary) and return true.
242: return true;
243: } else {
244: // API responded with a valid JSON, but the request did not
245: // succeed due to validation error, permissions/authentication
246: // error, or some other error. Thus, simply return false.
247: return false;
248: }
249: }else{
250: // In this case, there's an unrecognized error message that the server
251: // returned for whatever reason.
252: $this->errors = $this->responseObject;
253: return false;
254: }
255: }
256:
257: /**
258: * Creates or updates a model of a given type name using the current attributes.
259: * @param type $modelName
260: * @return boolean
261: */
262: public function modelCreateUpdate($modelName,$action,$attributes=array()) {
263: $ccUrl = "api/$action/model/$modelName";
264: if($action=='update')
265: $ccUrl .= '?'.http_build_query(array('id'=>$this->id),'','&');
266: $this->responseObject = $this->_send($ccUrl, array_merge($this->attributes, $attributes));
267: return $this->processResponse();
268: }
269:
270: /**
271: * Generic find-by-attributes method
272: */
273: public function modelLookup($modelName) {
274: foreach($this->attributes as $key=>$value){
275: // Exclude null attributes from lookup
276: if(is_null($value) || $value==''){
277: unset($this->attributes[$key]);
278: }
279: }
280: $action = empty($this->attributes['id']) || count($this->attributes) > 1
281: ? "api/lookup/model/$modelName"
282: : "api/view/model/$modelName";
283: $this->responseObject = $this->_send($action,$this->attributes);
284: return $this->processResponse(true);
285: }
286:
287: /**
288: * Creates a contact with attributes specified in the APIModel's attributes property.
289: * @param boolean $leadRouting Boolean whether or not to use lead routing rules for contact assigned to.
290: * @return string Response code from API request.
291: */
292: public function contactCreate($leadRouting = true) {
293: $attributes = array(
294: 'assignedTo' => $this->_user,
295: 'visibility' => '1',
296: );
297: if ($leadRouting) {
298: $attributes['_leadRouting'] = 1;
299: }
300: return $this->modelCreateUpdate('Contacts','create',$attributes);
301: }
302:
303: /**
304: * Updates a contact with the specified attributes.
305: * @param int $id Optional ID of the contact, will be used if the id attribute is not set.
306: * @return string Response code from the API request.
307: */
308: public function contactUpdate($id = null) {
309: if (!isset($this->id))
310: $this->id = $id;
311: $this->modelCreateUpdate('Contacts','update');
312: }
313:
314: /**
315: * Looks up a contact with the attributes set on the model.
316: * @return string Response code from the API request. JSON string of attributes on success.
317: */
318: public function contactLookup() {
319: return $this->modelLookup('Contacts');
320: }
321:
322: /**
323: * Deletes a contact with the specified ID.
324: * @param int $id Optional ID of the contact, will be used if id attribute is not set.
325: * @return string Response code of the API request.
326: */
327: public function contactDelete($id = null) {
328: if (!isset($this->id))
329: $this->id = $id;
330: $this->responseObject = $this->_send('api/delete/model/Contacts', $this->attributes);
331: return $this->processResponse();
332: }
333:
334: /**
335: * Clears the attributes set on the model.
336: */
337: public function clearAttributes() {
338: $this->attributes = array();
339: }
340:
341: /**
342: *
343: * @param type $action
344: * @return type
345: */
346: public function checkAccess($action){
347: $result=$this->_send('api/checkPermissions/action/'.$action.'/username/'.$this->_user.'/api/1',array());
348: return $result=='true';
349: }
350:
351: /**
352: * Creates a new cURL resource handle with user authentication parameters.
353: *
354: * @param type $url
355: * @param type $postData
356: * @param type $curlOpts
357: * @return resource
358: */
359: private function _curlHandle($url,$postData=array(),$curlOpts=array()) {
360: $post = !empty($postData);
361: // Authentication parameters
362: $authOpts = array(
363: 'userKey' => $this->_userKey,
364: 'user' => $this->_user
365: );
366: if(!$post) {
367: // The authentication parameters will need to go into the URL, since
368: // this won't be a POST request.
369: //
370: // if "?" is there already, concatenate with "&". Otherwise, "?"
371: $appendParams = strpos($url,'?') !== false; // use "&" to concatenates
372: $url .= ($appendParams ? '&' : '?').http_build_query($authOpts,'','&');
373: }
374: // Curl handle
375: $ch = curl_init($this->_baseUrl.'/'.$url);
376: // Set default options for the curl resource:
377: curl_setopt_array($ch,array(
378: // Tell CURL to receive response data (and don't return null) even if
379: // the server returned with an error, so that we can have the response
380: // data and get the response code with curl_getinfo:
381: CURLOPT_HTTP200ALIASES => array(400,401,403,404,413,500,501),
382: // Make it a POST request (or not):
383: CURLOPT_POST => $post,
384: // Response capture necessary:
385: CURLOPT_RETURNTRANSFER => 1,
386: ));
387: // Set custom options next so that they override defaults:
388: curl_setopt_array($ch,$curlOpts);
389: if($post) // Set payload data
390: curl_setopt($ch,CURLOPT_POSTFIELDS,$postData = array_merge($postData,$authOpts));
391: return $ch;
392: }
393:
394: /**
395: * Function that sends a post request to the server.
396: *
397: * @param string $url The full request URL including base path and route for create, update etc.
398: * @param mixed $postData Post data to be included with the request.
399: * @return string Response code sent by API controller.
400: */
401: private function _send($url, $postData){
402: $ccSession = $this->_curlHandle($url,$postData);
403: curl_setopt($ccSession, CURLOPT_RETURNTRANSFER, 1);
404: $ccResult = curl_exec($ccSession);
405: $this->_responseCode = curl_getinfo($ccSession,CURLINFO_HTTP_CODE);
406: return $ccResult;
407: }
408:
409: /**
410: * Magic method that handles setting attributes of the model.
411: * @param string $name Attribute name.
412: * @param string $value Attribute value.
413: */
414: public function __set($name, $value) {
415: $setter = 'set'.ucfirst($name);
416: if (strpos($name, '_') === 0 || $name == 'attributes') {
417: // Set the value directly
418: $this->$name = $value;
419: } else if(method_exists($this,$setter)) {
420: // Call the magic setter
421: $this->$setter($value);
422: } else {
423: // Set the named attribute
424: $this->attributes[$name] = $value;
425: }
426: }
427:
428: /**
429: * Magic method that handles getting of an attribute of the model.
430: * @param string $name The name of the attribute.
431: * @return The value of the attribute if set, else null .
432: */
433: public function __get($name) {
434: $getter = 'get'.ucfirst($name);
435: if (strpos($name, '_') === 0 || $name == 'attributes') {
436: // Return the named property
437: return $this->$name;
438: } else if (method_exists($this,$getter)) {
439: // Return whatever the magic getter returns
440: return $this->$getter();
441: } else if (isset($this->attributes[$name])) {
442: // return the named attribute
443: return $this->attributes[$name];
444: }
445: return null;
446: }
447:
448: /**
449: * Magic method to check if an attribute is set.
450: * @param type $name Name of the attribute
451: * @return boolean Whether or not the attribute is set.
452: */
453: public function __isset($name) {
454: if (strpos($name, '_') === 0 || $name == 'attributes') {
455: return isset($this->$name);
456: } else {
457: return isset($this->attributes[$name]);
458: }
459: }
460:
461: }
462:
463: ?>
464: