services/REST/services.php

<?php

/*
 * The base class for all of the services provided through the REST interface.
 * 
 * It creates an instance of utils which establish DB connection. It also
 * contains methods for checking the correctness of the format of the
 * incomming messages.
 * It contains the methods post, put, get, delete that exhibit upon a REST
 * call the default behaviour - "request can't be processed since the service
 * is not available.
 *
 * 
 * @author: Mirna Limic <[email protected]>
 * @uses ./restler The RESTLER framework. When using PUT and POST http methods
 * the function receiving the incomming data MUST contain a parameter called
 * request_data. The RESTLER framework stores the incoming JSON string converted
 * into an array in the request_data parameter.
 * 
 * Date: 15/10/2012
 * Follow-up:
 * Bugs: Unknown
 *
 */

    class Services {
                
                
                /*
                 * Constructor
                 *
                 * Initializes the contents attribute to an empty array, the
                 * mdtry_groups attribute to null, and the metier_manager attribute
                 * to null.
                 */
        protected function __construct() {
                        /* constant 'REST_REQUEST' indicates that the processing was
                         * initiated via a REST request. It is used inside of om_dbform
                         * class to avoid premature ending of script execution due to
                         * a die() issued by a DB error or another source.
                         */
                        if (!defined('REST_REQUEST')) {
                                define('REST_REQUEST', true);
                        }
                        /* contents is populated by derived classes. The contents array
                         * contains the parts of the message received via a REST request in
                         * JSON format. It is an associative array. It is used in verifying
                         * the completeness of the format of the request (see functions
                         * requestValid and dataComplete).
                         */
            $this->contents = array();
                        /* metier_manager points to one of the xxxManager classes that do
                         * the processing of the data. It should be instatiated by one of
                         * the derived classes.
                         */
                        $this->metier_manager = null;
                        /* mdtry_grps is used in checking the completeness (validity) of
                         * a request's format. It can be a 2D array, or a 1D array or a mix.
                         * Each element of mdtry_groups, called a group, is treated as an
                         * array. All strings found in a group have to be present in the
                         * received JSON data. No two strings coming from different groups
                         * can be found in the JSON data. I.e. the groups are disjoint.
                         * mdtry_grps are to be populated by a derived class.
                         */
                        $this->mdtry_grps = null;
        }
                
                
                /*
                 * Destructor
                 *
                 * Destroys the xxxManager instance.
                 */
        protected function __destruct() {
                        if ($this->metier_manager) {
                                unset($this->metier_manager);
                        }
        }

                
                /*
                 * Verifies that $this->contents contains non-empty data.
                 * @param mixed $optional An array of strings for which $this->contents
                 * is allowed to have an empty value
                 * @return bool returns true if contents has no disallowed empty values,
                 * false otherwise.
                 */
                private function dataComplete($optional = null) {
                        foreach ($this->contents as $key => $value) {
                                if (empty($value)) {
                                        // check if the key is optional
                                        if ($optional && in_array($key, $optional)) {
                                                continue;
                                        }
                                        return false;
                                }
                        }
                        return true;
                }


                /*
                 * Verifies if the format of the JSON data received via REST
                 * is valid.
                 * @param mixed $data the array containing the data received via REST
                 * @param mixed $optional An array of strings for which $this->contents
                 * is allowed to have an empty value
                 * @return bool returns true if contents has no disallowed empty values,
                 * false otherwise.
                 */
                protected function requestValid($data, $optional = null) {
                        if (count($data) == 0) {
                            return false;
                        }
                        // populate the contents array, where data could be coming from
                        // a REST request, for example
                        foreach (array_keys($this->contents) as $elem) {
                            if (isset($data[$elem])) {
                                $this->contents[$elem] = $data[$elem];
                            }     
                        }
                        // check all data is present, unless it's presence is optional
                        return $this->dataComplete($optional);
            }

                
                /*
                 * Return the index of the mandatory group into which the request belongs.
                 * 
                 * Returns the index of the group that corresponds to the format
                 * of the JSON data received via REST interface.
                 * All strings found in a mandatory group have to be present
                 * in the received JSON data. No two strings coming from
                 * different groups can be found in the JSON data. I.e. the
                 * groups are disjoint.
                 * Mandatory groups are useful when one http method (PUT, ...) can be
                 * used to process several different requests.
                 * @param mixed $data the array containing the data received via REST
                 * @return int index of the group starting with index 0 or -1 if no
                 * group could be found, or conflicting data found.
                 */
                protected function requestMdtrGroup(&$data) {
                        // case of mandatory groups, i.e. multiple requests possible to the same source
                        if (!$this->mdtry_grps) {
                                return -1;
                        }
                        $lengroups = count($this->mdtry_grps);
                        $group_idx = -1;
                        for ($i = 0; $i < $lengroups; $i++) {
                                $group = $this->mdtry_grps[$i];
                                if (!is_array($group)) {
                                        $group = array($group);
                                }
                                // position of the element, $elem, of a $group that is currently being considered
                                $pos = 0;
                                foreach($group as $elem) {
                                        if (isset($data[$elem]) && !empty($data[$elem])) {
                                                if ($group_idx != -1 && $group_idx != $i) { // The keys from disjoint groups found in data
                                                        return -1;
                                                }
                                                if ($group_idx < 0 && $pos > 0) {
                                                        // not all keys in a group found inside data
                                                        return -1;
                                                }
                                                $group_idx = $i;
                                        } else { // Not all strings in a group found insidee of data, error
                                                if ($group_idx == $i) {
                                                        return -1;
                                                }
                                        }
                                        $pos++;
                                }
                                
                        }
                        return $group_idx;
                }
                
                
                /*
                 * Send a reply depending on the result of processing of a request.
                 *
                 * @param string $result The result of the processing.
                 * @param string $KO_msg String containing the error that dappened
                 * during the processing of valid request data.
                 */
                protected function sendReply($result, $KO_msg = null, $OK_msg = null) {
                        // if there were any errors, return an error code
                        if ($result != 'OK') {
                                // if there was a problem with the data itself, send the error info
                                if ($result != 'KO') {
                                        return $this->sendHttpCode(400, $result);
                                }
                                // problem in processing the data
                                return $this->sendHttpCode(500, $KO_msg);
                        }
                        
                        return $this->sendHttpCode(200, $OK_msg);
                }
                
                
                /*
                 * Sends the return http status code.
                 * @param string|int $code The code to send
                 * @param string $msg The additional error message that can be added
                 * to the return ff it is not empty. It is added in parentheses.
                 */
                protected function sendHttpCode($code, $msg = '') {
                        return $this->HTTPSTATUS($code, $msg);
                }
                
                
                /*
                 * Called when the GET http method is used. If not overloaded,
                 * it is the default functionality, i.e. GET unsupported.
                 * Note: the parameter MUST be called *request_data* due
                 * to the way RESTLER framework does the JSON to parameter
                 * mapping.
                 * @param mixed $request_data The request data, and MUST have
                 * that name.
                 * @return mixed The array containing the response.
                 */
        protected function post($request_data) {
            return $this->sendHttpCode(400, 'Unsupported.');
        }
                

                /*
                 * Called when the GET http method is used. If not overloaded,
                 * it is the default functionality, i.e. GET unsupported.
                 * @param string $id The identifier of a dossier
                 * @return mixed The array containing the response.
                 */
        protected function get($id) {
                        return $this->sendHttpCode(400, 'Unsupported.');
        }

                
                /*
                 * Called when the PUT http method is used. If not overloaded,
                 * it is the default functionality, i.e. PUT unsupported.
                 * @param mixed $request_data The request data, and MUST have
                 * that name.
                 * @param string $id The identifier of a dossier
                 * @return mixed The array containing the response.
                 */             
        protected function put($request_data, $id) {
            return $this->sendHttpCode(400, 'Unsupported.');
        }

                
                /*
                 * Called when the DELETE http method is used. If not overloaded,
                 * it is the default functionality, i.e. DELETE unsupported.
                 * @param string $id The identifier of a dossier
                 * @return mixed The array containing the response.
                 */

        protected function delete($id) {
            return $this->sendHttpCode(400, 'Unsupported.');
        }  


                /*
                 * Returns the response to a REST request as an array.
                 * @param int|string $num The code to send in the response.
                 * @param string msg The additional string to send together
                 * with the error code. If present it is added to the
                 * return inside parentheses.
                 * @return mixed The array containing the response.
                 */
                private function HTTPStatus($num, $msg) {
                    $code = $num;
                    if ( !is_numeric($num) ) {
                        $code = intval($num);
                    }
                    $http_protocol = "HTTP/1.0"; 
                    if(isset($_SERVER['SERVER_PROTOCOL']) && stripos($_SERVER['SERVER_PROTOCOL'],"HTTP") >= 0){
                        $http_protocol = $_SERVER['SERVER_PROTOCOL']; 
                    }
                    $http = array(
                        200 => ' 200 OK',
                        201 => ' 201 Created',
                        204 => ' 204 No Content',
                        400 => ' 400 Bad Request',
                        401 => ' 401 Unauthorized',
                        403 => ' 403 Forbidden',
                        404 => ' 404 Not Found',
                        409 => ' 409 Conflict',
                        500 => ' 500 Internal Server Error',
                    );
                        
                        // set the header info
                        //header($http[$code]);
                        header($http_protocol . " ". $http[$code]);
                        
                        // create the response, add the msg in parentheses if
                        // it was supplied
                        //$error_msg = $http[$code];
                        $error_msg = null;
                        if ($msg && !empty($msg)) {
                                //$error_msg .= ' ('.$msg.')';
                                $error_msg = $msg;
                        }
                        //print '  $error_msg:'.$error_msg."\r\n";
                        if ($error_msg) {
                                return array(
                            //'code' => $code,
                            //'error' => $error_msg,
                                        $error_msg
                                );
                        }
                        return null;
                }
        
    }

