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);
                                }
                                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;
                                                }
                                                $group_idx = $i;
                                        } else { // Not all strings in a group found insidee of data, error
                                                if ($group_idx == $i) {
                                                        return -1;
                                                }
                                        }
                                }
                                
                        }
                        return $group_idx;
                }
                
                
                /*
                 * 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]);
                        
                        // create the response, add the msg in parentheses if
                        // it was supplied
                        $error_msg = $http[$code];
                        if (!empty($msg)) {
                                $error_msg .= ' ('.$msg.')';
                        }
                    return
                        array(
                            'code' => $code,
                            'error' => $error_msg,
                        );
                }
        
    }

?>
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	foreach($group as $elem) {
155	if (isset($data[$elem]) && !empty($data[$elem])) {
156	if ($group_idx != -1 && $group_idx != $i) { // The keys from disjoint groups found in data
157	return -1;
158	}
159	$group_idx = $i;
160	} else { // Not all strings in a group found insidee of data, error
161	if ($group_idx == $i) {
162	return -1;
163	}
164	}
165	}
166
167	}
168	return $group_idx;
169	}
170
171
172	/*
173	* Sends the return http status code.
174	* @param string\|int $code The code to send
175	* @param string $msg The additional error message that can be added
176	* to the return ff it is not empty. It is added in parentheses.
177	*/
178	protected function sendHttpCode($code, $msg = '') {
179	return $this->HTTPSTATUS($code, $msg);
180	}
181
182
183	/*
184	* Called when the GET http method is used. If not overloaded,
185	* it is the default functionality, i.e. GET unsupported.
186	* Note: the parameter MUST be called request_data due
187	* to the way RESTLER framework does the JSON to parameter
188	* mapping.
189	* @param mixed $request_data The request data, and MUST have
190	* that name.
191	* @return mixed The array containing the response.
192	*/
193	protected function post($request_data) {
194	return $this->sendHttpCode(400, 'Unsupported.');
195	}
196
197
198	/*
199	* Called when the GET http method is used. If not overloaded,
200	* it is the default functionality, i.e. GET unsupported.
201	* @param string $id The identifier of a dossier
202	* @return mixed The array containing the response.
203	*/
204	protected function get($id) {
205	return $this->sendHttpCode(400, 'Unsupported.');
206	}
207
208
209	/*
210	* Called when the PUT http method is used. If not overloaded,
211	* it is the default functionality, i.e. PUT unsupported.
212	* @param mixed $request_data The request data, and MUST have
213	* that name.
214	* @param string $id The identifier of a dossier
215	* @return mixed The array containing the response.
216	*/
217	protected function put($request_data, $id) {
218	return $this->sendHttpCode(400, 'Unsupported.');
219	}
220
221
222	/*
223	* Called when the DELETE http method is used. If not overloaded,
224	* it is the default functionality, i.e. DELETE unsupported.
225	* @param string $id The identifier of a dossier
226	* @return mixed The array containing the response.
227	*/
228
229	protected function delete($id) {
230	return $this->sendHttpCode(400, 'Unsupported.');
231	}
232
233
234	/*
235	* Returns the response to a REST request as an array.
236	* @param int\|string $num The code to send in the response.
237	* @param string msg The additional string to send together
238	* with the error code. If present it is added to the
239	* return inside parentheses.
240	* @return mixed The array containing the response.
241	*/
242	private function HTTPStatus($num, $msg) {
243	$code = $num;
244	if ( !is_numeric($num) ) {
245	$code = intval($num);
246	}
247	$http_protocol = "HTTP/1.0";
248	if(isset($_SERVER['SERVER_PROTOCOL']) && stripos($_SERVER['SERVER_PROTOCOL'],"HTTP") >= 0){
249	$http_protocol = $_SERVER['SERVER_PROTOCOL'];
250	}
251	$http = array(
252	200 => ' 200 OK',
253	201 => ' 201 Created',
254	204 => ' 204 No Content',
255	400 => ' 400 Bad Request',
256	401 => ' 401 Unauthorized',
257	403 => ' 403 Forbidden',
258	404 => ' 404 Not Found',
259	409 => ' 409 Conflict',
260	500 => ' 500 Internal Server Error',
261	);
262
263	// set the header info
264	header($http[$code]);
265
266	// create the response, add the msg in parentheses if
267	// it was supplied
268	$error_msg = $http[$code];
269	if (!empty($msg)) {
270	$error_msg .= ' ('.$msg.')';
271	}
272	return
273	array(
274	'code' => $code,
275	'error' => $error_msg,
276	);
277	}
278
279	}
280
281	?>