on-demand release 2.2beta+
[moodle.git] / course / externallib.php
CommitLineData
8e7d3fe4
PS
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/**
6bb31e40 19 * External course API
8e7d3fe4 20 *
df997f84
PS
21 * @package core
22 * @subpackage course
6bb31e40 23 * @copyright 2010 Moodle Pty Ltd (http://moodle.com)
8e7d3fe4
PS
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
26
df997f84
PS
27defined('MOODLE_INTERNAL') || die;
28
8e7d3fe4
PS
29require_once("$CFG->libdir/externallib.php");
30
5d1017e1
JM
31/**
32 * Course functions
33 */
34class core_course_external extends external_api {
8e7d3fe4 35
6bb31e40 36 /**
37 * Returns description of method parameters
38 * @return external_function_parameters
39 */
40 public static function get_courses_parameters() {
41 return new external_function_parameters(
42 array('options' => new external_single_structure(
43 array('ids' => new external_multiple_structure(
44 new external_value(PARAM_INT, 'Course id')
45 , 'List of course id. If empty return all courses
46 except front page course.',
47 VALUE_OPTIONAL)
48 ), 'options - operator OR is used', VALUE_DEFAULT, array())
49 )
50 );
51 }
52
53 /**
54 * Get courses
55 * @param array $options
56 * @return array
57 */
58 public static function get_courses($options) {
59 global $CFG, $DB;
60 require_once($CFG->dirroot . "/course/lib.php");
61
62 //validate parameter
63 $params = self::validate_parameters(self::get_courses_parameters(),
64 array('options' => $options));
65
66 //retrieve courses
67 if (!key_exists('ids', $params['options'])
68 or empty($params['options']['ids'])) {
69 $courses = $DB->get_records('course');
70 } else {
71 $courses = $DB->get_records_list('course', 'id', $params['options']['ids']);
72 }
73
74 //create return value
75 $coursesinfo = array();
76 foreach ($courses as $course) {
77
78 // now security checks
79 $context = get_context_instance(CONTEXT_COURSE, $course->id);
80 try {
81 self::validate_context($context);
82 } catch (Exception $e) {
83 $exceptionparam = new stdClass();
84 $exceptionparam->message = $e->getMessage();
85 $exceptionparam->courseid = $course->id;
86 throw new moodle_exception(
87 get_string('errorcoursecontextnotvalid', 'webservice', $exceptionparam));
88 }
89 require_capability('moodle/course:view', $context);
90
91 $courseinfo = array();
92 $courseinfo['id'] = $course->id;
93 $courseinfo['fullname'] = $course->fullname;
94 $courseinfo['shortname'] = $course->shortname;
95 $courseinfo['categoryid'] = $course->category;
96 $courseinfo['summary'] = $course->summary;
97 $courseinfo['summaryformat'] = $course->summaryformat;
98 $courseinfo['format'] = $course->format;
99 $courseinfo['startdate'] = $course->startdate;
100 $courseinfo['numsections'] = $course->numsections;
101
102 //some field should be returned only if the user has update permission
103 $courseadmin = has_capability('moodle/course:update', $context);
104 if ($courseadmin) {
105 $courseinfo['categorysortorder'] = $course->sortorder;
106 $courseinfo['idnumber'] = $course->idnumber;
107 $courseinfo['showgrades'] = $course->showgrades;
108 $courseinfo['showreports'] = $course->showreports;
109 $courseinfo['newsitems'] = $course->newsitems;
110 $courseinfo['visible'] = $course->visible;
111 $courseinfo['maxbytes'] = $course->maxbytes;
112 $courseinfo['hiddensections'] = $course->hiddensections;
113 $courseinfo['groupmode'] = $course->groupmode;
114 $courseinfo['groupmodeforce'] = $course->groupmodeforce;
115 $courseinfo['defaultgroupingid'] = $course->defaultgroupingid;
116 $courseinfo['lang'] = $course->lang;
117 $courseinfo['timecreated'] = $course->timecreated;
118 $courseinfo['timemodified'] = $course->timemodified;
119 $courseinfo['forcetheme'] = $course->theme;
120 $courseinfo['enablecompletion'] = $course->enablecompletion;
121 $courseinfo['completionstartonenrol'] = $course->completionstartonenrol;
122 $courseinfo['completionnotify'] = $course->completionnotify;
123 }
124
125 if ($courseadmin or $course->visible
126 or has_capability('moodle/course:viewhiddencourses', $context)) {
127 $coursesinfo[] = $courseinfo;
128 }
129 }
130
131 return $coursesinfo;
132 }
133
134 /**
135 * Returns description of method result value
136 * @return external_description
137 */
138 public static function get_courses_returns() {
139 return new external_multiple_structure(
140 new external_single_structure(
141 array(
142 'id' => new external_value(PARAM_INT, 'course id'),
143 'shortname' => new external_value(PARAM_TEXT, 'course short name'),
144 'categoryid' => new external_value(PARAM_INT, 'category id'),
145 'categorysortorder' => new external_value(PARAM_INT,
146 'sort order into the category', VALUE_OPTIONAL),
147 'fullname' => new external_value(PARAM_TEXT, 'full name'),
148 'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL),
149 'summary' => new external_value(PARAM_RAW, 'summary'),
150 'summaryformat' => new external_value(PARAM_INT,
151 'the summary text Moodle format'),
aff24313 152 'format' => new external_value(PARAM_PLUGIN,
6bb31e40 153 'course format: weeks, topics, social, site,..'),
154 'showgrades' => new external_value(PARAM_INT,
155 '1 if grades are shown, otherwise 0', VALUE_OPTIONAL),
156 'newsitems' => new external_value(PARAM_INT,
157 'number of recent items appearing on the course page', VALUE_OPTIONAL),
158 'startdate' => new external_value(PARAM_INT,
159 'timestamp when the course start'),
160 'numsections' => new external_value(PARAM_INT, 'number of weeks/topics'),
161 'maxbytes' => new external_value(PARAM_INT,
162 'largest size of file that can be uploaded into the course',
163 VALUE_OPTIONAL),
164 'showreports' => new external_value(PARAM_INT,
165 'are activity report shown (yes = 1, no =0)', VALUE_OPTIONAL),
166 'visible' => new external_value(PARAM_INT,
167 '1: available to student, 0:not available', VALUE_OPTIONAL),
168 'hiddensections' => new external_value(PARAM_INT,
169 'How the hidden sections in the course are displayed to students',
170 VALUE_OPTIONAL),
171 'groupmode' => new external_value(PARAM_INT, 'no group, separate, visible',
172 VALUE_OPTIONAL),
173 'groupmodeforce' => new external_value(PARAM_INT, '1: yes, 0: no',
174 VALUE_OPTIONAL),
175 'defaultgroupingid' => new external_value(PARAM_INT, 'default grouping id',
176 VALUE_OPTIONAL),
177 'timecreated' => new external_value(PARAM_INT,
178 'timestamp when the course have been created', VALUE_OPTIONAL),
179 'timemodified' => new external_value(PARAM_INT,
180 'timestamp when the course have been modified', VALUE_OPTIONAL),
181 'enablecompletion' => new external_value(PARAM_INT,
182 'Enabled, control via completion and activity settings. Disbaled,
183 not shown in activity settings.',
184 VALUE_OPTIONAL),
185 'completionstartonenrol' => new external_value(PARAM_INT,
186 '1: begin tracking a student\'s progress in course completion
187 after course enrolment. 0: does not',
188 VALUE_OPTIONAL),
189 'completionnotify' => new external_value(PARAM_INT,
190 '1: yes 0: no', VALUE_OPTIONAL),
aff24313 191 'lang' => new external_value(PARAM_SAFEDIR,
6bb31e40 192 'forced course language', VALUE_OPTIONAL),
aff24313 193 'forcetheme' => new external_value(PARAM_PLUGIN,
6bb31e40 194 'name of the force theme', VALUE_OPTIONAL),
195 ), 'course'
196 )
197 );
198 }
199
200 /**
201 * Returns description of method parameters
202 * @return external_function_parameters
203 */
204 public static function create_courses_parameters() {
205 $courseconfig = get_config('moodlecourse'); //needed for many default values
206 return new external_function_parameters(
207 array(
208 'courses' => new external_multiple_structure(
209 new external_single_structure(
210 array(
211 'fullname' => new external_value(PARAM_TEXT, 'full name'),
212 'shortname' => new external_value(PARAM_TEXT, 'course short name'),
213 'categoryid' => new external_value(PARAM_INT, 'category id'),
214 'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL),
215 'summary' => new external_value(PARAM_RAW, 'summary', VALUE_OPTIONAL),
216 'summaryformat' => new external_value(PARAM_INT,
217 'the summary text Moodle format', VALUE_DEFAULT, FORMAT_MOODLE),
aff24313 218 'format' => new external_value(PARAM_PLUGIN,
6bb31e40 219 'course format: weeks, topics, social, site,..',
220 VALUE_DEFAULT, $courseconfig->format),
221 'showgrades' => new external_value(PARAM_INT,
222 '1 if grades are shown, otherwise 0', VALUE_DEFAULT,
223 $courseconfig->showgrades),
224 'newsitems' => new external_value(PARAM_INT,
225 'number of recent items appearing on the course page',
226 VALUE_DEFAULT, $courseconfig->newsitems),
227 'startdate' => new external_value(PARAM_INT,
228 'timestamp when the course start', VALUE_OPTIONAL),
229 'numsections' => new external_value(PARAM_INT, 'number of weeks/topics',
230 VALUE_DEFAULT, $courseconfig->numsections),
231 'maxbytes' => new external_value(PARAM_INT,
232 'largest size of file that can be uploaded into the course',
233 VALUE_DEFAULT, $courseconfig->maxbytes),
234 'showreports' => new external_value(PARAM_INT,
235 'are activity report shown (yes = 1, no =0)', VALUE_DEFAULT,
236 $courseconfig->showreports),
237 'visible' => new external_value(PARAM_INT,
238 '1: available to student, 0:not available', VALUE_OPTIONAL),
239 'hiddensections' => new external_value(PARAM_INT,
240 'How the hidden sections in the course are displayed to students',
241 VALUE_DEFAULT, $courseconfig->hiddensections),
242 'groupmode' => new external_value(PARAM_INT, 'no group, separate, visible',
243 VALUE_DEFAULT, $courseconfig->groupmode),
244 'groupmodeforce' => new external_value(PARAM_INT, '1: yes, 0: no',
245 VALUE_DEFAULT, $courseconfig->groupmodeforce),
246 'defaultgroupingid' => new external_value(PARAM_INT, 'default grouping id',
247 VALUE_DEFAULT, 0),
248 'enablecompletion' => new external_value(PARAM_INT,
8a6b1193 249 'Enabled, control via completion and activity settings. Disabled,
6bb31e40 250 not shown in activity settings.',
251 VALUE_OPTIONAL),
252 'completionstartonenrol' => new external_value(PARAM_INT,
253 '1: begin tracking a student\'s progress in course completion after
254 course enrolment. 0: does not',
255 VALUE_OPTIONAL),
256 'completionnotify' => new external_value(PARAM_INT,
257 '1: yes 0: no', VALUE_OPTIONAL),
aff24313 258 'lang' => new external_value(PARAM_SAFEDIR,
6bb31e40 259 'forced course language', VALUE_OPTIONAL),
aff24313 260 'forcetheme' => new external_value(PARAM_PLUGIN,
6bb31e40 261 'name of the force theme', VALUE_OPTIONAL),
262 )
263 ), 'courses to create'
264 )
265 )
266 );
267 }
268
269 /**
270 * Create courses
271 * @param array $courses
272 * @return array courses (id and shortname only)
273 */
274 public static function create_courses($courses) {
275 global $CFG, $DB;
276 require_once($CFG->dirroot . "/course/lib.php");
277 require_once($CFG->libdir . '/completionlib.php');
278
279
280 $params = self::validate_parameters(self::create_courses_parameters(),
281 array('courses' => $courses));
282
283 $availablethemes = get_plugin_list('theme');
284 $availablelangs = get_string_manager()->get_list_of_translations();
285
286 $transaction = $DB->start_delegated_transaction();
287
288 foreach ($params['courses'] as $course) {
289
290 // Ensure the current user is allowed to run this function
291 $context = get_context_instance(CONTEXT_COURSECAT, $course['categoryid']);
292 try {
293 self::validate_context($context);
294 } catch (Exception $e) {
295 $exceptionparam = new stdClass();
296 $exceptionparam->message = $e->getMessage();
297 $exceptionparam->catid = $course['categoryid'];
298 throw new moodle_exception(
299 get_string('errorcatcontextnotvalid', 'webservice', $exceptionparam));
300 }
301 require_capability('moodle/course:create', $context);
302
303 // Make sure lang is valid
304 if (key_exists('lang', $course) and empty($availablelangs[$course['lang']])) {
305 throw new moodle_exception(
306 get_string('errorinvalidparam', 'webservice', 'lang'));
307 }
308
309 // Make sure theme is valid
310 if (key_exists('forcetheme', $course)) {
311 if (!empty($CFG->allowcoursethemes)) {
312 if (empty($availablethemes[$course['forcetheme']])) {
313 throw new moodle_exception(
314 get_string('errorinvalidparam', 'webservice', 'forcetheme'));
315 } else {
316 $course['theme'] = $course['forcetheme'];
317 }
318 }
319 }
320
321 //force visibility if ws user doesn't have the permission to set it
322 $category = $DB->get_record('course_categories', array('id' => $course['categoryid']));
323 if (!has_capability('moodle/course:visibility', $context)) {
324 $course['visible'] = $category->visible;
325 }
326
327 //set default value for completion
8a6b1193 328 $courseconfig = get_config('moodlecourse');
6bb31e40 329 if (completion_info::is_enabled_for_site()) {
330 if (!key_exists('enablecompletion', $course)) {
8a6b1193 331 $course['enablecompletion'] = $courseconfig->enablecompletion;
6bb31e40 332 }
333 if (!key_exists('completionstartonenrol', $course)) {
8a6b1193 334 $course['completionstartonenrol'] = $courseconfig->completionstartonenrol;
6bb31e40 335 }
336 } else {
337 $course['enablecompletion'] = 0;
338 $course['completionstartonenrol'] = 0;
339 }
340
341 $course['category'] = $course['categoryid'];
342
343 //Note: create_course() core function check shortname, idnumber, category
344 $course['id'] = create_course((object) $course)->id;
345
346 $resultcourses[] = array('id' => $course['id'], 'shortname' => $course['shortname']);
347 }
348
349 $transaction->allow_commit();
350
351 return $resultcourses;
352 }
353
354 /**
355 * Returns description of method result value
356 * @return external_description
357 */
358 public static function create_courses_returns() {
359 return new external_multiple_structure(
360 new external_single_structure(
361 array(
362 'id' => new external_value(PARAM_INT, 'course id'),
363 'shortname' => new external_value(PARAM_TEXT, 'short name'),
364 )
365 )
366 );
367 }
368
5d1017e1
JM
369}
370
371/**
372 * Deprecated course functions
373 * @deprecated since Moodle 2.2 please use core_course_external instead
374 */
375class moodle_course_external extends external_api {
376
377 /**
378 * Returns description of method parameters
379 * @deprecated since Moodle 2.2 please use core_course_external::get_courses_parameters instead
380 * @return external_function_parameters
381 */
382 public static function get_courses_parameters() {
383 return core_course_external::get_courses_parameters();
384 }
385
386 /**
387 * Get courses
388 * @param array $options
389 * @deprecated since Moodle 2.2 please use core_course_external::get_courses instead
390 * @return array
391 */
392 public static function get_courses($options) {
393 return core_course_external::get_courses($options);
394 }
395
396 /**
397 * Returns description of method result value
398 * @deprecated since Moodle 2.2 please use core_course_external::get_courses_returns instead
399 * @return external_description
400 */
401 public static function get_courses_returns() {
402 return core_course_external::get_courses_returns();
403 }
404
405 /**
406 * Returns description of method parameters
407 * @deprecated since Moodle 2.2 please use core_course_external::create_courses_parameters instead
408 * @return external_function_parameters
409 */
410 public static function create_courses_parameters() {
411 return core_course_external::create_courses_parameters();
412 }
413
414 /**
415 * Create courses
416 * @deprecated since Moodle 2.2 please use core_course_external::create_courses instead
417 * @param array $courses
418 * @return array courses (id and shortname only)
419 */
420 public static function create_courses($courses) {
421 return core_course_external::create_courses($courses);
422 }
423
424 /**
425 * Returns description of method result value
426 * @deprecated since Moodle 2.2 please use core_course_external::create_courses_returns instead
427 * @return external_description
428 */
429 public static function create_courses_returns() {
430 return core_course_external::create_courses_returns();
431 }
432
8e7d3fe4 433}