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