?>
1	<?php
2
3	/*
4	* The base class for all of the services provided through the REST interface.
5	*
6	* It creates an instance of utils which establish DB connection. It also
7	* contains methods for checking the correctness of the format of the
8	* incomming messages.
9	* It contains the methods post, put, get, delete that exhibit upon a REST
10	* call the default behaviour - "request can't be processed since the service
11	* is not available.
12	*
13	*
14	* @author: Mirna Limic <[email protected]>
15	* @uses ./restler The RESTLER framework. When using PUT and POST http methods
16	* the function receiving the incomming data MUST contain a parameter called
17	* request_data. The RESTLER framework stores the incoming JSON string converted
18	* into an array in the request_data parameter.
19	*
20	* Date: 15/10/2012
21	* Follow-up:
22	* Bugs: Unknown
23	*
24	*/
25
26	class Services {
27
28
29	/*
30	* Constructor
31	*
32	* Initializes the contents attribute to an empty array, the
33	* mdtry_groups attribute to null, and the metier_manager attribute
34	* to null.
35	*/
36	protected function __construct() {
37	/* constant 'REST_REQUEST' indicates that the processing was
38	* initiated via a REST request. It is used inside of om_dbform
39	* class to avoid premature ending of script execution due to
40	* a die() issued by a DB error or another source.
41	*/
42	if (!defined('REST_REQUEST')) {
43	define('REST_REQUEST', true);
44	}
45	/* contents is populated by derived classes. The contents array
46	* contains the parts of the message received via a REST request in
47	* JSON format. It is an associative array. It is used in verifying
48	* the completeness of the format of the request (see functions
49	* requestValid and dataComplete).
50	*/
51	$this->contents = array();
52	/* metier_manager points to one of the xxxManager classes that do
53	* the processing of the data. It should be instatiated by one of
54	* the derived classes.
55	*/
56	$this->metier_manager = null;
57	/* mdtry_grps is used in checking the completeness (validity) of
58	* a request's format. It can be a 2D array, or a 1D array or a mix.
59	* Each element of mdtry_groups, called a group, is treated as an
60	* array. All strings found in a group have to be present in the
61	* received JSON data. No two strings coming from different groups
62	* can be found in the JSON data. I.e. the groups are disjoint.
63	* mdtry_grps are to be populated by a derived class.
64	*/
65	$this->mdtry_grps = null;
66	}
67
68
69	/*
70	* Destructor
71	*
72	* Destroys the xxxManager instance.
73	*/
74	protected function __destruct() {
75	if ($this->metier_manager) {
76	unset($this->metier_manager);
77	}
78	}
79
80
81	/*
82	* Verifies that $this->contents contains non-empty data.
83	* @param mixed $optional An array of strings for which $this->contents
84	* is allowed to have an empty value
85	* @return bool returns true if contents has no disallowed empty values,
86	* false otherwise.
87	*/
88	private function dataComplete($optional = null) {
89	foreach ($this->contents as $key => $value) {
90	if (empty($value)) {
91	// check if the key is optional
92	if ($optional && in_array($key, $optional)) {
93	continue;
94	}
95	return false;
96	}
97	}
98	return true;
99	}
100
101
102	/*
103	* Verifies if the format of the JSON data received via REST
104	* is valid.
105	* @param mixed $data the array containing the data received via REST
106	* @param mixed $optional An array of strings for which $this->contents
107	* is allowed to have an empty value
108	* @return bool returns true if contents has no disallowed empty values,
109	* false otherwise.
110	*/
111	protected function requestValid($data, $optional = null) {
112	if (count($data) == 0) {
113	return false;
114	}
115	// populate the contents array, where data could be coming from
116	// a REST request, for example
117	foreach (array_keys($this->contents) as $elem) {
118	if (isset($data[$elem])) {
119	$this->contents[$elem] = $data[$elem];
120	}
121	}
122	// check all data is present, unless it's presence is optional
123	return $this->dataComplete($optional);
124	}
125
126
127	/*
128	* Return the index of the mandatory group into which the request belongs.
129	*
130	* Returns the index of the group that corresponds to the format
131	* of the JSON data received via REST interface.
132	* All strings found in a mandatory group have to be present
133	* in the received JSON data. No two strings coming from
134	* different groups can be found in the JSON data. I.e. the
135	* groups are disjoint.
136	* Mandatory groups are useful when one http method (PUT, ...) can be
137	* used to process several different requests.
138	* @param mixed $data the array containing the data received via REST
139	* @return int index of the group starting with index 0 or -1 if no
140	* group could be found, or conflicting data found.
141	*/
142	protected function requestMdtrGroup(&$data) {
143	// case of mandatory groups, i.e. multiple requests possible to the same source
144	if (!$this->mdtry_grps) {
145	return -1;
146	}
147	$lengroups = count($this->mdtry_grps);
148	$group_idx = -1;
149	for ($i = 0; $i < $lengroups; $i++) {
150	$group = $this->mdtry_grps[$i];
151	if (!is_array($group)) {
152	$group = array($group);
153	}
154	// position of the element, $elem, of a $group that is currently being considered
155	$pos = 0;
156	foreach($group as $elem) {
157	if (isset($data[$elem]) && !empty($data[$elem])) {
158	if ($group_idx != -1 && $group_idx != $i) { // The keys from disjoint groups found in data
159	return -1;
160	}
161	if ($group_idx < 0 && $pos > 0) {
162	// not all keys in a group found inside data
163	return -1;
164	}
165	$group_idx = $i;
166	} else { // Not all strings in a group found insidee of data, error
167	if ($group_idx == $i) {
168	return -1;
169	}
170	}
171	$pos++;
172	}
173
174	}
175	return $group_idx;
176	}
177
178
179	/*
180	* Send a reply depending on the result of processing of a request.
181	*
182	* @param string $result The result of the processing.
183	* @param string $KO_msg String containing the error that dappened
184	* during the processing of valid request data.
185	*/
186	protected function sendReply($result, $KO_msg = null, $OK_msg = null) {
187	// if there were any errors, return an error code
188	if ($result != 'OK') {
189	// if there was a problem with the data itself, send the error info
190	if ($result != 'KO') {
191	return $this->sendHttpCode(400, $result);
192	}
193	// problem in processing the data
194	return $this->sendHttpCode(500, $KO_msg);
195	}
196
197	return $this->sendHttpCode(200, $OK_msg);
198	}
199
200
201	/*
202	* Sends the return http status code.
203	* @param string\|int $code The code to send
204	* @param string $msg The additional error message that can be added
205	* to the return ff it is not empty. It is added in parentheses.
206	*/
207	protected function sendHttpCode($code, $msg = '') {
208	return $this->HTTPSTATUS($code, $msg);
209	}
210
211
212	/*
213	* Called when the GET http method is used. If not overloaded,
214	* it is the default functionality, i.e. GET unsupported.
215	* Note: the parameter MUST be called request_data due
216	* to the way RESTLER framework does the JSON to parameter
217	* mapping.
218	* @param mixed $request_data The request data, and MUST have
219	* that name.
220	* @return mixed The array containing the response.
221	*/
222	protected function post($request_data) {
223	return $this->sendHttpCode(400, 'Unsupported.');
224	}
225
226
227	/*
228	* Called when the GET http method is used. If not overloaded,
229	* it is the default functionality, i.e. GET unsupported.
230	* @param string $id The identifier of a dossier
231	* @return mixed The array containing the response.
232	*/
233	protected function get($id) {
234	return $this->sendHttpCode(400, 'Unsupported.');
235	}
236
237
238	/*
239	* Called when the PUT http method is used. If not overloaded,
240	* it is the default functionality, i.e. PUT unsupported.
241	* @param mixed $request_data The request data, and MUST have
242	* that name.
243	* @param string $id The identifier of a dossier
244	* @return mixed The array containing the response.
245	*/
246	protected function put($request_data, $id) {
247	return $this->sendHttpCode(400, 'Unsupported.');
248	}
249
250
251	/*
252	* Called when the DELETE http method is used. If not overloaded,
253	* it is the default functionality, i.e. DELETE unsupported.
254	* @param string $id The identifier of a dossier
255	* @return mixed The array containing the response.
256	*/
257
258	protected function delete($id) {
259	return $this->sendHttpCode(400, 'Unsupported.');
260	}
261
262
263	/*
264	* Returns the response to a REST request as an array.
265	* @param int\|string $num The code to send in the response.
266	* @param string msg The additional string to send together
267	* with the error code. If present it is added to the
268	* return inside parentheses.
269	* @return mixed The array containing the response.
270	*/
271	private function HTTPStatus($num, $msg) {
272	$code = $num;
273	if ( !is_numeric($num) ) {
274	$code = intval($num);
275	}
276	$http_protocol = "HTTP/1.0";
277	if(isset($_SERVER['SERVER_PROTOCOL']) && stripos($_SERVER['SERVER_PROTOCOL'],"HTTP") >= 0){
278	$http_protocol = $_SERVER['SERVER_PROTOCOL'];
279	}
280	$http = array(
281	200 => ' 200 OK',
282	201 => ' 201 Created',
283	204 => ' 204 No Content',
284	400 => ' 400 Bad Request',
285	401 => ' 401 Unauthorized',
286	403 => ' 403 Forbidden',
287	404 => ' 404 Not Found',
288	409 => ' 409 Conflict',
289	500 => ' 500 Internal Server Error',
290	);
291
292	// set the header info
293	//header($http[$code]);
294	header($http_protocol . " ". $http[$code]);
295
296	// create the response, add the msg in parentheses if
297	// it was supplied
298	//$error_msg = $http[$code];
299	$error_msg = null;
300	if ($msg && !empty($msg)) {
301	//$error_msg .= ' ('.$msg.')';
302	$error_msg = $msg;
303	}
304	//print ' $error_msg:'.$error_msg."\r\n";
305	if ($error_msg) {
306	return array(
307	//'code' => $code,
308	//'error' => $error_msg,
309	$error_msg
310	);
311	}
312	return null;
313	}
314
315	}
316
317	?>