Merge branch 'MDL-32941' of git://github.com/mouneyrac/moodle
[moodle.git] / course / externallib.php
CommitLineData
8e7d3fe4 1<?php
8e7d3fe4
PS
2// This file is part of Moodle - http://moodle.org/
3//
4// Moodle is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// Moodle is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
16
4615817d 17
8e7d3fe4 18/**
6bb31e40 19 * External course API
8e7d3fe4 20 *
4615817d
JM
21 * @package core_course
22 * @category external
23 * @copyright 2009 Petr Skodak
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 31/**
4615817d
JM
32 * Course external functions
33 *
34 * @package core_course
35 * @category external
36 * @copyright 2011 Jerome Mouneyrac
37 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
38 * @since Moodle 2.2
5d1017e1
JM
39 */
40class core_course_external extends external_api {
8e7d3fe4 41
ec0d6ea2
DC
42 /**
43 * Returns description of method parameters
4615817d 44 *
ec0d6ea2 45 * @return external_function_parameters
4615817d 46 * @since Moodle 2.2
ec0d6ea2
DC
47 */
48 public static function get_course_contents_parameters() {
49 return new external_function_parameters(
50 array('courseid' => new external_value(PARAM_INT, 'course id'),
51 'options' => new external_multiple_structure (
52 new external_single_structure(
53 array('name' => new external_value(PARAM_ALPHANUM, 'option name'),
54 'value' => new external_value(PARAM_RAW, 'the value of the option, this param is personaly validated in the external function.')
55 )
56 ), 'Options, not used yet, might be used in later version', VALUE_DEFAULT, array())
57 )
58 );
59 }
60
61 /**
62 * Get course contents
4615817d
JM
63 *
64 * @param int $courseid course id
65 * @param array $options These options are not used yet, might be used in later version
ec0d6ea2 66 * @return array
4615817d 67 * @since Moodle 2.2
ec0d6ea2
DC
68 */
69 public static function get_course_contents($courseid, $options) {
70 global $CFG, $DB;
71 require_once($CFG->dirroot . "/course/lib.php");
72
73 //validate parameter
74 $params = self::validate_parameters(self::get_course_contents_parameters(),
75 array('courseid' => $courseid, 'options' => $options));
76
77 //retrieve the course
78 $course = $DB->get_record('course', array('id' => $params['courseid']), '*', MUST_EXIST);
79
80 //check course format exist
81 if (!file_exists($CFG->dirroot . '/course/format/' . $course->format . '/lib.php')) {
82 throw new moodle_exception('cannotgetcoursecontents', 'webservice', '', null, get_string('courseformatnotfound', 'error', '', $course->format));
83 } else {
84 require_once($CFG->dirroot . '/course/format/' . $course->format . '/lib.php');
85 }
86
87 // now security checks
88 $context = get_context_instance(CONTEXT_COURSE, $course->id);
89 try {
90 self::validate_context($context);
91 } catch (Exception $e) {
92 $exceptionparam = new stdClass();
93 $exceptionparam->message = $e->getMessage();
94 $exceptionparam->courseid = $course->id;
95 throw new moodle_exception('errorcoursecontextnotvalid', 'webservice', '', $exceptionparam);
96 }
97
98 $canupdatecourse = has_capability('moodle/course:update', $context);
99
100 //create return value
101 $coursecontents = array();
102
103 if ($canupdatecourse or $course->visible
104 or has_capability('moodle/course:viewhiddencourses', $context)) {
105
106 //retrieve sections
107 $modinfo = get_fast_modinfo($course);
108 $sections = get_all_sections($course->id);
109
110 //for each sections (first displayed to last displayed)
111 foreach ($sections as $key => $section) {
112
113 $showsection = (has_capability('moodle/course:viewhiddensections', $context) or $section->visible or !$course->hiddensections);
114 if (!$showsection) {
115 continue;
116 }
117
118 // reset $sectioncontents
119 $sectionvalues = array();
120 $sectionvalues['id'] = $section->id;
121 $sectionvalues['name'] = get_section_name($course, $section);
122 $summary = file_rewrite_pluginfile_urls($section->summary, 'webservice/pluginfile.php', $context->id, 'course', 'section', $section->id);
123 $sectionvalues['visible'] = $section->visible;
124 $sectionvalues['summary'] = format_text($summary, $section->summaryformat);
125 $sectioncontents = array();
126
127 //for each module of the section
128 foreach ($modinfo->sections[$section->section] as $cmid) { //matching /course/lib.php:print_section() logic
129 $cm = $modinfo->cms[$cmid];
130
131 // stop here if the module is not visible to the user
132 if (!$cm->uservisible) {
133 continue;
134 }
135
136 $module = array();
137
138 //common info (for people being able to see the module or availability dates)
139 $module['id'] = $cm->id;
140 $module['name'] = format_string($cm->name, true);
141 $module['modname'] = $cm->modname;
142 $module['modplural'] = $cm->modplural;
143 $module['modicon'] = $cm->get_icon_url()->out(false);
144 $module['indent'] = $cm->indent;
145
146 $modcontext = get_context_instance(CONTEXT_MODULE, $cm->id);
147
148 if (!empty($cm->showdescription)) {
149 $module['description'] = $cm->get_content();
150 }
151
152 //url of the module
153 $url = $cm->get_url();
154 if ($url) { //labels don't have url
155 $module['url'] = $cm->get_url()->out();
156 }
157
158 $canviewhidden = has_capability('moodle/course:viewhiddenactivities',
159 get_context_instance(CONTEXT_MODULE, $cm->id));
160 //user that can view hidden module should know about the visibility
161 $module['visible'] = $cm->visible;
162
163 //availability date (also send to user who can see hidden module when the showavailabilyt is ON)
164 if ($canupdatecourse or ($CFG->enableavailability && $canviewhidden && $cm->showavailability)) {
165 $module['availablefrom'] = $cm->availablefrom;
166 $module['availableuntil'] = $cm->availableuntil;
167 }
168
169 $baseurl = 'webservice/pluginfile.php';
170
171 //call $modulename_export_contents
172 //(each module callback take care about checking the capabilities)
173 require_once($CFG->dirroot . '/mod/' . $cm->modname . '/lib.php');
174 $getcontentfunction = $cm->modname.'_export_contents';
175 if (function_exists($getcontentfunction)) {
176 if ($contents = $getcontentfunction($cm, $baseurl)) {
177 $module['contents'] = $contents;
178 }
179 }
180
181 //assign result to $sectioncontents
182 $sectioncontents[] = $module;
183
184 }
185 $sectionvalues['modules'] = $sectioncontents;
186
187 // assign result to $coursecontents
188 $coursecontents[] = $sectionvalues;
189 }
190 }
191 return $coursecontents;
192 }
193
194 /**
195 * Returns description of method result value
4615817d 196 *
ec0d6ea2 197 * @return external_description
4615817d 198 * @since Moodle 2.2
ec0d6ea2
DC
199 */
200 public static function get_course_contents_returns() {
201 return new external_multiple_structure(
202 new external_single_structure(
203 array(
204 'id' => new external_value(PARAM_INT, 'Section ID'),
205 'name' => new external_value(PARAM_TEXT, 'Section name'),
206 'visible' => new external_value(PARAM_INT, 'is the section visible', VALUE_OPTIONAL),
207 'summary' => new external_value(PARAM_RAW, 'Section description'),
208 'modules' => new external_multiple_structure(
209 new external_single_structure(
210 array(
211 'id' => new external_value(PARAM_INT, 'activity id'),
212 'url' => new external_value(PARAM_URL, 'activity url', VALUE_OPTIONAL),
213 'name' => new external_value(PARAM_TEXT, 'activity module name'),
214 'description' => new external_value(PARAM_RAW, 'activity description', VALUE_OPTIONAL),
215 'visible' => new external_value(PARAM_INT, 'is the module visible', VALUE_OPTIONAL),
216 'modicon' => new external_value(PARAM_URL, 'activity icon url'),
217 'modname' => new external_value(PARAM_PLUGIN, 'activity module type'),
218 'modplural' => new external_value(PARAM_TEXT, 'activity module plural name'),
219 'availablefrom' => new external_value(PARAM_INT, 'module availability start date', VALUE_OPTIONAL),
220 'availableuntil' => new external_value(PARAM_INT, 'module availability en date', VALUE_OPTIONAL),
221 'indent' => new external_value(PARAM_INT, 'number of identation in the site'),
222 'contents' => new external_multiple_structure(
223 new external_single_structure(
224 array(
225 // content info
226 'type'=> new external_value(PARAM_TEXT, 'a file or a folder or external link'),
227 'filename'=> new external_value(PARAM_FILE, 'filename'),
228 'filepath'=> new external_value(PARAM_PATH, 'filepath'),
229 'filesize'=> new external_value(PARAM_INT, 'filesize'),
230 'fileurl' => new external_value(PARAM_URL, 'downloadable file url', VALUE_OPTIONAL),
231 'content' => new external_value(PARAM_RAW, 'Raw content, will be used when type is content', VALUE_OPTIONAL),
232 'timecreated' => new external_value(PARAM_INT, 'Time created'),
233 'timemodified' => new external_value(PARAM_INT, 'Time modified'),
234 'sortorder' => new external_value(PARAM_INT, 'Content sort order'),
235
236 // copyright related info
237 'userid' => new external_value(PARAM_INT, 'User who added this content to moodle'),
238 'author' => new external_value(PARAM_TEXT, 'Content owner'),
239 'license' => new external_value(PARAM_TEXT, 'Content license'),
240 )
241 ), VALUE_DEFAULT, array()
242 )
243 )
244 ), 'list of module'
245 )
246 )
247 )
248 );
249 }
250
6bb31e40 251 /**
252 * Returns description of method parameters
4615817d 253 *
6bb31e40 254 * @return external_function_parameters
754c2dea 255 * @since Moodle 2.3
6bb31e40 256 */
dd5e31f3 257 public static function get_categories_parameters() {
6c6ec1d6 258 return new external_function_parameters(
dd5e31f3 259 array(
d4a17894 260 'criteria' => new external_multiple_structure(
261 new external_single_structure(
262 array(
6c6ec1d6
JM
263 'key' => new external_value(PARAM_ALPHA,
264 'The category column to search, expected keys (value format) are:'.
265 '"id" (int) the category id,'.
266 '"name" (string) the category name,'.
267 '"parent" (int) the parent category id,'.
268 '"idnumber" (string) category idnumber'.
269 ' - user must have \'moodle/category:manage\' to search on idnumber,'.
270 '"visible" (int) whether the category is visible or not'.
271 ' - user must have \'moodle/category:manage\' or \'moodle/category:viewhiddencategories\' to search on visible,'.
272 '"theme" (string) category theme'.
273 ' - user must have \'moodle/category:manage\' to search on theme'),
20854c75 274 'value' => new external_value(PARAM_RAW, 'the value to match')
d4a17894 275 )
20854c75
EL
276 ), VALUE_DEFAULT, array()
277 ),
d4a17894 278 'addsubcategories' => new external_value(PARAM_BOOL, 'return the sub categories infos
20854c75 279 (1 - default) otherwise only the category info (0)', VALUE_DEFAULT, 1)
d4a17894 280 )
6bb31e40 281 );
282 }
283
d4a246bc 284 /**
dd5e31f3
JM
285 * Get categories
286 *
d4a17894 287 * @param array $criteria Criteria to match the results
20854c75 288 * @param booln $addsubcategories obtain only the category (false) or its subcategories (true - default)
dd5e31f3
JM
289 * @return array list of categories
290 * @since Moodle 2.3
291 */
d4a17894 292 public static function get_categories($criteria = array(), $addsubcategories = true) {
d4a246bc
FS
293 global $CFG, $DB;
294 require_once($CFG->dirroot . "/course/lib.php");
d4a246bc 295
d4a17894 296 // Validate parameters.
dd5e31f3 297 $params = self::validate_parameters(self::get_categories_parameters(),
d4a17894 298 array('criteria' => $criteria, 'addsubcategories' => $addsubcategories));
dd5e31f3 299
d4a17894 300 // Retrieve the categories.
dd5e31f3 301 $categories = array();
d4a17894 302 if (!empty($params['criteria'])) {
303
304 $conditions = array();
305 $wheres = array();
306 foreach ($params['criteria'] as $crit) {
307 $key = trim($crit['key']);
308
309 // Trying to avoid duplicate keys.
310 if (!isset($conditions[$key])) {
311
312 $context = context_system::instance();
20854c75 313 $value = null;
d4a17894 314 switch ($key) {
20854c75
EL
315 case 'id':
316 $value = clean_param($crit['value'], PARAM_INT);
317 break;
318
319 case 'idnumber':
320 if (has_capability('moodle/category:manage', $context)) {
321 $value = clean_param($crit['value'], PARAM_RAW);
6c6ec1d6
JM
322 } else {
323 // We must throw an exception.
324 // Otherwise the dev client would think no idnumber exists.
8c507544
JM
325 throw new moodle_exception('criteriaerror',
326 'webservice', '', null,
6c6ec1d6 327 'You don\'t have the permissions to search on the "idnumber" field.');
20854c75
EL
328 }
329 break;
330
331 case 'name':
332 $value = clean_param($crit['value'], PARAM_TEXT);
333 break;
334
335 case 'parent':
336 $value = clean_param($crit['value'], PARAM_INT);
337 break;
338
339 case 'visible':
6c6ec1d6
JM
340 if (has_capability('moodle/category:manage', $context)
341 or has_capability('moodle/category:viewhiddencategories',
342 context_system::instance())) {
343 $value = clean_param($crit['value'], PARAM_INT);
344 } else {
8c507544
JM
345 throw new moodle_exception('criteriaerror',
346 'webservice', '', null,
6c6ec1d6
JM
347 'You don\'t have the permissions to search on the "visible" field.');
348 }
20854c75
EL
349 break;
350
351 case 'theme':
352 if (has_capability('moodle/category:manage', $context)) {
353 $value = clean_param($crit['value'], PARAM_THEME);
6c6ec1d6 354 } else {
8c507544
JM
355 throw new moodle_exception('criteriaerror',
356 'webservice', '', null,
6c6ec1d6 357 'You don\'t have the permissions to search on the "theme" field.');
20854c75
EL
358 }
359 break;
360
361 default:
8c507544
JM
362 throw new moodle_exception('criteriaerror',
363 'webservice', '', null,
6c6ec1d6 364 'You can not search on this criteria: ' . $key);
d4a17894 365 }
366
20854c75 367 if (isset($value)) {
d4a17894 368 $conditions[$key] = $crit['value'];
369 $wheres[] = $key . " = :" . $key;
370 }
371 }
372 }
373
374 if (!empty($wheres)) {
375 $wheres = implode(" AND ", $wheres);
376
6c6ec1d6 377 $categories = $DB->get_records_select('course_categories', $wheres, $conditions);
d4a17894 378
379 // Retrieve its sub subcategories (all levels).
380 if ($categories and !empty($params['addsubcategories'])) {
381 $newcategories = array();
382
383 foreach ($categories as $category) {
384 $sqllike = $DB->sql_like('path', ':path');
20854c75 385 $sqlparams = array('path' => $category->path.'/%'); // It will NOT include the specified category.
6c6ec1d6
JM
386 $subcategories = $DB->get_records_select('course_categories', $sqllike, $sqlparams);
387 $newcategories = $newcategories + $subcategories; // Both arrays have integer as keys.
d4a17894 388 }
6c6ec1d6 389 $categories = $categories + $newcategories;
d4a17894 390 }
391 }
392
dd5e31f3 393 } else {
d4a17894 394 // Retrieve all categories in the database.
6c6ec1d6 395 $categories = $DB->get_records('course_categories');
d4a246bc
FS
396 }
397
d4a17894 398 // The not returned categories. key => category id, value => reason of exclusion.
dd5e31f3
JM
399 $excludedcats = array();
400
d4a17894 401 // The returned categories.
d4a246bc 402 $categoriesinfo = array();
dd5e31f3 403
6c6ec1d6
JM
404 // We need to sort the categories by path.
405 // The parent cats need to be checked by the algo first.
406 usort($categories, "core_course_external::compare_categories_by_path");
407
d4a246bc 408 foreach ($categories as $category) {
dd5e31f3 409
d4a17894 410 // Check if the category is a child of an excluded category, if yes exclude it too (excluded => do not return).
dd5e31f3 411 $parents = explode('/', $category->path);
d4a17894 412 unset($parents[0]); // First key is always empty because path start with / => /1/2/4.
dd5e31f3
JM
413 foreach ($parents as $parentid) {
414 // Note: when the parent exclusion was due to the context,
d4a17894 415 // the sub category could still be returned.
dd5e31f3
JM
416 if (isset($excludedcats[$parentid]) and $excludedcats[$parentid] != 'context') {
417 $excludedcats[$category->id] = 'parent';
418 }
419 }
420
d4a17894 421 // Check category depth is <= maxdepth (do not check for user who can manage categories).
dd5e31f3
JM
422 if ((!empty($CFG->maxcategorydepth) && count($parents) > $CFG->maxcategorydepth)
423 and !has_capability('moodle/category:manage', $context)) {
424 $excludedcats[$category->id] = 'depth';
425 }
426
d4a17894 427 // Check the user can use the category context.
d4a246bc
FS
428 $context = context_coursecat::instance($category->id);
429 try {
430 self::validate_context($context);
431 } catch (Exception $e) {
dd5e31f3
JM
432 $excludedcats[$category->id] = 'context';
433
d4a17894 434 // If it was the requested category then throw an exception.
dd5e31f3
JM
435 if (isset($params['categoryid']) && $category->id == $params['categoryid']) {
436 $exceptionparam = new stdClass();
437 $exceptionparam->message = $e->getMessage();
438 $exceptionparam->catid = $category->id;
d4a246bc 439 throw new moodle_exception('errorcatcontextnotvalid', 'webservice', '', $exceptionparam);
dd5e31f3 440 }
d4a246bc
FS
441 }
442
d4a17894 443 // Return the category information.
dd5e31f3
JM
444 if (!isset($excludedcats[$category->id])) {
445
d4a17894 446 // Final check to see if the category is visible to the user.
dd5e31f3
JM
447 if ($category->visible
448 or has_capability('moodle/category:viewhiddencategories', context_system::instance())
449 or has_capability('moodle/category:manage', $context)) {
450
451 $categoryinfo = array();
452 $categoryinfo['id'] = $category->id;
453 $categoryinfo['name'] = $category->name;
454 $categoryinfo['description'] = file_rewrite_pluginfile_urls($category->description,
455 'webservice/pluginfile.php', $context->id, 'coursecat', 'description', null);
456 $options = new stdClass;
457 $options->noclean = true;
458 $options->para = false;
459 $categoryinfo['description'] = format_text($categoryinfo['description'],
460 $category->descriptionformat, $options);
461 $categoryinfo['parent'] = $category->parent;
462 $categoryinfo['sortorder'] = $category->sortorder;
463 $categoryinfo['coursecount'] = $category->coursecount;
464 $categoryinfo['depth'] = $category->depth;
465 $categoryinfo['path'] = $category->path;
466
d4a17894 467 // Some fields only returned for admin.
dd5e31f3
JM
468 if (has_capability('moodle/category:manage', $context)) {
469 $categoryinfo['idnumber'] = $category->idnumber;
470 $categoryinfo['visible'] = $category->visible;
471 $categoryinfo['visibleold'] = $category->visibleold;
472 $categoryinfo['timemodified'] = $category->timemodified;
473 $categoryinfo['theme'] = $category->theme;
474 }
d4a246bc 475
dd5e31f3
JM
476 $categoriesinfo[] = $categoryinfo;
477 } else {
478 $excludedcats[$category->id] = 'visibility';
479 }
d4a246bc
FS
480 }
481 }
482
6c6ec1d6
JM
483 // Sorting the resulting array so it looks a bit better for the client developer.
484 usort($categoriesinfo, "core_course_external::compare_categories_by_sortorder");
485
d4a246bc
FS
486 return $categoriesinfo;
487 }
488
6c6ec1d6
JM
489 /**
490 * Sort categories array by path
491 * private function: only used by get_categories
492 *
493 * @param array $category1
494 * @param array $category2
495 * @return int result of strcmp
496 * @since Moodle 2.3
497 */
8c507544 498 private static function compare_categories_by_path($category1, $category2) {
6c6ec1d6
JM
499 return strcmp($category1->path, $category2->path);
500 }
501
502 /**
503 * Sort categories array by sortorder
504 * private function: only used by get_categories
505 *
506 * @param array $category1
507 * @param array $category2
508 * @return int result of strcmp
509 * @since Moodle 2.3
510 */
8c507544 511 private static function compare_categories_by_sortorder($category1, $category2) {
6c6ec1d6
JM
512 return strcmp($category1['sortorder'], $category2['sortorder']);
513 }
514
d4a246bc 515 /**
dd5e31f3
JM
516 * Returns description of method result value
517 *
518 * @return external_description
519 * @since Moodle 2.3
520 */
d4a246bc
FS
521 public static function get_categories_returns() {
522 return new external_multiple_structure(
523 new external_single_structure(
524 array(
525 'id' => new external_value(PARAM_INT, 'category id'),
526 'name' => new external_value(PARAM_TEXT, 'category name'),
527 'idnumber' => new external_value(PARAM_RAW, 'category id number', VALUE_OPTIONAL),
dd5e31f3 528 'description' => new external_value(PARAM_RAW, 'category description'),
d4a246bc
FS
529 'parent' => new external_value(PARAM_INT, 'parent category id'),
530 'sortorder' => new external_value(PARAM_INT, 'category sorting order'),
531 'coursecount' => new external_value(PARAM_INT, 'number of courses in this category'),
532 'visible' => new external_value(PARAM_INT, '1: available, 0:not available', VALUE_OPTIONAL),
533 'visibleold' => new external_value(PARAM_INT, '1: available, 0:not available', VALUE_OPTIONAL),
534 'timemodified' => new external_value(PARAM_INT, 'timestamp', VALUE_OPTIONAL),
535 'depth' => new external_value(PARAM_INT, 'category depth'),
536 'path' => new external_value(PARAM_TEXT, 'category path'),
537 'theme' => new external_value(PARAM_THEME, 'category theme', VALUE_OPTIONAL),
d4a17894 538 ), 'List of categories'
d4a246bc
FS
539 )
540 );
541 }
542
6bb31e40 543 /**
544 * Returns description of method parameters
4615817d 545 *
6bb31e40 546 * @return external_function_parameters
4615817d 547 * @since Moodle 2.2
6bb31e40 548 */
549 public static function get_courses_parameters() {
550 return new external_function_parameters(
551 array('options' => new external_single_structure(
552 array('ids' => new external_multiple_structure(
553 new external_value(PARAM_INT, 'Course id')
554 , 'List of course id. If empty return all courses
555 except front page course.',
556 VALUE_OPTIONAL)
557 ), 'options - operator OR is used', VALUE_DEFAULT, array())
558 )
559 );
560 }
561
562 /**
563 * Get courses
4615817d
JM
564 *
565 * @param array $options It contains an array (list of ids)
6bb31e40 566 * @return array
4615817d 567 * @since Moodle 2.2
6bb31e40 568 */
569 public static function get_courses($options) {
570 global $CFG, $DB;
571 require_once($CFG->dirroot . "/course/lib.php");
572
573 //validate parameter
574 $params = self::validate_parameters(self::get_courses_parameters(),
575 array('options' => $options));
576
577 //retrieve courses
578 if (!key_exists('ids', $params['options'])
579 or empty($params['options']['ids'])) {
580 $courses = $DB->get_records('course');
581 } else {
582 $courses = $DB->get_records_list('course', 'id', $params['options']['ids']);
583 }
584
585 //create return value
586 $coursesinfo = array();
587 foreach ($courses as $course) {
588
589 // now security checks
590 $context = get_context_instance(CONTEXT_COURSE, $course->id);
591 try {
592 self::validate_context($context);
593 } catch (Exception $e) {
594 $exceptionparam = new stdClass();
595 $exceptionparam->message = $e->getMessage();
596 $exceptionparam->courseid = $course->id;
597 throw new moodle_exception(
598 get_string('errorcoursecontextnotvalid', 'webservice', $exceptionparam));
599 }
600 require_capability('moodle/course:view', $context);
601
602 $courseinfo = array();
603 $courseinfo['id'] = $course->id;
604 $courseinfo['fullname'] = $course->fullname;
605 $courseinfo['shortname'] = $course->shortname;
606 $courseinfo['categoryid'] = $course->category;
607 $courseinfo['summary'] = $course->summary;
608 $courseinfo['summaryformat'] = $course->summaryformat;
609 $courseinfo['format'] = $course->format;
610 $courseinfo['startdate'] = $course->startdate;
611 $courseinfo['numsections'] = $course->numsections;
612
613 //some field should be returned only if the user has update permission
614 $courseadmin = has_capability('moodle/course:update', $context);
615 if ($courseadmin) {
616 $courseinfo['categorysortorder'] = $course->sortorder;
617 $courseinfo['idnumber'] = $course->idnumber;
618 $courseinfo['showgrades'] = $course->showgrades;
619 $courseinfo['showreports'] = $course->showreports;
620 $courseinfo['newsitems'] = $course->newsitems;
621 $courseinfo['visible'] = $course->visible;
622 $courseinfo['maxbytes'] = $course->maxbytes;
623 $courseinfo['hiddensections'] = $course->hiddensections;
624 $courseinfo['groupmode'] = $course->groupmode;
625 $courseinfo['groupmodeforce'] = $course->groupmodeforce;
626 $courseinfo['defaultgroupingid'] = $course->defaultgroupingid;
627 $courseinfo['lang'] = $course->lang;
628 $courseinfo['timecreated'] = $course->timecreated;
629 $courseinfo['timemodified'] = $course->timemodified;
630 $courseinfo['forcetheme'] = $course->theme;
631 $courseinfo['enablecompletion'] = $course->enablecompletion;
632 $courseinfo['completionstartonenrol'] = $course->completionstartonenrol;
633 $courseinfo['completionnotify'] = $course->completionnotify;
634 }
635
636 if ($courseadmin or $course->visible
637 or has_capability('moodle/course:viewhiddencourses', $context)) {
638 $coursesinfo[] = $courseinfo;
639 }
640 }
641
642 return $coursesinfo;
643 }
644
645 /**
646 * Returns description of method result value
4615817d 647 *
6bb31e40 648 * @return external_description
4615817d 649 * @since Moodle 2.2
6bb31e40 650 */
651 public static function get_courses_returns() {
652 return new external_multiple_structure(
653 new external_single_structure(
654 array(
655 'id' => new external_value(PARAM_INT, 'course id'),
656 'shortname' => new external_value(PARAM_TEXT, 'course short name'),
657 'categoryid' => new external_value(PARAM_INT, 'category id'),
658 'categorysortorder' => new external_value(PARAM_INT,
659 'sort order into the category', VALUE_OPTIONAL),
660 'fullname' => new external_value(PARAM_TEXT, 'full name'),
661 'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL),
662 'summary' => new external_value(PARAM_RAW, 'summary'),
663 'summaryformat' => new external_value(PARAM_INT,
664 'the summary text Moodle format'),
aff24313 665 'format' => new external_value(PARAM_PLUGIN,
6bb31e40 666 'course format: weeks, topics, social, site,..'),
667 'showgrades' => new external_value(PARAM_INT,
668 '1 if grades are shown, otherwise 0', VALUE_OPTIONAL),
669 'newsitems' => new external_value(PARAM_INT,
670 'number of recent items appearing on the course page', VALUE_OPTIONAL),
671 'startdate' => new external_value(PARAM_INT,
672 'timestamp when the course start'),
673 'numsections' => new external_value(PARAM_INT, 'number of weeks/topics'),
674 'maxbytes' => new external_value(PARAM_INT,
675 'largest size of file that can be uploaded into the course',
676 VALUE_OPTIONAL),
677 'showreports' => new external_value(PARAM_INT,
678 'are activity report shown (yes = 1, no =0)', VALUE_OPTIONAL),
679 'visible' => new external_value(PARAM_INT,
680 '1: available to student, 0:not available', VALUE_OPTIONAL),
681 'hiddensections' => new external_value(PARAM_INT,
682 'How the hidden sections in the course are displayed to students',
683 VALUE_OPTIONAL),
684 'groupmode' => new external_value(PARAM_INT, 'no group, separate, visible',
685 VALUE_OPTIONAL),
686 'groupmodeforce' => new external_value(PARAM_INT, '1: yes, 0: no',
687 VALUE_OPTIONAL),
688 'defaultgroupingid' => new external_value(PARAM_INT, 'default grouping id',
689 VALUE_OPTIONAL),
690 'timecreated' => new external_value(PARAM_INT,
691 'timestamp when the course have been created', VALUE_OPTIONAL),
692 'timemodified' => new external_value(PARAM_INT,
693 'timestamp when the course have been modified', VALUE_OPTIONAL),
694 'enablecompletion' => new external_value(PARAM_INT,
695 'Enabled, control via completion and activity settings. Disbaled,
696 not shown in activity settings.',
697 VALUE_OPTIONAL),
698 'completionstartonenrol' => new external_value(PARAM_INT,
699 '1: begin tracking a student\'s progress in course completion
700 after course enrolment. 0: does not',
701 VALUE_OPTIONAL),
702 'completionnotify' => new external_value(PARAM_INT,
703 '1: yes 0: no', VALUE_OPTIONAL),
aff24313 704 'lang' => new external_value(PARAM_SAFEDIR,
6bb31e40 705 'forced course language', VALUE_OPTIONAL),
aff24313 706 'forcetheme' => new external_value(PARAM_PLUGIN,
6bb31e40 707 'name of the force theme', VALUE_OPTIONAL),
708 ), 'course'
709 )
710 );
711 }
712
479a5db1 713 /**
be051808
FS
714 * Returns description of method parameters
715 *
716 * @return external_function_parameters
717 * @since Moodle 2.3
718 */
95693c43
JM
719 public static function create_categories_parameters() {
720 return new external_function_parameters(
721 array(
722 'categories' => new external_multiple_structure(
723 new external_single_structure(
724 array(
725 'name' => new external_value(PARAM_TEXT, 'new category name'),
be051808
FS
726 'parent' => new external_value(PARAM_INT,
727 'the parent category id inside which the new category will be created'),
728 'idnumber' => new external_value(PARAM_RAW,
729 'the new category idnumber', VALUE_OPTIONAL),
730 'description' => new external_value(PARAM_RAW,
731 'the new category description', VALUE_OPTIONAL),
95693c43 732 'theme' => new external_value(PARAM_THEME,
be051808
FS
733 'the new category theme. This option must be enabled on moodle',
734 VALUE_OPTIONAL),
95693c43
JM
735 )
736 )
737 )
738 )
739 );
740 }
741
742 /**
743 * Create categories
744 *
745 * @param array $categories - see create_categories_parameters() for the array structure
746 * @return array - see create_categories_returns() for the array structure
747 * @since Moodle 2.3
95693c43
JM
748 */
749 public static function create_categories($categories) {
479a5db1
FS
750 global $CFG, $DB;
751 require_once($CFG->dirroot . "/course/lib.php");
752
95693c43
JM
753 $params = self::validate_parameters(self::create_categories_parameters(),
754 array('categories' => $categories));
755
756 $transaction = $DB->start_delegated_transaction();
95693c43 757
be051808
FS
758 $createdcategories = array();
759 foreach ($params['categories'] as $category) {
479a5db1 760 if ($category['parent']) {
95693c43 761 if (!$DB->record_exists('course_categories', array('id' => $category['parent']))) {
be051808 762 throw new moodle_exception('unknowcategory');
95693c43 763 }
479a5db1 764 $context = context_coursecat::instance($category['parent']);
be051808 765 } else {
479a5db1
FS
766 $context = context_system::instance();
767 }
768 self::validate_context($context);
95693c43 769 require_capability('moodle/category:manage', $context);
479a5db1 770
be051808
FS
771 // Check id number.
772 if (!empty($category['idnumber'])) { // Same as in course/editcategory_form.php .
773 if (textlib::strlen($category['idnumber'])>100) {
774 throw new moodle_exception('idnumbertoolong');
775 }
95693c43
JM
776 if ($existing = $DB->get_record('course_categories', array('idnumber' => $category['idnumber']))) {
777 if ($existing->id) {
778 throw new moodle_exception('idnumbertaken');
779 }
780 }
781 }
be051808 782 // Check name.
d7238d08 783 if (textlib::strlen($category['name'])>255) {
be051808 784 throw new moodle_exception('categorytoolong');
95693c43 785 }
95693c43 786
be051808
FS
787 $newcategory = new stdClass();
788 $newcategory->name = $category['name'];
789 $newcategory->parent = $category['parent'];
790 $newcategory->idnumber = $category['idnumber'];
791 $newcategory->sortorder = 999; // Same as in the course/editcategory.php .
792 // Format the description.
793 if (!empty($category['description'])) {
794 $newcategory->description = $category['description'];
95693c43
JM
795 }
796 $newcategory->descriptionformat = FORMAT_HTML;
479a5db1
FS
797 if (isset($category['theme']) and !empty($CFG->allowcategorythemes)) {
798 $newcategory->theme = $category['theme'];
799 }
479a5db1 800
be051808
FS
801 $newcategory = create_course_category($newcategory);
802 // Populate special fields.
803 fix_course_sortorder();
95693c43 804
479a5db1
FS
805 $createdcategories[] = array('id' => $newcategory->id, 'name' => $newcategory->name);
806 }
807
95693c43
JM
808 $transaction->allow_commit();
809
479a5db1
FS
810 return $createdcategories;
811 }
479a5db1
FS
812
813 /**
be051808
FS
814 * Returns description of method parameters
815 *
816 * @return external_function_parameters
817 * @since Moodle 2.3
818 */
479a5db1
FS
819 public static function create_categories_returns() {
820 return new external_multiple_structure(
821 new external_single_structure(
822 array(
823 'id' => new external_value(PARAM_INT, 'new category id'),
824 'name' => new external_value(PARAM_TEXT, 'new category name'),
825 )
826 )
827 );
828 }
829
6bb31e40 830 /**
831 * Returns description of method parameters
4615817d 832 *
6bb31e40 833 * @return external_function_parameters
4615817d 834 * @since Moodle 2.2
6bb31e40 835 */
836 public static function create_courses_parameters() {
837 $courseconfig = get_config('moodlecourse'); //needed for many default values
838 return new external_function_parameters(
839 array(
840 'courses' => new external_multiple_structure(
841 new external_single_structure(
842 array(
843 'fullname' => new external_value(PARAM_TEXT, 'full name'),
844 'shortname' => new external_value(PARAM_TEXT, 'course short name'),
845 'categoryid' => new external_value(PARAM_INT, 'category id'),
846 'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL),
847 'summary' => new external_value(PARAM_RAW, 'summary', VALUE_OPTIONAL),
848 'summaryformat' => new external_value(PARAM_INT,
849 'the summary text Moodle format', VALUE_DEFAULT, FORMAT_MOODLE),
aff24313 850 'format' => new external_value(PARAM_PLUGIN,
6bb31e40 851 'course format: weeks, topics, social, site,..',
852 VALUE_DEFAULT, $courseconfig->format),
853 'showgrades' => new external_value(PARAM_INT,
854 '1 if grades are shown, otherwise 0', VALUE_DEFAULT,
855 $courseconfig->showgrades),
856 'newsitems' => new external_value(PARAM_INT,
857 'number of recent items appearing on the course page',
858 VALUE_DEFAULT, $courseconfig->newsitems),
859 'startdate' => new external_value(PARAM_INT,
860 'timestamp when the course start', VALUE_OPTIONAL),
861 'numsections' => new external_value(PARAM_INT, 'number of weeks/topics',
862 VALUE_DEFAULT, $courseconfig->numsections),
863 'maxbytes' => new external_value(PARAM_INT,
864 'largest size of file that can be uploaded into the course',
865 VALUE_DEFAULT, $courseconfig->maxbytes),
866 'showreports' => new external_value(PARAM_INT,
867 'are activity report shown (yes = 1, no =0)', VALUE_DEFAULT,
868 $courseconfig->showreports),
869 'visible' => new external_value(PARAM_INT,
870 '1: available to student, 0:not available', VALUE_OPTIONAL),
871 'hiddensections' => new external_value(PARAM_INT,
872 'How the hidden sections in the course are displayed to students',
873 VALUE_DEFAULT, $courseconfig->hiddensections),
874 'groupmode' => new external_value(PARAM_INT, 'no group, separate, visible',
875 VALUE_DEFAULT, $courseconfig->groupmode),
876 'groupmodeforce' => new external_value(PARAM_INT, '1: yes, 0: no',
877 VALUE_DEFAULT, $courseconfig->groupmodeforce),
878 'defaultgroupingid' => new external_value(PARAM_INT, 'default grouping id',
879 VALUE_DEFAULT, 0),
880 'enablecompletion' => new external_value(PARAM_INT,
8a6b1193 881 'Enabled, control via completion and activity settings. Disabled,
6bb31e40 882 not shown in activity settings.',
883 VALUE_OPTIONAL),
884 'completionstartonenrol' => new external_value(PARAM_INT,
885 '1: begin tracking a student\'s progress in course completion after
886 course enrolment. 0: does not',
887 VALUE_OPTIONAL),
888 'completionnotify' => new external_value(PARAM_INT,
889 '1: yes 0: no', VALUE_OPTIONAL),
aff24313 890 'lang' => new external_value(PARAM_SAFEDIR,
6bb31e40 891 'forced course language', VALUE_OPTIONAL),
aff24313 892 'forcetheme' => new external_value(PARAM_PLUGIN,
6bb31e40 893 'name of the force theme', VALUE_OPTIONAL),
894 )
895 ), 'courses to create'
896 )
897 )
898 );
899 }
900
901 /**
902 * Create courses
4615817d 903 *
6bb31e40 904 * @param array $courses
905 * @return array courses (id and shortname only)
4615817d 906 * @since Moodle 2.2
6bb31e40 907 */
908 public static function create_courses($courses) {
909 global $CFG, $DB;
910 require_once($CFG->dirroot . "/course/lib.php");
911 require_once($CFG->libdir . '/completionlib.php');
912
6bb31e40 913 $params = self::validate_parameters(self::create_courses_parameters(),
914 array('courses' => $courses));
915
916 $availablethemes = get_plugin_list('theme');
917 $availablelangs = get_string_manager()->get_list_of_translations();
918
919 $transaction = $DB->start_delegated_transaction();
920
921 foreach ($params['courses'] as $course) {
922
923 // Ensure the current user is allowed to run this function
924 $context = get_context_instance(CONTEXT_COURSECAT, $course['categoryid']);
925 try {
926 self::validate_context($context);
927 } catch (Exception $e) {
928 $exceptionparam = new stdClass();
929 $exceptionparam->message = $e->getMessage();
930 $exceptionparam->catid = $course['categoryid'];
931 throw new moodle_exception(
932 get_string('errorcatcontextnotvalid', 'webservice', $exceptionparam));
933 }
934 require_capability('moodle/course:create', $context);
935
936 // Make sure lang is valid
937 if (key_exists('lang', $course) and empty($availablelangs[$course['lang']])) {
938 throw new moodle_exception(
939 get_string('errorinvalidparam', 'webservice', 'lang'));
940 }
941
942 // Make sure theme is valid
943 if (key_exists('forcetheme', $course)) {
944 if (!empty($CFG->allowcoursethemes)) {
945 if (empty($availablethemes[$course['forcetheme']])) {
946 throw new moodle_exception(
947 get_string('errorinvalidparam', 'webservice', 'forcetheme'));
948 } else {
949 $course['theme'] = $course['forcetheme'];
950 }
951 }
952 }
953
954 //force visibility if ws user doesn't have the permission to set it
955 $category = $DB->get_record('course_categories', array('id' => $course['categoryid']));
956 if (!has_capability('moodle/course:visibility', $context)) {
957 $course['visible'] = $category->visible;
958 }
959
960 //set default value for completion
8a6b1193 961 $courseconfig = get_config('moodlecourse');
6bb31e40 962 if (completion_info::is_enabled_for_site()) {
963 if (!key_exists('enablecompletion', $course)) {
8a6b1193 964 $course['enablecompletion'] = $courseconfig->enablecompletion;
6bb31e40 965 }
966 if (!key_exists('completionstartonenrol', $course)) {
8a6b1193 967 $course['completionstartonenrol'] = $courseconfig->completionstartonenrol;
6bb31e40 968 }
969 } else {
970 $course['enablecompletion'] = 0;
971 $course['completionstartonenrol'] = 0;
972 }
973
974 $course['category'] = $course['categoryid'];
975
976 //Note: create_course() core function check shortname, idnumber, category
977 $course['id'] = create_course((object) $course)->id;
978
979 $resultcourses[] = array('id' => $course['id'], 'shortname' => $course['shortname']);
980 }
981
982 $transaction->allow_commit();
983
984 return $resultcourses;
985 }
986
987 /**
988 * Returns description of method result value
4615817d 989 *
6bb31e40 990 * @return external_description
4615817d 991 * @since Moodle 2.2
6bb31e40 992 */
993 public static function create_courses_returns() {
994 return new external_multiple_structure(
995 new external_single_structure(
996 array(
997 'id' => new external_value(PARAM_INT, 'course id'),
998 'shortname' => new external_value(PARAM_TEXT, 'short name'),
999 )
1000 )
1001 );
1002 }
1003
63a85dc7
JL
1004 /**
1005 * Returns description of method parameters
1006 * @return external_function_parameters
1007 */
1008 public static function delete_courses_parameters() {
1009 return new external_function_parameters(
1010 array(
1011 'courseids' => new external_multiple_structure(new external_value(PARAM_INT, 'course ID')),
1012 )
1013 );
1014 }
1015
1016 /**
1017 * Delete courses
1018 * @param array $courseids A list of course ids
1019 */
1020 public static function delete_courses($courseids) {
1021 global $CFG, $DB;
1022 require_once($CFG->dirroot."/course/lib.php");
1023
1024 // Parameter validation.
1025 $params = self::validate_parameters(self::delete_courses_parameters(), array('courseids'=>$courseids));
1026
1027 $transaction = $DB->start_delegated_transaction();
1028
1029 foreach ($params['courseids'] as $courseid) {
1030 $course = $DB->get_record('course', array('id'=>$courseid), '*', MUST_EXIST);
1031
1032 // Check if the context is valid.
1033 $coursecontext = context_course::instance($course->id);
1034 self::validate_context($coursecontext);
1035
1036 // Check if the current user has enought permissions.
1037 if (!can_delete_course($courseid)) {
d6ebe011
JM
1038 throw new moodle_exception('cannotdeletecategorycourse', 'error',
1039 '', format_string($course->fullname)." (id: $courseid)");
63a85dc7
JL
1040 }
1041
1042 delete_course($course, false);
1043 }
1044
1045 $transaction->allow_commit();
1046
1047 return null;
1048 }
1049
1050 /**
1051 * Returns description of method result value
1052 * @return external_description
1053 */
1054 public static function delete_courses_returns() {
1055 return null;
1056 }
1057
3dc1d76e
JL
1058 /**
1059 * Returns description of method parameters
1060 *
1061 * @return external_function_parameters
1062 * @since Moodle 2.3
1063 */
1064 public static function duplicate_course_parameters() {
1065 return new external_function_parameters(
1066 array(
1067 'courseid' => new external_value(PARAM_INT, 'course to duplicate id'),
1068 'fullname' => new external_value(PARAM_TEXT, 'duplicated course full name'),
1069 'shortname' => new external_value(PARAM_TEXT, 'duplicated course short name'),
1070 'categoryid' => new external_value(PARAM_INT, 'duplicated course category parent'),
1071 'visible' => new external_value(PARAM_INT, 'duplicated course visible, default to yes', VALUE_DEFAULT, 1),
1072 'options' => new external_multiple_structure(
1073 new external_single_structure(
1074 array(
9aa84e91
JL
1075 'name' => new external_value(PARAM_ALPHA, 'The backup option name:
1076 "activities" (int) Include course activites (default to 1 that is equal to yes),
1077 "blocks" (int) Include course blocks (default to 1 that is equal to yes),
1078 "filters" (int) Include course filters (default to 1 that is equal to yes),
1079 "users" (int) Include users (default to 0 that is equal to no),
1080 "role_assignments" (int) Include role assignments (default to 0 that is equal to no),
1081 "user_files" (int) Include user files (default to 0 that is equal to no),
1082 "comments" (int) Include user comments (default to 0 that is equal to no),
1083 "completion_information" (int) Include user course completion information (default to 0 that is equal to no),
1084 "logs" (int) Include course logs (default to 0 that is equal to no),
1085 "histories" (int) Include histories (default to 0 that is equal to no)'
1086 ),
1087 'value' => new external_value(PARAM_RAW, 'the value for the option 1 (yes) or 0 (no)'
1088 )
3dc1d76e
JL
1089 )
1090 ), VALUE_DEFAULT, array()
1091 ),
1092 )
1093 );
1094 }
1095
1096 /**
1097 * Duplicate a course
1098 *
1099 * @param int $courseid
1100 * @param string $fullname Duplicated course fullname
1101 * @param string $shortname Duplicated course shortname
1102 * @param int $categoryid Duplicated course parent category id
1103 * @param int $visible Duplicated course availability
1104 * @param array $options List of backup options
1105 * @return array New course info
1106 * @since Moodle 2.3
1107 */
1108 public static function duplicate_course($courseid, $fullname, $shortname, $categoryid, $visible, $options) {
1109 global $CFG, $USER, $DB;
1110 require_once($CFG->dirroot . '/backup/util/includes/backup_includes.php');
1111 require_once($CFG->dirroot . '/backup/util/includes/restore_includes.php');
1112
1113 // Parameter validation.
1114 $params = self::validate_parameters(
1115 self::duplicate_course_parameters(),
1116 array(
1117 'courseid' => $courseid,
1118 'fullname' => $fullname,
1119 'shortname' => $shortname,
1120 'categoryid' => $categoryid,
1121 'visible' => $visible,
1122 'options' => $options
1123 )
1124 );
1125
1126 // Context validation.
1127
1128 if (! ($course = $DB->get_record('course', array('id'=>$params['courseid'])))) {
1129 throw new moodle_exception('invalidcourseid', 'error', '', $params['courseid']);
1130 }
1131
1132 // Category where duplicated course is going to be created.
1133 $categorycontext = context_coursecat::instance($params['categoryid']);
1134 self::validate_context($categorycontext);
1135
1136 // Course to be duplicated.
1137 $coursecontext = context_course::instance($course->id);
1138 self::validate_context($coursecontext);
1139
9aa84e91 1140 $backupdefaults = array(
d7f465d4
JL
1141 'activities' => 1,
1142 'blocks' => 1,
1143 'filters' => 1,
1144 'users' => 0,
1145 'role_assignments' => 0,
1146 'user_files' => 0,
1147 'comments' => 0,
1148 'completion_information' => 0,
1149 'logs' => 0,
1150 'histories' => 0
9aa84e91
JL
1151 );
1152
1153 $backupsettings = array();
1154 // Check for backup and restore options.
1155 if (!empty($params['options'])) {
1156 foreach ($params['options'] as $option) {
1157
1158 // Strict check for a correct value (allways 1 or 0, true or false).
1159 $value = clean_param($option['value'], PARAM_INT);
1160
1161 if ($value !== 0 and $value !== 1) {
1162 throw new moodle_exception('invalidextparam', 'webservice', '', $option['name']);
1163 }
1164
1165 if (!isset($backupdefaults[$option['name']])) {
1166 throw new moodle_exception('invalidextparam', 'webservice', '', $option['name']);
1167 }
1168
1169 $backupsettings[$option['name']] = $value;
1170 }
1171 }
1172
3dc1d76e
JL
1173 // Capability checking.
1174
1175 // The backup controller check for this currently, this may be redundant.
1176 require_capability('moodle/course:create', $categorycontext);
1177 require_capability('moodle/restore:restorecourse', $categorycontext);
3dc1d76e 1178 require_capability('moodle/backup:backupcourse', $coursecontext);
3dc1d76e 1179
9aa84e91
JL
1180 if (!empty($backupsettings['users'])) {
1181 require_capability('moodle/backup:userinfo', $coursecontext);
1182 require_capability('moodle/restore:userinfo', $categorycontext);
1183 }
1184
3dc1d76e
JL
1185 // Check if the shortname is used.
1186 if ($foundcourses = $DB->get_records('course', array('shortname'=>$shortname))) {
1187 foreach ($foundcourses as $foundcourse) {
1188 $foundcoursenames[] = $foundcourse->fullname;
1189 }
1190
1191 $foundcoursenamestring = implode(',', $foundcoursenames);
1192 throw new moodle_exception('shortnametaken', '', '', $foundcoursenamestring);
1193 }
1194
9aa84e91 1195 // Backup the course.
3dc1d76e 1196
3dc1d76e 1197 $bc = new backup_controller(backup::TYPE_1COURSE, $course->id, backup::FORMAT_MOODLE,
d7f465d4 1198 backup::INTERACTIVE_NO, backup::MODE_SAMESITE, $USER->id);
3dc1d76e
JL
1199
1200 foreach ($backupsettings as $name => $value) {
1201 $bc->get_plan()->get_setting($name)->set_value($value);
1202 }
1203
1204 $backupid = $bc->get_backupid();
1205 $backupbasepath = $bc->get_plan()->get_basepath();
1206
1207 $bc->execute_plan();
9aa84e91 1208 $results = $bc->get_results();
d7f465d4 1209 $file = $results['backup_destination'];
6c7d3e31 1210
3dc1d76e
JL
1211 $bc->destroy();
1212
1213 // Restore the backup immediately.
1214
6c7d3e31 1215 // Check if we need to unzip the file because the backup temp dir does not contains backup files.
d7f465d4 1216 if (!file_exists($backupbasepath . "/moodle_backup.xml")) {
6c7d3e31 1217 $file->extract_to_pathname(get_file_packer(), $backupbasepath);
9aa84e91
JL
1218 }
1219
3dc1d76e
JL
1220 // Create new course.
1221 $newcourseid = restore_dbops::create_new_course($params['fullname'], $params['shortname'], $params['categoryid']);
1222
1223 $rc = new restore_controller($backupid, $newcourseid,
d7f465d4 1224 backup::INTERACTIVE_NO, backup::MODE_SAMESITE, $USER->id, backup::TARGET_NEW_COURSE);
3dc1d76e
JL
1225
1226 foreach ($backupsettings as $name => $value) {
9aa84e91
JL
1227 $setting = $rc->get_plan()->get_setting($name);
1228 if ($setting->get_status() == backup_setting::NOT_LOCKED) {
1229 $setting->set_value($value);
1230 }
3dc1d76e
JL
1231 }
1232
1233 if (!$rc->execute_precheck()) {
1234 $precheckresults = $rc->get_precheck_results();
1235 if (is_array($precheckresults) && !empty($precheckresults['errors'])) {
1236 if (empty($CFG->keeptempdirectoriesonbackup)) {
1237 fulldelete($backupbasepath);
1238 }
1239
1240 $errorinfo = '';
1241
1242 foreach ($precheckresults['errors'] as $error) {
1243 $errorinfo .= $error;
1244 }
1245
1246 if (array_key_exists('warnings', $precheckresults)) {
1247 foreach ($precheckresults['warnings'] as $warning) {
1248 $errorinfo .= $warning;
1249 }
1250 }
1251
1252 throw new moodle_exception('backupprecheckerrors', 'webservice', '', $errorinfo);
1253 }
1254 }
1255
1256 $rc->execute_plan();
1257 $rc->destroy();
1258
1259 $course = $DB->get_record('course', array('id' => $newcourseid), '*', MUST_EXIST);
1260 $course->fullname = $params['fullname'];
1261 $course->shortname = $params['shortname'];
1262 $course->visible = $params['visible'];
1263
1264 // Set shortname and fullname back.
1265 $DB->update_record('course', $course);
1266
1267 if (empty($CFG->keeptempdirectoriesonbackup)) {
1268 fulldelete($backupbasepath);
1269 }
1270
d7f465d4
JL
1271 // Delete the course backup file created by this WebService. Originally located in the course backups area.
1272 $file->delete();
6c7d3e31 1273
3dc1d76e
JL
1274 return array('id' => $course->id, 'shortname' => $course->shortname);
1275 }
1276
1277 /**
1278 * Returns description of method result value
1279 *
1280 * @return external_description
1281 * @since Moodle 2.3
1282 */
1283 public static function duplicate_course_returns() {
1284 return new external_single_structure(
1285 array(
1286 'id' => new external_value(PARAM_INT, 'course id'),
1287 'shortname' => new external_value(PARAM_TEXT, 'short name'),
1288 )
1289 );
1290 }
1291
2f951d86
FS
1292 /**
1293 * Returns description of method parameters
1294 * @return external_function_parameters
1295 * @since Moodle 2.3
1296 */
1297 public static function delete_categories_parameters() {
1298 return new external_function_parameters(
1299 array(
1300 'categories' => new external_multiple_structure(
1301 new external_single_structure(
1302 array(
1303 'id' => new external_value(PARAM_INT, 'category id to delete'),
1304 'newparent' => new external_value(PARAM_INT,
1305 'the parent category to move the contents to, if specified', VALUE_OPTIONAL),
1306 'recursive' => new external_value(PARAM_BOOL, '1: recursively delete all contents inside this
1307 category, 0 (default): move contents to newparent or current parent category (except if parent is root)', VALUE_DEFAULT, 0)
1308 )
1309 )
1310 )
1311 )
1312 );
1313 }
1314
1315 /**
1316 * Delete categories
1317 * @param array $categories A list of category ids
1318 * @return array
1319 * @since Moodle 2.3
1320 */
1321 public static function delete_categories($categories) {
1322 global $CFG, $DB;
1323 require_once($CFG->dirroot . "/course/lib.php");
1324
1325 // Validate parameters.
1326 $params = self::validate_parameters(self::delete_categories_parameters(), array('categories' => $categories));
1327
1328 foreach ($params['categories'] as $category) {
1329 if (!$deletecat = $DB->get_record('course_categories', array('id' => $category['id']))) {
1330 throw new moodle_exception('unknowcategory');
1331 }
1332 $context = context_coursecat::instance($deletecat->id);
1333 require_capability('moodle/category:manage', $context);
1334 self::validate_context($context);
1335 self::validate_context(get_category_or_system_context($deletecat->parent));
1336
1337 if ($category['recursive']) {
1338 // If recursive was specified, then we recursively delete the category's contents.
1339 category_delete_full($deletecat, false);
1340 } else {
1341 // In this situation, we don't delete the category's contents, we either move it to newparent or parent.
1342 // If the parent is the root, moving is not supported (because a course must always be inside a category).
1343 // We must move to an existing category.
1344 if (!empty($category['newparent'])) {
1345 if (!$DB->record_exists('course_categories', array('id' => $category['newparent']))) {
1346 throw new moodle_exception('unknowcategory');
1347 }
1348 $newparent = $category['newparent'];
1349 } else {
1350 $newparent = $deletecat->parent;
1351 }
1352
1353 // This operation is not allowed. We must move contents to an existing category.
1354 if ($newparent == 0) {
1355 throw new moodle_exception('movecatcontentstoroot');
1356 }
1357
1358 $parentcontext = get_category_or_system_context($newparent);
1359 require_capability('moodle/category:manage', $parentcontext);
1360 self::validate_context($parentcontext);
1361 category_delete_move($deletecat, $newparent, false);
1362 }
1363 }
1364
1365 }
1366
1367 /**
1368 * Returns description of method parameters
1369 * @return external_function_parameters
1370 * @since Moodle 2.3
1371 */
1372 public static function delete_categories_returns() {
1373 return null;
1374 }
f2229c68
FS
1375
1376 /**
1377 * Returns description of method parameters
1378 * @return external_function_parameters
1379 * @since Moodle 2.3
1380 */
1381 public static function update_categories_parameters() {
1382 return new external_function_parameters(
1383 array(
1384 'categories' => new external_multiple_structure(
1385 new external_single_structure(
1386 array(
1387 'id' => new external_value(PARAM_INT, 'course id'),
1388 'name' => new external_value(PARAM_TEXT, 'category name', VALUE_OPTIONAL),
1389 'idnumber' => new external_value(PARAM_RAW, 'category id number', VALUE_OPTIONAL),
1390 'parent' => new external_value(PARAM_INT, 'parent category id', VALUE_OPTIONAL),
1391 'description' => new external_value(PARAM_RAW, 'category description', VALUE_OPTIONAL),
1392 'theme' => new external_value(PARAM_THEME,
1393 'the category theme. This option must be enabled on moodle', VALUE_OPTIONAL),
1394 )
1395 )
1396 )
1397 )
1398 );
1399 }
1400
1401 /**
1402 * Update categories
1403 * @param array $categories The list of categories to update
1404 * @return null
1405 * @since Moodle 2.3
1406 */
1407 public static function update_categories($categories) {
1408 global $CFG, $DB;
1409 require_once($CFG->dirroot . "/course/lib.php");
1410
1411 // Validate parameters.
1412 $params = self::validate_parameters(self::update_categories_parameters(), array('categories' => $categories));
1413
1414 $transaction = $DB->start_delegated_transaction();
1415
1416 foreach ($params['categories'] as $cat) {
1417 if (!$category = $DB->get_record('course_categories', array('id' => $cat['id']))) {
1418 throw new moodle_exception('unknowcategory');
1419 }
1420
1421 $categorycontext = context_coursecat::instance($cat['id']);
1422 self::validate_context($categorycontext);
1423 require_capability('moodle/category:manage', $categorycontext);
1424
1425 if (!empty($cat['name'])) {
d7238d08 1426 if (textlib::strlen($cat['name'])>255) {
f2229c68
FS
1427 throw new moodle_exception('categorytoolong');
1428 }
1429 $category->name = $cat['name'];
1430 }
1431 if (!empty($cat['idnumber'])) {
1432 if (textlib::strlen($cat['idnumber'])>100) {
1433 throw new moodle_exception('idnumbertoolong');
1434 }
1435 $category->idnumber = $cat['idnumber'];
1436 }
1437 if (!empty($cat['description'])) {
1438 $category->description = $cat['description'];
1439 $category->descriptionformat = FORMAT_HTML;
1440 }
1441 if (!empty($cat['theme'])) {
1442 $category->theme = $cat['theme'];
1443 }
1444 if (!empty($cat['parent']) && ($category->parent != $cat['parent'])) {
1445 // First check if parent exists.
1446 if (!$parent_cat = $DB->get_record('course_categories', array('id' => $cat['parent']))) {
1447 throw new moodle_exception('unknowcategory');
1448 }
1449 // Then check if we have capability.
1450 self::validate_context(get_category_or_system_context((int)$cat['parent']));
1451 require_capability('moodle/category:manage', get_category_or_system_context((int)$cat['parent']));
1452 // Finally move the category.
1453 move_category($category, $parent_cat);
1454 $category->parent = $cat['parent'];
1455 }
1456 $DB->update_record('course_categories', $category);
1457 }
1458
1459 $transaction->allow_commit();
1460 }
1461
1462 /**
1463 * Returns description of method result value
1464 * @return external_description
1465 */
1466 public static function update_categories_returns() {
1467 return null;
1468 }
5d1017e1
JM
1469}
1470
1471/**
4615817d
JM
1472 * Deprecated course external functions
1473 *
1474 * @package core_course
1475 * @copyright 2009 Petr Skodak
1476 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1477 * @since Moodle 2.0
1478 * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
1479 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1480 * @see core_course_external
5d1017e1
JM
1481 */
1482class moodle_course_external extends external_api {
1483
1484 /**
1485 * Returns description of method parameters
4615817d 1486 *
5d1017e1 1487 * @return external_function_parameters
4615817d
JM
1488 * @since Moodle 2.0
1489 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1490 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1491 * @see core_course_external::get_courses_parameters()
5d1017e1
JM
1492 */
1493 public static function get_courses_parameters() {
1494 return core_course_external::get_courses_parameters();
1495 }
1496
1497 /**
1498 * Get courses
4615817d 1499 *
5d1017e1 1500 * @param array $options
5d1017e1 1501 * @return array
4615817d
JM
1502 * @since Moodle 2.0
1503 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1504 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1505 * @see core_course_external::get_courses()
5d1017e1
JM
1506 */
1507 public static function get_courses($options) {
1508 return core_course_external::get_courses($options);
1509 }
1510
1511 /**
1512 * Returns description of method result value
4615817d 1513 *
5d1017e1 1514 * @return external_description
4615817d
JM
1515 * @since Moodle 2.0
1516 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1517 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1518 * @see core_course_external::get_courses_returns()
5d1017e1
JM
1519 */
1520 public static function get_courses_returns() {
1521 return core_course_external::get_courses_returns();
1522 }
1523
1524 /**
1525 * Returns description of method parameters
4615817d 1526 *
5d1017e1 1527 * @return external_function_parameters
4615817d
JM
1528 * @since Moodle 2.0
1529 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1530 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1531 * @see core_course_external::create_courses_parameters()
5d1017e1
JM
1532 */
1533 public static function create_courses_parameters() {
1534 return core_course_external::create_courses_parameters();
1535 }
1536
1537 /**
1538 * Create courses
4615817d 1539 *
5d1017e1
JM
1540 * @param array $courses
1541 * @return array courses (id and shortname only)
4615817d
JM
1542 * @since Moodle 2.0
1543 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1544 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1545 * @see core_course_external::create_courses()
5d1017e1
JM
1546 */
1547 public static function create_courses($courses) {
1548 return core_course_external::create_courses($courses);
1549 }
1550
1551 /**
1552 * Returns description of method result value
4615817d 1553 *
5d1017e1 1554 * @return external_description
4615817d
JM
1555 * @since Moodle 2.0
1556 * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
1557 * @todo MDL-31194 This will be deleted in Moodle 2.5.
1558 * @see core_course_external::create_courses_returns()
5d1017e1
JM
1559 */
1560 public static function create_courses_returns() {
1561 return core_course_external::create_courses_returns();
1562 }
1563
ec0d6ea2 1564}