MDL-30495 HTML5 apps cannot call Webservices functions if a HTTP resource is retrieve...
[moodle.git] / webservice / rest / locallib.php
1 <?php
3 // This file is part of Moodle - http://moodle.org/
4 //
5 // Moodle is free software: you can redistribute it and/or modify
6 // it under the terms of the GNU General Public License as published by
7 // the Free Software Foundation, either version 3 of the License, or
8 // (at your option) any later version.
9 //
10 // Moodle is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 // GNU General Public License for more details.
14 //
15 // You should have received a copy of the GNU General Public License
16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
18 /**
19  * REST web service implementation classes and methods.
20  *
21  * @package   webservice
22  * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
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  * @author Petr Skoda (skodak)
31  */
32 class webservice_rest_server extends webservice_base_server {
34     /** @property string $alt return method (XML / JSON) */
35     protected $restformat;
37     /**
38      * Contructor
39      */
40     public function __construct($authmethod, $restformat = 'xml') {
41         parent::__construct($authmethod);
42         $this->wsname = 'rest';
43         $this->restformat = ($restformat != 'xml' && $restformat != 'json')?'xml':$restformat; //sanity check, we accept only xml or json
44     }
46     /**
47      * This method parses the $_POST and $_GET superglobals and looks for
48      * the following information:
49      *  1/ user authentication - username+password or token (wsusername, wspassword and wstoken parameters)
50      *  2/ function name (wsfunction parameter)
51      *  3/ function parameters (all other parameters except those above)
52      *
53      * @return void
54      */
55     protected function parse_request() {
57         //Get GET and POST paramters
58         $methodvariables = array_merge($_GET,$_POST);
60         if ($this->authmethod == WEBSERVICE_AUTHMETHOD_USERNAME) {
61             $this->username = isset($methodvariables['wsusername']) ? $methodvariables['wsusername'] : null;
62             unset($methodvariables['wsusername']);
64             $this->password = isset($methodvariables['wspassword']) ? $methodvariables['wspassword'] : null;
65             unset($methodvariables['wspassword']);
67             $this->functionname = isset($methodvariables['wsfunction']) ? $methodvariables['wsfunction'] : null;
68             unset($methodvariables['wsfunction']);
70             $this->parameters = $methodvariables;
72         } else {
73             $this->token = isset($methodvariables['wstoken']) ? $methodvariables['wstoken'] : null;
74             unset($methodvariables['wstoken']);
76             $this->functionname = isset($methodvariables['wsfunction']) ? $methodvariables['wsfunction'] : null;
77             unset($methodvariables['wsfunction']);
79             $this->parameters = $methodvariables;
80         }
81     }
83     /**
84      * Send the result of function call to the WS client
85      * formatted as XML document.
86      * @return void
87      */
88     protected function send_response() {
90         //Check that the returned values are valid
91         try {
92             if ($this->function->returns_desc != null) {
93                 $validatedvalues = external_api::clean_returnvalue($this->function->returns_desc, $this->returns);
94             } else {
95                 $validatedvalues = null;
96             }
97         } catch (Exception $ex) {
98             $exception = $ex;
99         }
101         if (!empty($exception)) {
102             $response =  $this->generate_error($exception);
103         } else {
104             //We can now convert the response to the requested REST format
105             if ($this->restformat == 'json') {
106                 $response = json_encode($validatedvalues);
107             } else {
108                 $response = '<?xml version="1.0" encoding="UTF-8" ?>'."\n";
109                 $response .= '<RESPONSE>'."\n";
110                 $response .= self::xmlize_result($this->returns, $this->function->returns_desc);
111                 $response .= '</RESPONSE>'."\n";
112             }
113         }
115         $this->send_headers();
116         echo $response;
117     }
119     /**
120      * Send the error information to the WS client
121      * formatted as XML document.
122      * Note: the exception is never passed as null,
123      *       it only matches the abstract function declaration.
124      * @param exception $ex
125      * @return void
126      */
127     protected function send_error($ex=null) {
128         $this->send_headers();
129         echo $this->generate_error($ex);
130     }
132     /**
133      * Build the error information matching the REST returned value format (JSON or XML)
134      * @param exception $ex
135      * @return string the error in the requested REST format
136      */
137     protected function generate_error($ex) {
138         if ($this->restformat == 'json') {
139             $errorobject = new stdClass;
140             $errorobject->exception = get_class($ex);
141             $errorobject->message = $ex->getMessage();
142             if (debugging() and isset($ex->debuginfo)) {
143                 $errorobject->debuginfo = $ex->debuginfo;
144             }
145             $error = json_encode($errorobject);
146         } else {
147             $error = '<?xml version="1.0" encoding="UTF-8" ?>'."\n";
148             $error .= '<EXCEPTION class="'.get_class($ex).'">'."\n";
149             $error .= '<MESSAGE>'.htmlspecialchars($ex->getMessage(), ENT_COMPAT, 'UTF-8').'</MESSAGE>'."\n";
150             if (debugging() and isset($ex->debuginfo)) {
151                 $error .= '<DEBUGINFO>'.htmlspecialchars($ex->debuginfo, ENT_COMPAT, 'UTF-8').'</DEBUGINFO>'."\n";
152             }
153             $error .= '</EXCEPTION>'."\n";
154         }
155         return $error;
156     }
158     /**
159      * Internal implementation - sending of page headers.
160      * @return void
161      */
162     protected function send_headers() {
163         if ($this->restformat == 'json') {
164             header('Content-type: application/json');
165         } else {
166             header('Content-Type: application/xml; charset=utf-8');
167             header('Content-Disposition: inline; filename="response.xml"');
168         }
169         header('Cache-Control: private, must-revalidate, pre-check=0, post-check=0, max-age=0');
170         header('Expires: '. gmdate('D, d M Y H:i:s', 0) .' GMT');
171         header('Pragma: no-cache');
172         header('Accept-Ranges: none');
173     }
175     /**
176      * Internal implementation - recursive function producing XML markup.
177      * @param mixed $returns
178      * @param $desc
179      * @return unknown_type
180      */
181     protected static function xmlize_result($returns, $desc) {
182         if ($desc === null) {
183             return '';
185         } else if ($desc instanceof external_value) {
186             if (is_bool($returns)) {
187                 // we want 1/0 instead of true/false here
188                 $returns = (int)$returns;
189             }
190             if (is_null($returns)) {
191                 return '<VALUE null="null"/>'."\n";
192             } else {
193                 return '<VALUE>'.htmlspecialchars($returns, ENT_COMPAT, 'UTF-8').'</VALUE>'."\n";
194             }
196         } else if ($desc instanceof external_multiple_structure) {
197             $mult = '<MULTIPLE>'."\n";
198             if (!empty($returns)) {
199                 foreach ($returns as $val) {
200                     $mult .= self::xmlize_result($val, $desc->content);
201                 }
202             }
203             $mult .= '</MULTIPLE>'."\n";
204             return $mult;
206         } else if ($desc instanceof external_single_structure) {
207             $single = '<SINGLE>'."\n";
208             foreach ($desc->keys as $key=>$subdesc) {
209                 $single .= '<KEY name="'.$key.'">'.self::xmlize_result($returns[$key], $subdesc).'</KEY>'."\n";
210             }
211             $single .= '</SINGLE>'."\n";
212             return $single;
213         }
214     }
218 /**
219  * REST test client class
220  */
221 class webservice_rest_test_client implements webservice_test_client_interface {
222     /**
223      * Execute test client WS request
224      * @param string $serverurl
225      * @param string $function
226      * @param array $params
227      * @return mixed
228      */
229     public function simpletest($serverurl, $function, $params) {
230         return download_file_content($serverurl.'&wsfunction='.$function, null, $params);
231     }