Proyectos de Subversion Moodle

<?php

// This file is part of Moodle - http://moodle.org/

//

// Moodle is free software: you can redistribute it and/or modify

// it under the terms of the GNU General Public License as published by

// the Free Software Foundation, either version 3 of the License, or

// (at your option) any later version.

//

// Moodle is distributed in the hope that it will be useful,

// but WITHOUT ANY WARRANTY; without even the implied warranty of

// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

// GNU General Public License for more details.

//

// You should have received a copy of the GNU General Public License

// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**

 * REST web service implementation classes and methods.

 *

 * @package    webservice_rest

 * @copyright  2009 Jerome Mouneyrac

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

use core_external\external_multiple_structure;

use core_external\external_single_structure;

use core_external\external_value;

require_once("$CFG->dirroot/webservice/lib.php");

/**

 * REST service server implementation.

 *

 * @package    webservice_rest

 * @copyright  2009 Petr Skoda (skodak)

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

class webservice_rest_server extends webservice_base_server {

    /** @var string return method ('xml' or 'json') */

    protected $restformat;

    /**

     * Contructor

     *

     * @param string $authmethod authentication method of the web service (WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN, ...)

     * @param string $restformat Format of the return values: 'xml' or 'json'

     */

    public function __construct($authmethod) {

        parent::__construct($authmethod);

        $this->wsname = 'rest';

    }

    /**

     * Set the request format to.

     */

    public function set_rest_format(): void {

        // Get GET and POST parameters.

        $methodvariables = array_merge($_GET, $_POST);

        // Retrieve REST format parameter - 'xml' (default) or 'json'.

        $restformatisset = isset($methodvariables['moodlewsrestformat'])

                && (($methodvariables['moodlewsrestformat'] == 'xml' || $methodvariables['moodlewsrestformat'] == 'json'));

        $this->restformat = $restformatisset ? $methodvariables['moodlewsrestformat'] : 'xml';

    }

    /**

     * This method parses the $_POST and $_GET superglobals and looks for

     * the following information:

     *  1/ user authentication - username+password or token (wsusername, wspassword and wstoken parameters)

     *  2/ function name (wsfunction parameter)

     *  3/ function parameters (all other parameters except those above)

     *  4/ text format parameters

     *  5/ return rest format xml/json

     */

    protected function parse_request() {

        // Retrieve and clean the POST/GET parameters from the parameters specific to the server.

        parent::set_web_service_call_settings();

        // Get GET and POST parameters.

        $methodvariables = array_merge($_GET, $_POST);

        $this->set_rest_format();

        unset($methodvariables['moodlewsrestformat']);

        if ($this->authmethod == WEBSERVICE_AUTHMETHOD_USERNAME) {

            $this->username = isset($methodvariables['wsusername']) ? $methodvariables['wsusername'] : null;

            unset($methodvariables['wsusername']);

            $this->password = isset($methodvariables['wspassword']) ? $methodvariables['wspassword'] : null;

            unset($methodvariables['wspassword']);

            $this->functionname = isset($methodvariables['wsfunction']) ? $methodvariables['wsfunction'] : null;

            unset($methodvariables['wsfunction']);

            $this->parameters = $methodvariables;

        } else {

            $this->token = isset($methodvariables['wstoken']) ? $methodvariables['wstoken'] : null;

            unset($methodvariables['wstoken']);

            $this->functionname = isset($methodvariables['wsfunction']) ? $methodvariables['wsfunction'] : null;

            unset($methodvariables['wsfunction']);

            $this->parameters = $methodvariables;

        }

    }

    /**

     * Send the result of function call to the WS client

     * formatted as XML document.

     */

    protected function send_response() {

        //Check that the returned values are valid

        try {

            if ($this->function->returns_desc != null) {

                $validatedvalues = \core_external\external_api::clean_returnvalue(

                    $this->function->returns_desc,

                    $this->returns

                );

            } else {

                $validatedvalues = null;

            }

        } catch (Exception $ex) {

            $exception = $ex;

        }

        if (!empty($exception)) {

            $response =  $this->generate_error($exception);

        } else {

            //We can now convert the response to the requested REST format

            if ($this->restformat == 'json') {

                $response = json_encode($validatedvalues);

            } else {

                $response = '<?xml version="1.0" encoding="UTF-8" ?>'."\n";

                $response .= '<RESPONSE>'."\n";

                $response .= self::xmlize_result($validatedvalues, $this->function->returns_desc);

                $response .= '</RESPONSE>'."\n";

            }

        }

        $this->send_headers();

        echo $response;

    }

    /**

     * Send the error information to the WS client

     * formatted as XML document.

     * Note: the exception is never passed as null,

     *       it only matches the abstract function declaration.

     * @param exception $ex the exception that we are sending

     */

    protected function send_error($ex=null) {

        // Unless debugging is completely off, log the error to server error log.

        if (debugging('', DEBUG_MINIMAL)) {

            $info = get_exception_info($ex);

            // This format is the same as default_exception_handler() in setuplib.php but with the

            // word 'REST' instead of 'Default', to make it easy to reuse any existing processing.

            error_log('REST exception handler: ' . $info->message . ' Debug: ' .

                    $info->debuginfo . "\n" . format_backtrace($info->backtrace, true));

        }

        $this->send_headers();

        echo $this->generate_error($ex);

    }

    /**

     * Build the error information matching the REST returned value format (JSON or XML)

     * @param exception $ex the exception we are converting in the server rest format

     * @return string the error in the requested REST format

     */

    protected function generate_error($ex) {

        if ($this->restformat == 'json') {

            $errorobject = new stdClass;

            $errorobject->exception = get_class($ex);

            if (isset($ex->errorcode)) {

                $errorobject->errorcode = $ex->errorcode;

            }

            $errorobject->message = $ex->getMessage();

            if (debugging() and isset($ex->debuginfo)) {

                $errorobject->debuginfo = $ex->debuginfo;

            }

            $error = json_encode($errorobject);

        } else {

            $error = '<?xml version="1.0" encoding="UTF-8" ?>'."\n";

            $error .= '<EXCEPTION class="'.get_class($ex).'">'."\n";

            if (isset($ex->errorcode)) {

                $error .= '<ERRORCODE>' . htmlspecialchars($ex->errorcode, ENT_COMPAT, 'UTF-8')

                        . '</ERRORCODE>' . "\n";

            }

            $error .= '<MESSAGE>'.htmlspecialchars($ex->getMessage(), ENT_COMPAT, 'UTF-8').'</MESSAGE>'."\n";

            if (debugging() and isset($ex->debuginfo)) {

                $error .= '<DEBUGINFO>'.htmlspecialchars($ex->debuginfo, ENT_COMPAT, 'UTF-8').'</DEBUGINFO>'."\n";

            }

            $error .= '</EXCEPTION>'."\n";

        }

        return $error;

    }

    /**

     * Internal implementation - sending of page headers.

     */

    protected function send_headers() {

        if ($this->restformat == 'json') {

            header('Content-type: application/json');

        } else {

            header('Content-Type: application/xml; charset=utf-8');

            header('Content-Disposition: inline; filename="response.xml"');

        }

        header('Cache-Control: private, must-revalidate, pre-check=0, post-check=0, max-age=0');

        header('Expires: '. gmdate('D, d M Y H:i:s', 0) .' GMT');

        header('Pragma: no-cache');

        header('Accept-Ranges: none');

        // Allow cross-origin requests only for Web Services.

        // This allow to receive requests done by Web Workers or webapps in different domains.

        header('Access-Control-Allow-Origin: *');

    }

    /**

     * Internal implementation - recursive function producing XML markup.

     *

     * @param mixed $returns the returned values

     * @param external_description $desc

     * @return string

     */

    protected static function xmlize_result($returns, $desc) {

        if ($desc === null) {

            return '';

        } else if ($desc instanceof external_value) {

            if (is_bool($returns)) {

                // we want 1/0 instead of true/false here

                $returns = (int)$returns;

            }

            if (is_null($returns)) {

                return '<VALUE null="null"/>'."\n";

            } else {

                return '<VALUE>'.htmlspecialchars($returns, ENT_COMPAT, 'UTF-8').'</VALUE>'."\n";

            }

        } else if ($desc instanceof external_multiple_structure) {

            $mult = '<MULTIPLE>'."\n";

            if (!empty($returns)) {

                foreach ($returns as $val) {

                    $mult .= self::xmlize_result($val, $desc->content);

                }

            }

            $mult .= '</MULTIPLE>'."\n";

            return $mult;

        } else if ($desc instanceof external_single_structure) {

            $single = '<SINGLE>'."\n";

            foreach ($desc->keys as $key=>$subdesc) {

                $value = isset($returns[$key]) ? $returns[$key] : null;

                $single .= '<KEY name="'.$key.'">'.self::xmlize_result($value, $subdesc).'</KEY>'."\n";

            }

            $single .= '</SINGLE>'."\n";

            return $single;

        }

    }

}

/**

 * REST test client class

 *

 * @package    webservice_rest

 * @copyright  2009 Petr Skoda (skodak)

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

class webservice_rest_test_client implements webservice_test_client_interface {

    /**

     * Execute test client WS request

     * @param string $serverurl server url (including token parameter or username/password parameters)

     * @param string $function function name

     * @param array $params parameters of the called function

     * @return mixed

     */

    public function simpletest($serverurl, $function, $params) {

        return download_file_content($serverurl.'&wsfunction='.$function, null, $params);

    }

}