dc2f7254ac39ce9125c24dd2ffbc55c29f043980
[moodle.git] / course / externallib.php
1 <?php
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/>.
18 /**
19  * External course API
20  *
21  * @package    core_course
22  * @category   external
23  * @copyright  2009 Petr Skodak
24  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25  */
27 defined('MOODLE_INTERNAL') || die;
29 require_once("$CFG->libdir/externallib.php");
31 /**
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
39  */
40 class core_course_external extends external_api {
42     /**
43      * Returns description of method parameters
44      *
45      * @return external_function_parameters
46      * @since Moodle 2.2
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     }
61     /**
62      * Get course contents
63      *
64      * @param int $courseid course id
65      * @param array $options These options are not used yet, might be used in later version
66      * @return array
67      * @since Moodle 2.2
68      */
69     public static function get_course_contents($courseid, $options) {
70         global $CFG, $DB;
71         require_once($CFG->dirroot . "/course/lib.php");
73         //validate parameter
74         $params = self::validate_parameters(self::get_course_contents_parameters(),
75                         array('courseid' => $courseid, 'options' => $options));
77         //retrieve the course
78         $course = $DB->get_record('course', array('id' => $params['courseid']), '*', MUST_EXIST);
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         }
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         }
98         $canupdatecourse = has_capability('moodle/course:update', $context);
100         //create return value
101         $coursecontents = array();
103         if ($canupdatecourse or $course->visible
104                 or has_capability('moodle/course:viewhiddencourses', $context)) {
106             //retrieve sections
107             $modinfo = get_fast_modinfo($course);
108             $sections = get_all_sections($course->id);
110             //for each sections (first displayed to last displayed)
111             foreach ($sections as $key => $section) {
113                 $showsection = (has_capability('moodle/course:viewhiddensections', $context) or $section->visible or !$course->hiddensections);
114                 if (!$showsection) {
115                     continue;
116                 }
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();
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];
131                     // stop here if the module is not visible to the user
132                     if (!$cm->uservisible) {
133                         continue;
134                     }
136                     $module = array();
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;
146                     $modcontext = get_context_instance(CONTEXT_MODULE, $cm->id);
148                     if (!empty($cm->showdescription)) {
149                         $module['description'] = $cm->get_content();
150                     }
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                     }
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;
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                     }
169                     $baseurl = 'webservice/pluginfile.php';
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                     }
181                     //assign result to $sectioncontents
182                     $sectioncontents[] = $module;
184                 }
185                 $sectionvalues['modules'] = $sectioncontents;
187                 // assign result to $coursecontents
188                 $coursecontents[] = $sectionvalues;
189             }
190         }
191         return $coursecontents;
192     }
194     /**
195      * Returns description of method result value
196      *
197      * @return external_description
198      * @since Moodle 2.2
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'),
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     }
251     /**
252      * Returns description of method parameters
253      *
254      * @return external_function_parameters
255      * @since Moodle 2.3
256      */
257     public static function get_categories_parameters() {
258         return new external_function_parameters(
259             array(
260                 'criteria' => new external_multiple_structure(
261                     new external_single_structure(
262                         array(
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'),
274                             'value' => new external_value(PARAM_RAW, 'the value to match')
275                         )
276                     ), VALUE_DEFAULT, array()
277                 ),
278                 'addsubcategories' => new external_value(PARAM_BOOL, 'return the sub categories infos
279                                           (1 - default) otherwise only the category info (0)', VALUE_DEFAULT, 1)
280             )
281         );
282     }
284     /**
285      * Get categories
286      *
287      * @param array $criteria Criteria to match the results
288      * @param booln $addsubcategories obtain only the category (false) or its subcategories (true - default)
289      * @return array list of categories
290      * @since Moodle 2.3
291      */
292     public static function get_categories($criteria = array(), $addsubcategories = true) {
293         global $CFG, $DB;
294         require_once($CFG->dirroot . "/course/lib.php");
296         // Validate parameters.
297         $params = self::validate_parameters(self::get_categories_parameters(),
298                 array('criteria' => $criteria, 'addsubcategories' => $addsubcategories));
300         // Retrieve the categories.
301         $categories = array();
302         if (!empty($params['criteria'])) {
304             $conditions = array();
305             $wheres = array();
306             foreach ($params['criteria'] as $crit) {
307                 $key = trim($crit['key']);
309                 // Trying to avoid duplicate keys.
310                 if (!isset($conditions[$key])) {
312                     $context = context_system::instance();
313                     $value = null;
314                     switch ($key) {
315                         case 'id':
316                             $value = clean_param($crit['value'], PARAM_INT);
317                             break;
319                         case 'idnumber':
320                             if (has_capability('moodle/category:manage', $context)) {
321                                 $value = clean_param($crit['value'], PARAM_RAW);
322                             } else {
323                                 // We must throw an exception.
324                                 // Otherwise the dev client would think no idnumber exists.
325                                 throw new moodle_exception('criteriaerror',
326                                         'webservice', '', null,
327                                         'You don\'t have the permissions to search on the "idnumber" field.');
328                             }
329                             break;
331                         case 'name':
332                             $value = clean_param($crit['value'], PARAM_TEXT);
333                             break;
335                         case 'parent':
336                             $value = clean_param($crit['value'], PARAM_INT);
337                             break;
339                         case 'visible':
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 {
345                                 throw new moodle_exception('criteriaerror',
346                                         'webservice', '', null,
347                                         'You don\'t have the permissions to search on the "visible" field.');
348                             }
349                             break;
351                         case 'theme':
352                             if (has_capability('moodle/category:manage', $context)) {
353                                 $value = clean_param($crit['value'], PARAM_THEME);
354                             } else {
355                                 throw new moodle_exception('criteriaerror',
356                                         'webservice', '', null,
357                                         'You don\'t have the permissions to search on the "theme" field.');
358                             }
359                             break;
361                         default:
362                             throw new moodle_exception('criteriaerror',
363                                     'webservice', '', null,
364                                     'You can not search on this criteria: ' . $key);
365                     }
367                     if (isset($value)) {
368                         $conditions[$key] = $crit['value'];
369                         $wheres[] = $key . " = :" . $key;
370                     }
371                 }
372             }
374             if (!empty($wheres)) {
375                 $wheres = implode(" AND ", $wheres);
377                 $categories = $DB->get_records_select('course_categories', $wheres, $conditions);
379                 // Retrieve its sub subcategories (all levels).
380                 if ($categories and !empty($params['addsubcategories'])) {
381                     $newcategories = array();
383                     foreach ($categories as $category) {
384                         $sqllike = $DB->sql_like('path', ':path');
385                         $sqlparams = array('path' => $category->path.'/%'); // It will NOT include the specified category.
386                         $subcategories = $DB->get_records_select('course_categories', $sqllike, $sqlparams);
387                         $newcategories = $newcategories + $subcategories;   // Both arrays have integer as keys.
388                     }
389                     $categories = $categories + $newcategories;
390                 }
391             }
393         } else {
394             // Retrieve all categories in the database.
395             $categories = $DB->get_records('course_categories');
396         }
398         // The not returned categories. key => category id, value => reason of exclusion.
399         $excludedcats = array();
401         // The returned categories.
402         $categoriesinfo = array();
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");
408         foreach ($categories as $category) {
410             // Check if the category is a child of an excluded category, if yes exclude it too (excluded => do not return).
411             $parents = explode('/', $category->path);
412             unset($parents[0]); // First key is always empty because path start with / => /1/2/4.
413             foreach ($parents as $parentid) {
414                 // Note: when the parent exclusion was due to the context,
415                 // the sub category could still be returned.
416                 if (isset($excludedcats[$parentid]) and $excludedcats[$parentid] != 'context') {
417                     $excludedcats[$category->id] = 'parent';
418                 }
419             }
421             // Check category depth is <= maxdepth (do not check for user who can manage categories).
422             if ((!empty($CFG->maxcategorydepth) && count($parents) > $CFG->maxcategorydepth)
423                     and !has_capability('moodle/category:manage', $context)) {
424                 $excludedcats[$category->id] = 'depth';
425             }
427             // Check the user can use the category context.
428             $context = context_coursecat::instance($category->id);
429             try {
430                 self::validate_context($context);
431             } catch (Exception $e) {
432                 $excludedcats[$category->id] = 'context';
434                 // If it was the requested category then throw an exception.
435                 if (isset($params['categoryid']) && $category->id == $params['categoryid']) {
436                     $exceptionparam = new stdClass();
437                     $exceptionparam->message = $e->getMessage();
438                     $exceptionparam->catid = $category->id;
439                     throw new moodle_exception('errorcatcontextnotvalid', 'webservice', '', $exceptionparam);
440                 }
441             }
443             // Return the category information.
444             if (!isset($excludedcats[$category->id])) {
446                 // Final check to see if the category is visible to the user.
447                 if ($category->visible
448                         or has_capability('moodle/category:viewhiddencategories', context_system::instance())
449                         or has_capability('moodle/category:manage', $context)) {
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;
467                     // Some fields only returned for admin.
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                     }
476                     $categoriesinfo[] = $categoryinfo;
477                 } else {
478                     $excludedcats[$category->id] = 'visibility';
479                 }
480             }
481         }
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");
486         return $categoriesinfo;
487     }
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      */
498     private static function compare_categories_by_path($category1, $category2) {
499         return strcmp($category1->path, $category2->path);
500     }
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      */
511     private static function compare_categories_by_sortorder($category1, $category2) {
512         return strcmp($category1['sortorder'], $category2['sortorder']);
513     }
515     /**
516      * Returns description of method result value
517      *
518      * @return external_description
519      * @since Moodle 2.3
520      */
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),
528                     'description' => new external_value(PARAM_RAW, 'category description'),
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),
538                 ), 'List of categories'
539             )
540         );
541     }
543     /**
544      * Returns description of method parameters
545      *
546      * @return external_function_parameters
547      * @since Moodle 2.2
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     }
562     /**
563      * Get courses
564      *
565      * @param array $options It contains an array (list of ids)
566      * @return array
567      * @since Moodle 2.2
568      */
569     public static function get_courses($options) {
570         global $CFG, $DB;
571         require_once($CFG->dirroot . "/course/lib.php");
573         //validate parameter
574         $params = self::validate_parameters(self::get_courses_parameters(),
575                         array('options' => $options));
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         }
585         //create return value
586         $coursesinfo = array();
587         foreach ($courses as $course) {
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);
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;
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             }
636             if ($courseadmin or $course->visible
637                     or has_capability('moodle/course:viewhiddencourses', $context)) {
638                 $coursesinfo[] = $courseinfo;
639             }
640         }
642         return $coursesinfo;
643     }
645     /**
646      * Returns description of method result value
647      *
648      * @return external_description
649      * @since Moodle 2.2
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'),
665                             'format' => new external_value(PARAM_PLUGIN,
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),
704                             'lang' => new external_value(PARAM_SAFEDIR,
705                                     'forced course language', VALUE_OPTIONAL),
706                             'forcetheme' => new external_value(PARAM_PLUGIN,
707                                     'name of the force theme', VALUE_OPTIONAL),
708                         ), 'course'
709                 )
710         );
711     }
713     /**
714      * Returns description of method parameters
715      *
716      * @return external_function_parameters
717      * @since Moodle 2.3
718      */
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'),
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),
732                                 'theme' => new external_value(PARAM_THEME,
733                                         'the new category theme. This option must be enabled on moodle',
734                                         VALUE_OPTIONAL),
735                         )
736                     )
737                 )
738             )
739         );
740     }
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
748      */
749     public static function create_categories($categories) {
750         global $CFG, $DB;
751         require_once($CFG->dirroot . "/course/lib.php");
753         $params = self::validate_parameters(self::create_categories_parameters(),
754                         array('categories' => $categories));
756         $transaction = $DB->start_delegated_transaction();
758         $createdcategories = array();
759         foreach ($params['categories'] as $category) {
760             if ($category['parent']) {
761                 if (!$DB->record_exists('course_categories', array('id' => $category['parent']))) {
762                     throw new moodle_exception('unknowcategory');
763                 }
764                 $context = context_coursecat::instance($category['parent']);
765             } else {
766                 $context = context_system::instance();
767             }
768             self::validate_context($context);
769             require_capability('moodle/category:manage', $context);
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                 }
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             }
782             // Check name.
783             if (textlib::strlen($category['name'])>255) {
784                 throw new moodle_exception('categorytoolong');
785             }
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'];
795             }
796             $newcategory->descriptionformat = FORMAT_HTML;
797             if (isset($category['theme']) and !empty($CFG->allowcategorythemes)) {
798                 $newcategory->theme = $category['theme'];
799             }
801             $newcategory = create_course_category($newcategory);
802             // Populate special fields.
803             fix_course_sortorder();
805             $createdcategories[] = array('id' => $newcategory->id, 'name' => $newcategory->name);
806         }
808         $transaction->allow_commit();
810         return $createdcategories;
811     }
813     /**
814      * Returns description of method parameters
815      *
816      * @return external_function_parameters
817      * @since Moodle 2.3
818      */
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     }
830     /**
831      * Returns description of method parameters
832      *
833      * @return external_function_parameters
834      * @since Moodle 2.2
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),
850                             'format' => new external_value(PARAM_PLUGIN,
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,
881                                     'Enabled, control via completion and activity settings. Disabled,
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),
890                             'lang' => new external_value(PARAM_SAFEDIR,
891                                     'forced course language', VALUE_OPTIONAL),
892                             'forcetheme' => new external_value(PARAM_PLUGIN,
893                                     'name of the force theme', VALUE_OPTIONAL),
894                         )
895                     ), 'courses to create'
896                 )
897             )
898         );
899     }
901     /**
902      * Create  courses
903      *
904      * @param array $courses
905      * @return array courses (id and shortname only)
906      * @since Moodle 2.2
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');
913         $params = self::validate_parameters(self::create_courses_parameters(),
914                         array('courses' => $courses));
916         $availablethemes = get_plugin_list('theme');
917         $availablelangs = get_string_manager()->get_list_of_translations();
919         $transaction = $DB->start_delegated_transaction();
921         foreach ($params['courses'] as $course) {
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);
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             }
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             }
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             }
960             //set default value for completion
961             $courseconfig = get_config('moodlecourse');
962             if (completion_info::is_enabled_for_site()) {
963                 if (!key_exists('enablecompletion', $course)) {
964                     $course['enablecompletion'] = $courseconfig->enablecompletion;
965                 }
966                 if (!key_exists('completionstartonenrol', $course)) {
967                     $course['completionstartonenrol'] = $courseconfig->completionstartonenrol;
968                 }
969             } else {
970                 $course['enablecompletion'] = 0;
971                 $course['completionstartonenrol'] = 0;
972             }
974             $course['category'] = $course['categoryid'];
976             //Note: create_course() core function check shortname, idnumber, category
977             $course['id'] = create_course((object) $course)->id;
979             $resultcourses[] = array('id' => $course['id'], 'shortname' => $course['shortname']);
980         }
982         $transaction->allow_commit();
984         return $resultcourses;
985     }
987     /**
988      * Returns description of method result value
989      *
990      * @return external_description
991      * @since Moodle 2.2
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     }
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     }
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");
1024         // Parameter validation.
1025         $params = self::validate_parameters(self::delete_courses_parameters(), array('courseids'=>$courseids));
1027         $transaction = $DB->start_delegated_transaction();
1029         foreach ($params['courseids'] as $courseid) {
1030             $course = $DB->get_record('course', array('id'=>$courseid), '*', MUST_EXIST);
1032             // Check if the context is valid.
1033             $coursecontext = context_course::instance($course->id);
1034             self::validate_context($coursecontext);
1036             // Check if the current user has enought permissions.
1037             if (!can_delete_course($courseid)) {
1038                 throw new moodle_exception('cannotdeletecategorycourse', 'error',
1039                     '', format_string($course->fullname)." (id: $courseid)");
1040             }
1042             delete_course($course, false);
1043         }
1045         $transaction->allow_commit();
1047         return null;
1048     }
1050     /**
1051      * Returns description of method result value
1052      * @return external_description
1053      */
1054     public static function delete_courses_returns() {
1055         return null;
1056     }
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(
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                             )
1089                         )
1090                     ), VALUE_DEFAULT, array()
1091                 ),
1092             )
1093         );
1094     }
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');
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         );
1126         // Context validation.
1128         if (! ($course = $DB->get_record('course', array('id'=>$params['courseid'])))) {
1129             throw new moodle_exception('invalidcourseid', 'error', '', $params['courseid']);
1130         }
1132         // Category where duplicated course is going to be created.
1133         $categorycontext = context_coursecat::instance($params['categoryid']);
1134         self::validate_context($categorycontext);
1136         // Course to be duplicated.
1137         $coursecontext = context_course::instance($course->id);
1138         self::validate_context($coursecontext);
1140         $backupdefaults = array(
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
1151         );
1153         $backupsettings = array();
1154         // Check for backup and restore options.
1155         if (!empty($params['options'])) {
1156             foreach ($params['options'] as $option) {
1158                 // Strict check for a correct value (allways 1 or 0, true or false).
1159                 $value = clean_param($option['value'], PARAM_INT);
1161                 if ($value !== 0 and $value !== 1) {
1162                     throw new moodle_exception('invalidextparam', 'webservice', '', $option['name']);
1163                 }
1165                 if (!isset($backupdefaults[$option['name']])) {
1166                     throw new moodle_exception('invalidextparam', 'webservice', '', $option['name']);
1167                 }
1169                 $backupsettings[$option['name']] = $value;
1170             }
1171         }
1173         // Capability checking.
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);
1178         require_capability('moodle/backup:backupcourse', $coursecontext);
1180         if (!empty($backupsettings['users'])) {
1181             require_capability('moodle/backup:userinfo', $coursecontext);
1182             require_capability('moodle/restore:userinfo', $categorycontext);
1183         }
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             }
1191             $foundcoursenamestring = implode(',', $foundcoursenames);
1192             throw new moodle_exception('shortnametaken', '', '', $foundcoursenamestring);
1193         }
1195         // Backup the course.
1197         $bc = new backup_controller(backup::TYPE_1COURSE, $course->id, backup::FORMAT_MOODLE,
1198         backup::INTERACTIVE_NO, backup::MODE_SAMESITE, $USER->id);
1200         foreach ($backupsettings as $name => $value) {
1201             $bc->get_plan()->get_setting($name)->set_value($value);
1202         }
1204         $backupid       = $bc->get_backupid();
1205         $backupbasepath = $bc->get_plan()->get_basepath();
1207         $bc->execute_plan();
1208         $results = $bc->get_results();
1209         $file = $results['backup_destination'];
1211         $bc->destroy();
1213         // Restore the backup immediately.
1215         // Check if we need to unzip the file because the backup temp dir does not contains backup files.
1216         if (!file_exists($backupbasepath . "/moodle_backup.xml")) {
1217             $file->extract_to_pathname(get_file_packer(), $backupbasepath);
1218         }
1220         // Create new course.
1221         $newcourseid = restore_dbops::create_new_course($params['fullname'], $params['shortname'], $params['categoryid']);
1223         $rc = new restore_controller($backupid, $newcourseid,
1224                 backup::INTERACTIVE_NO, backup::MODE_SAMESITE, $USER->id, backup::TARGET_NEW_COURSE);
1226         foreach ($backupsettings as $name => $value) {
1227             $setting = $rc->get_plan()->get_setting($name);
1228             if ($setting->get_status() == backup_setting::NOT_LOCKED) {
1229                 $setting->set_value($value);
1230             }
1231         }
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                 }
1240                 $errorinfo = '';
1242                 foreach ($precheckresults['errors'] as $error) {
1243                     $errorinfo .= $error;
1244                 }
1246                 if (array_key_exists('warnings', $precheckresults)) {
1247                     foreach ($precheckresults['warnings'] as $warning) {
1248                         $errorinfo .= $warning;
1249                     }
1250                 }
1252                 throw new moodle_exception('backupprecheckerrors', 'webservice', '', $errorinfo);
1253             }
1254         }
1256         $rc->execute_plan();
1257         $rc->destroy();
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'];
1264         // Set shortname and fullname back.
1265         $DB->update_record('course', $course);
1267         if (empty($CFG->keeptempdirectoriesonbackup)) {
1268             fulldelete($backupbasepath);
1269         }
1271         // Delete the course backup file created by this WebService. Originally located in the course backups area.
1272         $file->delete();
1274         return array('id' => $course->id, 'shortname' => $course->shortname);
1275     }
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     }
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     }
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");
1325         // Validate parameters.
1326         $params = self::validate_parameters(self::delete_categories_parameters(), array('categories' => $categories));
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));
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                 }
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                 }
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         }
1365     }
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     }
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     }
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");
1411         // Validate parameters.
1412         $params = self::validate_parameters(self::update_categories_parameters(), array('categories' => $categories));
1414         $transaction = $DB->start_delegated_transaction();
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             }
1421             $categorycontext = context_coursecat::instance($cat['id']);
1422             self::validate_context($categorycontext);
1423             require_capability('moodle/category:manage', $categorycontext);
1425             if (!empty($cat['name'])) {
1426                 if (textlib::strlen($cat['name'])>255) {
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         }
1459         $transaction->allow_commit();
1460     }
1462     /**
1463      * Returns description of method result value
1464      * @return external_description
1465      */
1466     public static function update_categories_returns() {
1467         return null;
1468     }
1471 /**
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
1481  */
1482 class moodle_course_external extends external_api {
1484     /**
1485      * Returns description of method parameters
1486      *
1487      * @return external_function_parameters
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()
1492      */
1493     public static function get_courses_parameters() {
1494         return core_course_external::get_courses_parameters();
1495     }
1497     /**
1498      * Get courses
1499      *
1500      * @param array $options
1501      * @return array
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()
1506      */
1507     public static function get_courses($options) {
1508         return core_course_external::get_courses($options);
1509     }
1511     /**
1512      * Returns description of method result value
1513      *
1514      * @return external_description
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()
1519      */
1520     public static function get_courses_returns() {
1521         return core_course_external::get_courses_returns();
1522     }
1524     /**
1525      * Returns description of method parameters
1526      *
1527      * @return external_function_parameters
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()
1532      */
1533     public static function create_courses_parameters() {
1534         return core_course_external::create_courses_parameters();
1535     }
1537     /**
1538      * Create  courses
1539      *
1540      * @param array $courses
1541      * @return array courses (id and shortname only)
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()
1546      */
1547     public static function create_courses($courses) {
1548         return core_course_external::create_courses($courses);
1549     }
1551     /**
1552      * Returns description of method result value
1553      *
1554      * @return external_description
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()
1559      */
1560     public static function create_courses_returns() {
1561         return core_course_external::create_courses_returns();
1562     }