MDL-64961 REST web service: Fatal error in error handler
[moodle.git] / webservice / rest / locallib.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
18 /**
19  * REST web service implementation classes and methods.
20  *
21  * @package    webservice_rest
22  * @copyright  2009 Jerome Mouneyrac
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  */
26 require_once("$CFG->dirroot/webservice/lib.php");
28 /**
29  * REST service server implementation.
30  *
31  * @package    webservice_rest
32  * @copyright  2009 Petr Skoda (skodak)
33  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
34  */
35 class webservice_rest_server extends webservice_base_server {
37     /** @var string return method ('xml' or 'json') */
38     protected $restformat;
40     /**
41      * Contructor
42      *
43      * @param string $authmethod authentication method of the web service (WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN, ...)
44      * @param string $restformat Format of the return values: 'xml' or 'json'
45      */
46     public function __construct($authmethod) {
47         parent::__construct($authmethod);
48         $this->wsname = 'rest';
49     }
51     /**
52      * This method parses the $_POST and $_GET superglobals and looks for
53      * the following information:
54      *  1/ user authentication - username+password or token (wsusername, wspassword and wstoken parameters)
55      *  2/ function name (wsfunction parameter)
56      *  3/ function parameters (all other parameters except those above)
57      *  4/ text format parameters
58      *  5/ return rest format xml/json
59      */
60     protected function parse_request() {
62         // Retrieve and clean the POST/GET parameters from the parameters specific to the server.
63         parent::set_web_service_call_settings();
65         // Get GET and POST parameters.
66         $methodvariables = array_merge($_GET, $_POST);
68         // Retrieve REST format parameter - 'xml' (default) or 'json'.
69         $restformatisset = isset($methodvariables['moodlewsrestformat'])
70                 && (($methodvariables['moodlewsrestformat'] == 'xml' || $methodvariables['moodlewsrestformat'] == 'json'));
71         $this->restformat = $restformatisset ? $methodvariables['moodlewsrestformat'] : 'xml';
72         unset($methodvariables['moodlewsrestformat']);
74         if ($this->authmethod == WEBSERVICE_AUTHMETHOD_USERNAME) {
75             $this->username = isset($methodvariables['wsusername']) ? $methodvariables['wsusername'] : null;
76             unset($methodvariables['wsusername']);
78             $this->password = isset($methodvariables['wspassword']) ? $methodvariables['wspassword'] : null;
79             unset($methodvariables['wspassword']);
81             $this->functionname = isset($methodvariables['wsfunction']) ? $methodvariables['wsfunction'] : null;
82             unset($methodvariables['wsfunction']);
84             $this->parameters = $methodvariables;
86         } else {
87             $this->token = isset($methodvariables['wstoken']) ? $methodvariables['wstoken'] : null;
88             unset($methodvariables['wstoken']);
90             $this->functionname = isset($methodvariables['wsfunction']) ? $methodvariables['wsfunction'] : null;
91             unset($methodvariables['wsfunction']);
93             $this->parameters = $methodvariables;
94         }
95     }
97     /**
98      * Send the result of function call to the WS client
99      * formatted as XML document.
100      */
101     protected function send_response() {
103         //Check that the returned values are valid
104         try {
105             if ($this->function->returns_desc != null) {
106                 $validatedvalues = external_api::clean_returnvalue($this->function->returns_desc, $this->returns);
107             } else {
108                 $validatedvalues = null;
109             }
110         } catch (Exception $ex) {
111             $exception = $ex;
112         }
114         if (!empty($exception)) {
115             $response =  $this->generate_error($exception);
116         } else {
117             //We can now convert the response to the requested REST format
118             if ($this->restformat == 'json') {
119                 $response = json_encode($validatedvalues);
120             } else {
121                 $response = '<?xml version="1.0" encoding="UTF-8" ?>'."\n";
122                 $response .= '<RESPONSE>'."\n";
123                 $response .= self::xmlize_result($validatedvalues, $this->function->returns_desc);
124                 $response .= '</RESPONSE>'."\n";
125             }
126         }
128         $this->send_headers();
129         echo $response;
130     }
132     /**
133      * Send the error information to the WS client
134      * formatted as XML document.
135      * Note: the exception is never passed as null,
136      *       it only matches the abstract function declaration.
137      * @param exception $ex the exception that we are sending
138      */
139     protected function send_error($ex=null) {
140         $this->send_headers();
141         echo $this->generate_error($ex);
142     }
144     /**
145      * Build the error information matching the REST returned value format (JSON or XML)
146      * @param exception $ex the exception we are converting in the server rest format
147      * @return string the error in the requested REST format
148      */
149     protected function generate_error($ex) {
150         if ($this->restformat == 'json') {
151             $errorobject = new stdClass;
152             $errorobject->exception = get_class($ex);
153             if (isset($ex->errorcode)) {
154                 $errorobject->errorcode = $ex->errorcode;
155             }
156             $errorobject->message = $ex->getMessage();
157             if (debugging() and isset($ex->debuginfo)) {
158                 $errorobject->debuginfo = $ex->debuginfo;
159             }
160             $error = json_encode($errorobject);
161         } else {
162             $error = '<?xml version="1.0" encoding="UTF-8" ?>'."\n";
163             $error .= '<EXCEPTION class="'.get_class($ex).'">'."\n";
164             if (isset($ex->errorcode)) {
165                 $error .= '<ERRORCODE>' . htmlspecialchars($ex->errorcode, ENT_COMPAT, 'UTF-8')
166                         . '</ERRORCODE>' . "\n";
167             }
168             $error .= '<MESSAGE>'.htmlspecialchars($ex->getMessage(), ENT_COMPAT, 'UTF-8').'</MESSAGE>'."\n";
169             if (debugging() and isset($ex->debuginfo)) {
170                 $error .= '<DEBUGINFO>'.htmlspecialchars($ex->debuginfo, ENT_COMPAT, 'UTF-8').'</DEBUGINFO>'."\n";
171             }
172             $error .= '</EXCEPTION>'."\n";
173         }
174         return $error;
175     }
177     /**
178      * Internal implementation - sending of page headers.
179      */
180     protected function send_headers() {
181         if ($this->restformat == 'json') {
182             header('Content-type: application/json');
183         } else {
184             header('Content-Type: application/xml; charset=utf-8');
185             header('Content-Disposition: inline; filename="response.xml"');
186         }
187         header('Cache-Control: private, must-revalidate, pre-check=0, post-check=0, max-age=0');
188         header('Expires: '. gmdate('D, d M Y H:i:s', 0) .' GMT');
189         header('Pragma: no-cache');
190         header('Accept-Ranges: none');
191         // Allow cross-origin requests only for Web Services.
192         // This allow to receive requests done by Web Workers or webapps in different domains.
193         header('Access-Control-Allow-Origin: *');
194     }
196     /**
197      * Internal implementation - recursive function producing XML markup.
198      *
199      * @param mixed $returns the returned values
200      * @param external_description $desc
201      * @return string
202      */
203     protected static function xmlize_result($returns, $desc) {
204         if ($desc === null) {
205             return '';
207         } else if ($desc instanceof external_value) {
208             if (is_bool($returns)) {
209                 // we want 1/0 instead of true/false here
210                 $returns = (int)$returns;
211             }
212             if (is_null($returns)) {
213                 return '<VALUE null="null"/>'."\n";
214             } else {
215                 return '<VALUE>'.htmlspecialchars($returns, ENT_COMPAT, 'UTF-8').'</VALUE>'."\n";
216             }
218         } else if ($desc instanceof external_multiple_structure) {
219             $mult = '<MULTIPLE>'."\n";
220             if (!empty($returns)) {
221                 foreach ($returns as $val) {
222                     $mult .= self::xmlize_result($val, $desc->content);
223                 }
224             }
225             $mult .= '</MULTIPLE>'."\n";
226             return $mult;
228         } else if ($desc instanceof external_single_structure) {
229             $single = '<SINGLE>'."\n";
230             foreach ($desc->keys as $key=>$subdesc) {
231                 $value = isset($returns[$key]) ? $returns[$key] : null;
232                 $single .= '<KEY name="'.$key.'">'.self::xmlize_result($value, $subdesc).'</KEY>'."\n";
233             }
234             $single .= '</SINGLE>'."\n";
235             return $single;
236         }
237     }
241 /**
242  * REST test client class
243  *
244  * @package    webservice_rest
245  * @copyright  2009 Petr Skoda (skodak)
246  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
247  */
248 class webservice_rest_test_client implements webservice_test_client_interface {
249     /**
250      * Execute test client WS request
251      * @param string $serverurl server url (including token parameter or username/password parameters)
252      * @param string $function function name
253      * @param array $params parameters of the called function
254      * @return mixed
255      */
256     public function simpletest($serverurl, $function, $params) {
257         return download_file_content($serverurl.'&wsfunction='.$function, null, $params);
258     }