MDL-12886 fixed param typo
[moodle.git] / lib / externallib.php
CommitLineData
9a0df45a 1<?php
2
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/>.
17
18/**
19 * Support for external API
20 *
21 * @package moodlecore
22 * @subpackage webservice
551f4420 23 * @copyright 2009 Moodle Pty Ltd (http://moodle.com)
9a0df45a 24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
26
27/**
28 * Exception indicating user is not allowed to use external function in
29 * the current context.
30 */
31class restricted_context_exception extends moodle_exception {
32 /**
33 * Constructor
34 */
35 function __construct() {
36 parent::__construct('restrictedcontextexception', 'error');
37 }
38}
39
40/**
41 * Base class for external api methods.
42 */
43class external_api {
9a0df45a 44 private static $contextrestriction;
45
1bea0c27 46 /**
47 * Set context restriction for all folowing subsequent function calls.
48 * @param stdClass $contex
49 * @return void
50 */
9a0df45a 51 public static function set_context_restriction($contex) {
52 self::$contextrestriction = $context;
53 }
54
1bea0c27 55 /**
c9c5cc81 56 * Validates submitted function parameters, if anything is incorrect
1bea0c27 57 * invalid_parameter_exception is thrown.
1d7db36f 58 * This is a simple recursive method which is intended to be called from
59 * each implementation method of external API.
c9c5cc81 60 * @param external_description $description description of parameters
61 * @param mixed $params the actual parameters
62 * @return mixed params with added defaults for optional items, invalid_parameters_exception thrown if any problem found
1bea0c27 63 */
c9c5cc81 64 public static function validate_parameters(external_description $description, $params) {
65 if ($description instanceof external_param) {
66 if (is_array($params) or is_object($params)) {
67 throw new invalid_parameter_exception('Scalar type expected, array or object received.');
68 }
69 return validate_param($params, $description->type, $description->allownull, 'Invalid external api parameter');
70
71 } else if ($description instanceof external_single_structure) {
72 if (!is_array($params)) {
73 throw new invalid_parameter_exception('Only arrays accepted.');
74 }
75 $result = array();
76 foreach ($description->keys as $key=>$subdesc) {
77 if (!array_key_exists($key, $params)) {
78 if ($subdesc->required) {
79 throw new invalid_parameter_exception('Missing required key in single structure.');
80 }
81 if ($subdesc instanceof external_param) {
82 $result[$key] = self::validate_parameters($subdesc, $subdesc->default);
83 }
84 } else {
85 $result[$key] = self::validate_parameters($subdesc, $params[$key]);
86 }
87 unset($params[$key]);
88 }
89 if (!empty($params)) {
90 throw new invalid_parameter_exception('Unexpected keys detected in parameter array.');
91 }
92 return $result;
1bea0c27 93
c9c5cc81 94 } else if ($description instanceof external_multiple_structure) {
95 if (!is_array($params)) {
96 throw new invalid_parameter_exception('Only arrays accepted.');
97 }
98 $result = array();
99 foreach ($params as $param) {
100 $result[] = self::validate_parameters($description->content, $param);
101 }
102 return $result;
103
104 } else {
105 throw new invalid_parameter_exception('Invalid external api description.');
106 }
1bea0c27 107 }
108
9a0df45a 109 /**
110 * Makes sure user may execute functions in this context.
111 * @param object $context
112 * @return void
113 */
114 protected static function validate_context($context) {
ab9a01f2 115 if (empty($context)) {
116 throw new invalid_parameter_exception('Context does not exist');
117 }
9a0df45a 118 if (empty(self::$contextrestriction)) {
119 self::$contextrestriction = get_context_instance(CONTEXT_SYSTEM);
120 }
121 $rcontext = self::$contextrestriction;
122
123 if ($rcontext->contextlevel == $context->contextlevel) {
124 if ($rcontex->id != $context->id) {
125 throw new restricted_context_exception();
126 }
127 } else if ($rcontext->contextlevel > $context->contextlevel) {
128 throw new restricted_context_exception();
129 } else {
130 $parents = get_parent_contexts($context);
131 if (!in_array($rcontext->id, $parents)) {
132 throw new restricted_context_exception();
133 }
134 }
135
136 if ($context->contextlevel >= CONTEXT_COURSE) {
137 //TODO: temporary bloody hack, this needs to be replaced by
138 // proper enrolment and course visibility check
139 // similar to require_login() (which can not be used
140 // because it can be used only once and redirects)
c9c5cc81 141 // oh - did I say we need to rewrite enrolments in 2.0
9a0df45a 142 // to solve this bloody mess?
143 //
144 // missing: hidden courses and categories, groupmembersonly,
145 // conditional activities, etc.
146 require_capability('moodle/course:view', $context);
147 }
148 }
9a0df45a 149}
150
b038c32c 151/**
152 * Common ancestor of all parameter description classes
153 */
154abstract class external_description {
155 /** @property string $description description of element */
156 public $desc;
157 /** @property bool $required element value required, null not alowed */
158 public $required;
159
160 /**
161 * Contructor
162 * @param string $desc
163 * @param bool $required
164 */
c9c5cc81 165 public function __construct($desc, $required) {
b038c32c 166 $this->desc = $desc;
167 $this->required = $required;
168 }
169}
170
171/**
172 * Scalar parameter description class
173 */
174class external_param extends external_description {
175 /** @property mixed $type parameter type PARAM_XX */
176 public $type;
177 /** @property mixed $default default value */
178 public $default;
179 /** @property bool $allownull allow null values */
180 public $allownull;
181
182 /**
183 * Constructor
184 * @param mixed $type
185 * @param string $desc
186 * @param bool $required
187 * @param mixed $default
188 * @param bool $allownull
189 */
c9c5cc81 190 public function __construct($type, $desc='', $required=true, $default=null, $allownull=true) {
191 parent::__construct($desc, $required);
b038c32c 192 $this->type = $type;
193 $this->default = $default;
194 $this->allownull = $allownull;
195 }
196}
197
198/**
199 * Associative array description class
200 */
201class external_single_structure extends external_description {
202 /** @property array $keys description of array keys key=>external_description */
203 public $keys;
204
205 /**
206 * Constructor
207 * @param array $keys
208 * @param string $desc
209 * @param bool $required
210 */
211 public function __construct(array $keys, $desc='', $required=true) {
c9c5cc81 212 parent::__construct($desc, $required);
b038c32c 213 $this->keys = $keys;
214 }
215}
216
217/**
218 * Bulk array description class.
219 */
220class external_multiple_structure extends external_description {
221 /** @property external_description $content */
222 public $content;
223
224 /**
225 * Constructor
226 * @param external_description $content
227 * @param string $desc
228 * @param bool $required
229 */
230 public function __construct(external_description $content, $desc='', $required=true) {
c9c5cc81 231 parent::__construct($desc, $required);
b038c32c 232 $this->content = $content;
233 }
234}
c29cca30 235
236/**
237 * Description of top level - PHP function parameters.
238 * @author skodak
239 *
240 */
241class external_function_parameters extends external_single_structure {
242}