MDL-51324 forms: Add a new course selector
[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.9 Options available
47      * @since Moodle 2.2
48      */
49     public static function get_course_contents_parameters() {
50         return new external_function_parameters(
51                 array('courseid' => new external_value(PARAM_INT, 'course id'),
52                       'options' => new external_multiple_structure (
53                               new external_single_structure(
54                                 array(
55                                     'name' => new external_value(PARAM_ALPHANUM,
56                                                 'The expected keys (value format) are:
57                                                 excludemodules (bool) Do not return modules, return only the sections structure
58                                                 excludecontents (bool) Do not return module contents (i.e: files inside a resource)
59                                                 sectionid (int) Return only this section
60                                                 sectionnumber (int) Return only this section with number (order)
61                                                 cmid (int) Return only this module information (among the whole sections structure)
62                                                 modname (string) Return only modules with this name "label, forum, etc..."
63                                                 modid (int) Return only the module with this id (to be used with modname'),
64                                     'value' => new external_value(PARAM_RAW, 'the value of the option,
65                                                                     this param is personaly validated in the external function.')
66                               )
67                       ), 'Options, used since Moodle 2.9', VALUE_DEFAULT, array())
68                 )
69         );
70     }
72     /**
73      * Get course contents
74      *
75      * @param int $courseid course id
76      * @param array $options Options for filtering the results, used since Moodle 2.9
77      * @return array
78      * @since Moodle 2.9 Options available
79      * @since Moodle 2.2
80      */
81     public static function get_course_contents($courseid, $options = array()) {
82         global $CFG, $DB;
83         require_once($CFG->dirroot . "/course/lib.php");
85         //validate parameter
86         $params = self::validate_parameters(self::get_course_contents_parameters(),
87                         array('courseid' => $courseid, 'options' => $options));
89         $filters = array();
90         if (!empty($params['options'])) {
92             foreach ($params['options'] as $option) {
93                 $name = trim($option['name']);
94                 // Avoid duplicated options.
95                 if (!isset($filters[$name])) {
96                     switch ($name) {
97                         case 'excludemodules':
98                         case 'excludecontents':
99                             $value = clean_param($option['value'], PARAM_BOOL);
100                             $filters[$name] = $value;
101                             break;
102                         case 'sectionid':
103                         case 'sectionnumber':
104                         case 'cmid':
105                         case 'modid':
106                             $value = clean_param($option['value'], PARAM_INT);
107                             if (is_numeric($value)) {
108                                 $filters[$name] = $value;
109                             } else {
110                                 throw new moodle_exception('errorinvalidparam', 'webservice', '', $name);
111                             }
112                             break;
113                         case 'modname':
114                             $value = clean_param($option['value'], PARAM_PLUGIN);
115                             if ($value) {
116                                 $filters[$name] = $value;
117                             } else {
118                                 throw new moodle_exception('errorinvalidparam', 'webservice', '', $name);
119                             }
120                             break;
121                         default:
122                             throw new moodle_exception('errorinvalidparam', 'webservice', '', $name);
123                     }
124                 }
125             }
126         }
128         //retrieve the course
129         $course = $DB->get_record('course', array('id' => $params['courseid']), '*', MUST_EXIST);
131         if ($course->id != SITEID) {
132             // Check course format exist.
133             if (!file_exists($CFG->dirroot . '/course/format/' . $course->format . '/lib.php')) {
134                 throw new moodle_exception('cannotgetcoursecontents', 'webservice', '', null,
135                                             get_string('courseformatnotfound', 'error', $course->format));
136             } else {
137                 require_once($CFG->dirroot . '/course/format/' . $course->format . '/lib.php');
138             }
139         }
141         // now security checks
142         $context = context_course::instance($course->id, IGNORE_MISSING);
143         try {
144             self::validate_context($context);
145         } catch (Exception $e) {
146             $exceptionparam = new stdClass();
147             $exceptionparam->message = $e->getMessage();
148             $exceptionparam->courseid = $course->id;
149             throw new moodle_exception('errorcoursecontextnotvalid', 'webservice', '', $exceptionparam);
150         }
152         $canupdatecourse = has_capability('moodle/course:update', $context);
154         //create return value
155         $coursecontents = array();
157         if ($canupdatecourse or $course->visible
158                 or has_capability('moodle/course:viewhiddencourses', $context)) {
160             //retrieve sections
161             $modinfo = get_fast_modinfo($course);
162             $sections = $modinfo->get_section_info_all();
164             //for each sections (first displayed to last displayed)
165             $modinfosections = $modinfo->get_sections();
166             foreach ($sections as $key => $section) {
168                 if (!$section->uservisible) {
169                     continue;
170                 }
172                 // This becomes true when we are filtering and we found the value to filter with.
173                 $sectionfound = false;
175                 // Filter by section id.
176                 if (!empty($filters['sectionid'])) {
177                     if ($section->id != $filters['sectionid']) {
178                         continue;
179                     } else {
180                         $sectionfound = true;
181                     }
182                 }
184                 // Filter by section number. Note that 0 is a valid section number.
185                 if (isset($filters['sectionnumber'])) {
186                     if ($key != $filters['sectionnumber']) {
187                         continue;
188                     } else {
189                         $sectionfound = true;
190                     }
191                 }
193                 // reset $sectioncontents
194                 $sectionvalues = array();
195                 $sectionvalues['id'] = $section->id;
196                 $sectionvalues['name'] = get_section_name($course, $section);
197                 $sectionvalues['visible'] = $section->visible;
198                 list($sectionvalues['summary'], $sectionvalues['summaryformat']) =
199                         external_format_text($section->summary, $section->summaryformat,
200                                 $context->id, 'course', 'section', $section->id);
201                 $sectioncontents = array();
203                 //for each module of the section
204                 if (empty($filters['excludemodules']) and !empty($modinfosections[$section->section])) {
205                     foreach ($modinfosections[$section->section] as $cmid) {
206                         $cm = $modinfo->cms[$cmid];
208                         // stop here if the module is not visible to the user
209                         if (!$cm->uservisible) {
210                             continue;
211                         }
213                         // This becomes true when we are filtering and we found the value to filter with.
214                         $modfound = false;
216                         // Filter by cmid.
217                         if (!empty($filters['cmid'])) {
218                             if ($cmid != $filters['cmid']) {
219                                 continue;
220                             } else {
221                                 $modfound = true;
222                             }
223                         }
225                         // Filter by module name and id.
226                         if (!empty($filters['modname'])) {
227                             if ($cm->modname != $filters['modname']) {
228                                 continue;
229                             } else if (!empty($filters['modid'])) {
230                                 if ($cm->instance != $filters['modid']) {
231                                     continue;
232                                 } else {
233                                     // Note that if we are only filtering by modname we don't break the loop.
234                                     $modfound = true;
235                                 }
236                             }
237                         }
239                         $module = array();
241                         $modcontext = context_module::instance($cm->id);
243                         //common info (for people being able to see the module or availability dates)
244                         $module['id'] = $cm->id;
245                         $module['name'] = external_format_string($cm->name, $modcontext->id);
246                         $module['instance'] = $cm->instance;
247                         $module['modname'] = $cm->modname;
248                         $module['modplural'] = $cm->modplural;
249                         $module['modicon'] = $cm->get_icon_url()->out(false);
250                         $module['indent'] = $cm->indent;
252                         if (!empty($cm->showdescription) or $cm->modname == 'label') {
253                             // We want to use the external format. However from reading get_formatted_content(), $cm->content format is always FORMAT_HTML.
254                             list($module['description'], $descriptionformat) = external_format_text($cm->content,
255                                 FORMAT_HTML, $modcontext->id, $cm->modname, 'intro', $cm->id);
256                         }
258                         //url of the module
259                         $url = $cm->url;
260                         if ($url) { //labels don't have url
261                             $module['url'] = $url->out(false);
262                         }
264                         $canviewhidden = has_capability('moodle/course:viewhiddenactivities',
265                                             context_module::instance($cm->id));
266                         //user that can view hidden module should know about the visibility
267                         $module['visible'] = $cm->visible;
269                         // Availability date (also send to user who can see hidden module).
270                         if ($CFG->enableavailability && ($canviewhidden || $canupdatecourse)) {
271                             $module['availability'] = $cm->availability;
272                         }
274                         $baseurl = 'webservice/pluginfile.php';
276                         //call $modulename_export_contents
277                         //(each module callback take care about checking the capabilities)
279                         require_once($CFG->dirroot . '/mod/' . $cm->modname . '/lib.php');
280                         $getcontentfunction = $cm->modname.'_export_contents';
281                         if (function_exists($getcontentfunction)) {
282                             if (empty($filters['excludecontents']) and $contents = $getcontentfunction($cm, $baseurl)) {
283                                 $module['contents'] = $contents;
284                             } else {
285                                 $module['contents'] = array();
286                             }
287                         }
289                         //assign result to $sectioncontents
290                         $sectioncontents[] = $module;
292                         // If we just did a filtering, break the loop.
293                         if ($modfound) {
294                             break;
295                         }
297                     }
298                 }
299                 $sectionvalues['modules'] = $sectioncontents;
301                 // assign result to $coursecontents
302                 $coursecontents[] = $sectionvalues;
304                 // Break the loop if we are filtering.
305                 if ($sectionfound) {
306                     break;
307                 }
308             }
309         }
310         return $coursecontents;
311     }
313     /**
314      * Returns description of method result value
315      *
316      * @return external_description
317      * @since Moodle 2.2
318      */
319     public static function get_course_contents_returns() {
320         return new external_multiple_structure(
321             new external_single_structure(
322                 array(
323                     'id' => new external_value(PARAM_INT, 'Section ID'),
324                     'name' => new external_value(PARAM_TEXT, 'Section name'),
325                     'visible' => new external_value(PARAM_INT, 'is the section visible', VALUE_OPTIONAL),
326                     'summary' => new external_value(PARAM_RAW, 'Section description'),
327                     'summaryformat' => new external_format_value('summary'),
328                     'modules' => new external_multiple_structure(
329                             new external_single_structure(
330                                 array(
331                                     'id' => new external_value(PARAM_INT, 'activity id'),
332                                     'url' => new external_value(PARAM_URL, 'activity url', VALUE_OPTIONAL),
333                                     'name' => new external_value(PARAM_RAW, 'activity module name'),
334                                     'instance' => new external_value(PARAM_INT, 'instance id', VALUE_OPTIONAL),
335                                     'description' => new external_value(PARAM_RAW, 'activity description', VALUE_OPTIONAL),
336                                     'visible' => new external_value(PARAM_INT, 'is the module visible', VALUE_OPTIONAL),
337                                     'modicon' => new external_value(PARAM_URL, 'activity icon url'),
338                                     'modname' => new external_value(PARAM_PLUGIN, 'activity module type'),
339                                     'modplural' => new external_value(PARAM_TEXT, 'activity module plural name'),
340                                     'availability' => new external_value(PARAM_RAW, 'module availability settings', VALUE_OPTIONAL),
341                                     'indent' => new external_value(PARAM_INT, 'number of identation in the site'),
342                                     'contents' => new external_multiple_structure(
343                                           new external_single_structure(
344                                               array(
345                                                   // content info
346                                                   'type'=> new external_value(PARAM_TEXT, 'a file or a folder or external link'),
347                                                   'filename'=> new external_value(PARAM_FILE, 'filename'),
348                                                   'filepath'=> new external_value(PARAM_PATH, 'filepath'),
349                                                   'filesize'=> new external_value(PARAM_INT, 'filesize'),
350                                                   'fileurl' => new external_value(PARAM_URL, 'downloadable file url', VALUE_OPTIONAL),
351                                                   'content' => new external_value(PARAM_RAW, 'Raw content, will be used when type is content', VALUE_OPTIONAL),
352                                                   'timecreated' => new external_value(PARAM_INT, 'Time created'),
353                                                   'timemodified' => new external_value(PARAM_INT, 'Time modified'),
354                                                   'sortorder' => new external_value(PARAM_INT, 'Content sort order'),
356                                                   // copyright related info
357                                                   'userid' => new external_value(PARAM_INT, 'User who added this content to moodle'),
358                                                   'author' => new external_value(PARAM_TEXT, 'Content owner'),
359                                                   'license' => new external_value(PARAM_TEXT, 'Content license'),
360                                               )
361                                           ), VALUE_DEFAULT, array()
362                                       )
363                                 )
364                             ), 'list of module'
365                     )
366                 )
367             )
368         );
369     }
371     /**
372      * Returns description of method parameters
373      *
374      * @return external_function_parameters
375      * @since Moodle 2.3
376      */
377     public static function get_courses_parameters() {
378         return new external_function_parameters(
379                 array('options' => new external_single_structure(
380                             array('ids' => new external_multiple_structure(
381                                         new external_value(PARAM_INT, 'Course id')
382                                         , 'List of course id. If empty return all courses
383                                             except front page course.',
384                                         VALUE_OPTIONAL)
385                             ), 'options - operator OR is used', VALUE_DEFAULT, array())
386                 )
387         );
388     }
390     /**
391      * Get courses
392      *
393      * @param array $options It contains an array (list of ids)
394      * @return array
395      * @since Moodle 2.2
396      */
397     public static function get_courses($options = array()) {
398         global $CFG, $DB;
399         require_once($CFG->dirroot . "/course/lib.php");
401         //validate parameter
402         $params = self::validate_parameters(self::get_courses_parameters(),
403                         array('options' => $options));
405         //retrieve courses
406         if (!array_key_exists('ids', $params['options'])
407                 or empty($params['options']['ids'])) {
408             $courses = $DB->get_records('course');
409         } else {
410             $courses = $DB->get_records_list('course', 'id', $params['options']['ids']);
411         }
413         //create return value
414         $coursesinfo = array();
415         foreach ($courses as $course) {
417             // now security checks
418             $context = context_course::instance($course->id, IGNORE_MISSING);
419             $courseformatoptions = course_get_format($course)->get_format_options();
420             try {
421                 self::validate_context($context);
422             } catch (Exception $e) {
423                 $exceptionparam = new stdClass();
424                 $exceptionparam->message = $e->getMessage();
425                 $exceptionparam->courseid = $course->id;
426                 throw new moodle_exception('errorcoursecontextnotvalid', 'webservice', '', $exceptionparam);
427             }
428             require_capability('moodle/course:view', $context);
430             $courseinfo = array();
431             $courseinfo['id'] = $course->id;
432             $courseinfo['fullname'] = $course->fullname;
433             $courseinfo['shortname'] = $course->shortname;
434             $courseinfo['categoryid'] = $course->category;
435             list($courseinfo['summary'], $courseinfo['summaryformat']) =
436                 external_format_text($course->summary, $course->summaryformat, $context->id, 'course', 'summary', 0);
437             $courseinfo['format'] = $course->format;
438             $courseinfo['startdate'] = $course->startdate;
439             if (array_key_exists('numsections', $courseformatoptions)) {
440                 // For backward-compartibility
441                 $courseinfo['numsections'] = $courseformatoptions['numsections'];
442             }
444             //some field should be returned only if the user has update permission
445             $courseadmin = has_capability('moodle/course:update', $context);
446             if ($courseadmin) {
447                 $courseinfo['categorysortorder'] = $course->sortorder;
448                 $courseinfo['idnumber'] = $course->idnumber;
449                 $courseinfo['showgrades'] = $course->showgrades;
450                 $courseinfo['showreports'] = $course->showreports;
451                 $courseinfo['newsitems'] = $course->newsitems;
452                 $courseinfo['visible'] = $course->visible;
453                 $courseinfo['maxbytes'] = $course->maxbytes;
454                 if (array_key_exists('hiddensections', $courseformatoptions)) {
455                     // For backward-compartibility
456                     $courseinfo['hiddensections'] = $courseformatoptions['hiddensections'];
457                 }
458                 $courseinfo['groupmode'] = $course->groupmode;
459                 $courseinfo['groupmodeforce'] = $course->groupmodeforce;
460                 $courseinfo['defaultgroupingid'] = $course->defaultgroupingid;
461                 $courseinfo['lang'] = $course->lang;
462                 $courseinfo['timecreated'] = $course->timecreated;
463                 $courseinfo['timemodified'] = $course->timemodified;
464                 $courseinfo['forcetheme'] = $course->theme;
465                 $courseinfo['enablecompletion'] = $course->enablecompletion;
466                 $courseinfo['completionnotify'] = $course->completionnotify;
467                 $courseinfo['courseformatoptions'] = array();
468                 foreach ($courseformatoptions as $key => $value) {
469                     $courseinfo['courseformatoptions'][] = array(
470                         'name' => $key,
471                         'value' => $value
472                     );
473                 }
474             }
476             if ($courseadmin or $course->visible
477                     or has_capability('moodle/course:viewhiddencourses', $context)) {
478                 $coursesinfo[] = $courseinfo;
479             }
480         }
482         return $coursesinfo;
483     }
485     /**
486      * Returns description of method result value
487      *
488      * @return external_description
489      * @since Moodle 2.2
490      */
491     public static function get_courses_returns() {
492         return new external_multiple_structure(
493                 new external_single_structure(
494                         array(
495                             'id' => new external_value(PARAM_INT, 'course id'),
496                             'shortname' => new external_value(PARAM_TEXT, 'course short name'),
497                             'categoryid' => new external_value(PARAM_INT, 'category id'),
498                             'categorysortorder' => new external_value(PARAM_INT,
499                                     'sort order into the category', VALUE_OPTIONAL),
500                             'fullname' => new external_value(PARAM_TEXT, 'full name'),
501                             'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL),
502                             'summary' => new external_value(PARAM_RAW, 'summary'),
503                             'summaryformat' => new external_format_value('summary'),
504                             'format' => new external_value(PARAM_PLUGIN,
505                                     'course format: weeks, topics, social, site,..'),
506                             'showgrades' => new external_value(PARAM_INT,
507                                     '1 if grades are shown, otherwise 0', VALUE_OPTIONAL),
508                             'newsitems' => new external_value(PARAM_INT,
509                                     'number of recent items appearing on the course page', VALUE_OPTIONAL),
510                             'startdate' => new external_value(PARAM_INT,
511                                     'timestamp when the course start'),
512                             'numsections' => new external_value(PARAM_INT,
513                                     '(deprecated, use courseformatoptions) number of weeks/topics',
514                                     VALUE_OPTIONAL),
515                             'maxbytes' => new external_value(PARAM_INT,
516                                     'largest size of file that can be uploaded into the course',
517                                     VALUE_OPTIONAL),
518                             'showreports' => new external_value(PARAM_INT,
519                                     'are activity report shown (yes = 1, no =0)', VALUE_OPTIONAL),
520                             'visible' => new external_value(PARAM_INT,
521                                     '1: available to student, 0:not available', VALUE_OPTIONAL),
522                             'hiddensections' => new external_value(PARAM_INT,
523                                     '(deprecated, use courseformatoptions) How the hidden sections in the course are displayed to students',
524                                     VALUE_OPTIONAL),
525                             'groupmode' => new external_value(PARAM_INT, 'no group, separate, visible',
526                                     VALUE_OPTIONAL),
527                             'groupmodeforce' => new external_value(PARAM_INT, '1: yes, 0: no',
528                                     VALUE_OPTIONAL),
529                             'defaultgroupingid' => new external_value(PARAM_INT, 'default grouping id',
530                                     VALUE_OPTIONAL),
531                             'timecreated' => new external_value(PARAM_INT,
532                                     'timestamp when the course have been created', VALUE_OPTIONAL),
533                             'timemodified' => new external_value(PARAM_INT,
534                                     'timestamp when the course have been modified', VALUE_OPTIONAL),
535                             'enablecompletion' => new external_value(PARAM_INT,
536                                     'Enabled, control via completion and activity settings. Disbaled,
537                                         not shown in activity settings.',
538                                     VALUE_OPTIONAL),
539                             'completionnotify' => new external_value(PARAM_INT,
540                                     '1: yes 0: no', VALUE_OPTIONAL),
541                             'lang' => new external_value(PARAM_SAFEDIR,
542                                     'forced course language', VALUE_OPTIONAL),
543                             'forcetheme' => new external_value(PARAM_PLUGIN,
544                                     'name of the force theme', VALUE_OPTIONAL),
545                             'courseformatoptions' => new external_multiple_structure(
546                                 new external_single_structure(
547                                     array('name' => new external_value(PARAM_ALPHANUMEXT, 'course format option name'),
548                                         'value' => new external_value(PARAM_RAW, 'course format option value')
549                                 )),
550                                     'additional options for particular course format', VALUE_OPTIONAL
551                              ),
552                         ), 'course'
553                 )
554         );
555     }
557     /**
558      * Returns description of method parameters
559      *
560      * @return external_function_parameters
561      * @since Moodle 2.2
562      */
563     public static function create_courses_parameters() {
564         $courseconfig = get_config('moodlecourse'); //needed for many default values
565         return new external_function_parameters(
566             array(
567                 'courses' => new external_multiple_structure(
568                     new external_single_structure(
569                         array(
570                             'fullname' => new external_value(PARAM_TEXT, 'full name'),
571                             'shortname' => new external_value(PARAM_TEXT, 'course short name'),
572                             'categoryid' => new external_value(PARAM_INT, 'category id'),
573                             'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL),
574                             'summary' => new external_value(PARAM_RAW, 'summary', VALUE_OPTIONAL),
575                             'summaryformat' => new external_format_value('summary', VALUE_DEFAULT),
576                             'format' => new external_value(PARAM_PLUGIN,
577                                     'course format: weeks, topics, social, site,..',
578                                     VALUE_DEFAULT, $courseconfig->format),
579                             'showgrades' => new external_value(PARAM_INT,
580                                     '1 if grades are shown, otherwise 0', VALUE_DEFAULT,
581                                     $courseconfig->showgrades),
582                             'newsitems' => new external_value(PARAM_INT,
583                                     'number of recent items appearing on the course page',
584                                     VALUE_DEFAULT, $courseconfig->newsitems),
585                             'startdate' => new external_value(PARAM_INT,
586                                     'timestamp when the course start', VALUE_OPTIONAL),
587                             'numsections' => new external_value(PARAM_INT,
588                                     '(deprecated, use courseformatoptions) number of weeks/topics',
589                                     VALUE_OPTIONAL),
590                             'maxbytes' => new external_value(PARAM_INT,
591                                     'largest size of file that can be uploaded into the course',
592                                     VALUE_DEFAULT, $courseconfig->maxbytes),
593                             'showreports' => new external_value(PARAM_INT,
594                                     'are activity report shown (yes = 1, no =0)', VALUE_DEFAULT,
595                                     $courseconfig->showreports),
596                             'visible' => new external_value(PARAM_INT,
597                                     '1: available to student, 0:not available', VALUE_OPTIONAL),
598                             'hiddensections' => new external_value(PARAM_INT,
599                                     '(deprecated, use courseformatoptions) How the hidden sections in the course are displayed to students',
600                                     VALUE_OPTIONAL),
601                             'groupmode' => new external_value(PARAM_INT, 'no group, separate, visible',
602                                     VALUE_DEFAULT, $courseconfig->groupmode),
603                             'groupmodeforce' => new external_value(PARAM_INT, '1: yes, 0: no',
604                                     VALUE_DEFAULT, $courseconfig->groupmodeforce),
605                             'defaultgroupingid' => new external_value(PARAM_INT, 'default grouping id',
606                                     VALUE_DEFAULT, 0),
607                             'enablecompletion' => new external_value(PARAM_INT,
608                                     'Enabled, control via completion and activity settings. Disabled,
609                                         not shown in activity settings.',
610                                     VALUE_OPTIONAL),
611                             'completionnotify' => new external_value(PARAM_INT,
612                                     '1: yes 0: no', VALUE_OPTIONAL),
613                             'lang' => new external_value(PARAM_SAFEDIR,
614                                     'forced course language', VALUE_OPTIONAL),
615                             'forcetheme' => new external_value(PARAM_PLUGIN,
616                                     'name of the force theme', VALUE_OPTIONAL),
617                             'courseformatoptions' => new external_multiple_structure(
618                                 new external_single_structure(
619                                     array('name' => new external_value(PARAM_ALPHANUMEXT, 'course format option name'),
620                                         'value' => new external_value(PARAM_RAW, 'course format option value')
621                                 )),
622                                     'additional options for particular course format', VALUE_OPTIONAL),
623                         )
624                     ), 'courses to create'
625                 )
626             )
627         );
628     }
630     /**
631      * Create  courses
632      *
633      * @param array $courses
634      * @return array courses (id and shortname only)
635      * @since Moodle 2.2
636      */
637     public static function create_courses($courses) {
638         global $CFG, $DB;
639         require_once($CFG->dirroot . "/course/lib.php");
640         require_once($CFG->libdir . '/completionlib.php');
642         $params = self::validate_parameters(self::create_courses_parameters(),
643                         array('courses' => $courses));
645         $availablethemes = core_component::get_plugin_list('theme');
646         $availablelangs = get_string_manager()->get_list_of_translations();
648         $transaction = $DB->start_delegated_transaction();
650         foreach ($params['courses'] as $course) {
652             // Ensure the current user is allowed to run this function
653             $context = context_coursecat::instance($course['categoryid'], IGNORE_MISSING);
654             try {
655                 self::validate_context($context);
656             } catch (Exception $e) {
657                 $exceptionparam = new stdClass();
658                 $exceptionparam->message = $e->getMessage();
659                 $exceptionparam->catid = $course['categoryid'];
660                 throw new moodle_exception('errorcatcontextnotvalid', 'webservice', '', $exceptionparam);
661             }
662             require_capability('moodle/course:create', $context);
664             // Make sure lang is valid
665             if (array_key_exists('lang', $course) and empty($availablelangs[$course['lang']])) {
666                 throw new moodle_exception('errorinvalidparam', 'webservice', '', 'lang');
667             }
669             // Make sure theme is valid
670             if (array_key_exists('forcetheme', $course)) {
671                 if (!empty($CFG->allowcoursethemes)) {
672                     if (empty($availablethemes[$course['forcetheme']])) {
673                         throw new moodle_exception('errorinvalidparam', 'webservice', '', 'forcetheme');
674                     } else {
675                         $course['theme'] = $course['forcetheme'];
676                     }
677                 }
678             }
680             //force visibility if ws user doesn't have the permission to set it
681             $category = $DB->get_record('course_categories', array('id' => $course['categoryid']));
682             if (!has_capability('moodle/course:visibility', $context)) {
683                 $course['visible'] = $category->visible;
684             }
686             //set default value for completion
687             $courseconfig = get_config('moodlecourse');
688             if (completion_info::is_enabled_for_site()) {
689                 if (!array_key_exists('enablecompletion', $course)) {
690                     $course['enablecompletion'] = $courseconfig->enablecompletion;
691                 }
692             } else {
693                 $course['enablecompletion'] = 0;
694             }
696             $course['category'] = $course['categoryid'];
698             // Summary format.
699             $course['summaryformat'] = external_validate_format($course['summaryformat']);
701             if (!empty($course['courseformatoptions'])) {
702                 foreach ($course['courseformatoptions'] as $option) {
703                     $course[$option['name']] = $option['value'];
704                 }
705             }
707             //Note: create_course() core function check shortname, idnumber, category
708             $course['id'] = create_course((object) $course)->id;
710             $resultcourses[] = array('id' => $course['id'], 'shortname' => $course['shortname']);
711         }
713         $transaction->allow_commit();
715         return $resultcourses;
716     }
718     /**
719      * Returns description of method result value
720      *
721      * @return external_description
722      * @since Moodle 2.2
723      */
724     public static function create_courses_returns() {
725         return new external_multiple_structure(
726             new external_single_structure(
727                 array(
728                     'id'       => new external_value(PARAM_INT, 'course id'),
729                     'shortname' => new external_value(PARAM_TEXT, 'short name'),
730                 )
731             )
732         );
733     }
735     /**
736      * Update courses
737      *
738      * @return external_function_parameters
739      * @since Moodle 2.5
740      */
741     public static function update_courses_parameters() {
742         return new external_function_parameters(
743             array(
744                 'courses' => new external_multiple_structure(
745                     new external_single_structure(
746                         array(
747                             'id' => new external_value(PARAM_INT, 'ID of the course'),
748                             'fullname' => new external_value(PARAM_TEXT, 'full name', VALUE_OPTIONAL),
749                             'shortname' => new external_value(PARAM_TEXT, 'course short name', VALUE_OPTIONAL),
750                             'categoryid' => new external_value(PARAM_INT, 'category id', VALUE_OPTIONAL),
751                             'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL),
752                             'summary' => new external_value(PARAM_RAW, 'summary', VALUE_OPTIONAL),
753                             'summaryformat' => new external_format_value('summary', VALUE_OPTIONAL),
754                             'format' => new external_value(PARAM_PLUGIN,
755                                     'course format: weeks, topics, social, site,..', VALUE_OPTIONAL),
756                             'showgrades' => new external_value(PARAM_INT,
757                                     '1 if grades are shown, otherwise 0', VALUE_OPTIONAL),
758                             'newsitems' => new external_value(PARAM_INT,
759                                     'number of recent items appearing on the course page', VALUE_OPTIONAL),
760                             'startdate' => new external_value(PARAM_INT,
761                                     'timestamp when the course start', VALUE_OPTIONAL),
762                             'numsections' => new external_value(PARAM_INT,
763                                     '(deprecated, use courseformatoptions) number of weeks/topics', VALUE_OPTIONAL),
764                             'maxbytes' => new external_value(PARAM_INT,
765                                     'largest size of file that can be uploaded into the course', VALUE_OPTIONAL),
766                             'showreports' => new external_value(PARAM_INT,
767                                     'are activity report shown (yes = 1, no =0)', VALUE_OPTIONAL),
768                             'visible' => new external_value(PARAM_INT,
769                                     '1: available to student, 0:not available', VALUE_OPTIONAL),
770                             'hiddensections' => new external_value(PARAM_INT,
771                                     '(deprecated, use courseformatoptions) How the hidden sections in the course are
772                                         displayed to students', VALUE_OPTIONAL),
773                             'groupmode' => new external_value(PARAM_INT, 'no group, separate, visible', VALUE_OPTIONAL),
774                             'groupmodeforce' => new external_value(PARAM_INT, '1: yes, 0: no', VALUE_OPTIONAL),
775                             'defaultgroupingid' => new external_value(PARAM_INT, 'default grouping id', VALUE_OPTIONAL),
776                             'enablecompletion' => new external_value(PARAM_INT,
777                                     'Enabled, control via completion and activity settings. Disabled,
778                                         not shown in activity settings.', VALUE_OPTIONAL),
779                             'completionnotify' => new external_value(PARAM_INT, '1: yes 0: no', VALUE_OPTIONAL),
780                             'lang' => new external_value(PARAM_SAFEDIR, 'forced course language', VALUE_OPTIONAL),
781                             'forcetheme' => new external_value(PARAM_PLUGIN, 'name of the force theme', VALUE_OPTIONAL),
782                             'courseformatoptions' => new external_multiple_structure(
783                                 new external_single_structure(
784                                     array('name' => new external_value(PARAM_ALPHANUMEXT, 'course format option name'),
785                                         'value' => new external_value(PARAM_RAW, 'course format option value')
786                                 )),
787                                     'additional options for particular course format', VALUE_OPTIONAL),
788                         )
789                     ), 'courses to update'
790                 )
791             )
792         );
793     }
795     /**
796      * Update courses
797      *
798      * @param array $courses
799      * @since Moodle 2.5
800      */
801     public static function update_courses($courses) {
802         global $CFG, $DB;
803         require_once($CFG->dirroot . "/course/lib.php");
804         $warnings = array();
806         $params = self::validate_parameters(self::update_courses_parameters(),
807                         array('courses' => $courses));
809         $availablethemes = core_component::get_plugin_list('theme');
810         $availablelangs = get_string_manager()->get_list_of_translations();
812         foreach ($params['courses'] as $course) {
813             // Catch any exception while updating course and return as warning to user.
814             try {
815                 // Ensure the current user is allowed to run this function.
816                 $context = context_course::instance($course['id'], MUST_EXIST);
817                 self::validate_context($context);
819                 $oldcourse = course_get_format($course['id'])->get_course();
821                 require_capability('moodle/course:update', $context);
823                 // Check if user can change category.
824                 if (array_key_exists('categoryid', $course) && ($oldcourse->category != $course['categoryid'])) {
825                     require_capability('moodle/course:changecategory', $context);
826                     $course['category'] = $course['categoryid'];
827                 }
829                 // Check if the user can change fullname.
830                 if (array_key_exists('fullname', $course) && ($oldcourse->fullname != $course['fullname'])) {
831                     require_capability('moodle/course:changefullname', $context);
832                 }
834                 // Check if the user can change shortname.
835                 if (array_key_exists('shortname', $course) && ($oldcourse->shortname != $course['shortname'])) {
836                     require_capability('moodle/course:changeshortname', $context);
837                 }
839                 // Check if the user can change the idnumber.
840                 if (array_key_exists('idnumber', $course) && ($oldcourse->idnumber != $course['idnumber'])) {
841                     require_capability('moodle/course:changeidnumber', $context);
842                 }
844                 // Check if user can change summary.
845                 if (array_key_exists('summary', $course) && ($oldcourse->summary != $course['summary'])) {
846                     require_capability('moodle/course:changesummary', $context);
847                 }
849                 // Summary format.
850                 if (array_key_exists('summaryformat', $course) && ($oldcourse->summaryformat != $course['summaryformat'])) {
851                     require_capability('moodle/course:changesummary', $context);
852                     $course['summaryformat'] = external_validate_format($course['summaryformat']);
853                 }
855                 // Check if user can change visibility.
856                 if (array_key_exists('visible', $course) && ($oldcourse->visible != $course['visible'])) {
857                     require_capability('moodle/course:visibility', $context);
858                 }
860                 // Make sure lang is valid.
861                 if (array_key_exists('lang', $course) && empty($availablelangs[$course['lang']])) {
862                     throw new moodle_exception('errorinvalidparam', 'webservice', '', 'lang');
863                 }
865                 // Make sure theme is valid.
866                 if (array_key_exists('forcetheme', $course)) {
867                     if (!empty($CFG->allowcoursethemes)) {
868                         if (empty($availablethemes[$course['forcetheme']])) {
869                             throw new moodle_exception('errorinvalidparam', 'webservice', '', 'forcetheme');
870                         } else {
871                             $course['theme'] = $course['forcetheme'];
872                         }
873                     }
874                 }
876                 // Make sure completion is enabled before setting it.
877                 if (array_key_exists('enabledcompletion', $course) && !completion_info::is_enabled_for_site()) {
878                     $course['enabledcompletion'] = 0;
879                 }
881                 // Make sure maxbytes are less then CFG->maxbytes.
882                 if (array_key_exists('maxbytes', $course)) {
883                     $course['maxbytes'] = get_max_upload_file_size($CFG->maxbytes, $course['maxbytes']);
884                 }
886                 if (!empty($course['courseformatoptions'])) {
887                     foreach ($course['courseformatoptions'] as $option) {
888                         if (isset($option['name']) && isset($option['value'])) {
889                             $course[$option['name']] = $option['value'];
890                         }
891                     }
892                 }
894                 // Update course if user has all required capabilities.
895                 update_course((object) $course);
896             } catch (Exception $e) {
897                 $warning = array();
898                 $warning['item'] = 'course';
899                 $warning['itemid'] = $course['id'];
900                 if ($e instanceof moodle_exception) {
901                     $warning['warningcode'] = $e->errorcode;
902                 } else {
903                     $warning['warningcode'] = $e->getCode();
904                 }
905                 $warning['message'] = $e->getMessage();
906                 $warnings[] = $warning;
907             }
908         }
910         $result = array();
911         $result['warnings'] = $warnings;
912         return $result;
913     }
915     /**
916      * Returns description of method result value
917      *
918      * @return external_description
919      * @since Moodle 2.5
920      */
921     public static function update_courses_returns() {
922         return new external_single_structure(
923             array(
924                 'warnings' => new external_warnings()
925             )
926         );
927     }
929     /**
930      * Returns description of method parameters
931      *
932      * @return external_function_parameters
933      * @since Moodle 2.2
934      */
935     public static function delete_courses_parameters() {
936         return new external_function_parameters(
937             array(
938                 'courseids' => new external_multiple_structure(new external_value(PARAM_INT, 'course ID')),
939             )
940         );
941     }
943     /**
944      * Delete courses
945      *
946      * @param array $courseids A list of course ids
947      * @since Moodle 2.2
948      */
949     public static function delete_courses($courseids) {
950         global $CFG, $DB;
951         require_once($CFG->dirroot."/course/lib.php");
953         // Parameter validation.
954         $params = self::validate_parameters(self::delete_courses_parameters(), array('courseids'=>$courseids));
956         $warnings = array();
958         foreach ($params['courseids'] as $courseid) {
959             $course = $DB->get_record('course', array('id' => $courseid));
961             if ($course === false) {
962                 $warnings[] = array(
963                                 'item' => 'course',
964                                 'itemid' => $courseid,
965                                 'warningcode' => 'unknowncourseidnumber',
966                                 'message' => 'Unknown course ID ' . $courseid
967                             );
968                 continue;
969             }
971             // Check if the context is valid.
972             $coursecontext = context_course::instance($course->id);
973             self::validate_context($coursecontext);
975             // Check if the current user has permission.
976             if (!can_delete_course($courseid)) {
977                 $warnings[] = array(
978                                 'item' => 'course',
979                                 'itemid' => $courseid,
980                                 'warningcode' => 'cannotdeletecourse',
981                                 'message' => 'You do not have the permission to delete this course' . $courseid
982                             );
983                 continue;
984             }
986             if (delete_course($course, false) === false) {
987                 $warnings[] = array(
988                                 'item' => 'course',
989                                 'itemid' => $courseid,
990                                 'warningcode' => 'cannotdeletecategorycourse',
991                                 'message' => 'Course ' . $courseid . ' failed to be deleted'
992                             );
993                 continue;
994             }
995         }
997         fix_course_sortorder();
999         return array('warnings' => $warnings);
1000     }
1002     /**
1003      * Returns description of method result value
1004      *
1005      * @return external_description
1006      * @since Moodle 2.2
1007      */
1008     public static function delete_courses_returns() {
1009         return new external_single_structure(
1010             array(
1011                 'warnings' => new external_warnings()
1012             )
1013         );
1014     }
1016     /**
1017      * Returns description of method parameters
1018      *
1019      * @return external_function_parameters
1020      * @since Moodle 2.3
1021      */
1022     public static function duplicate_course_parameters() {
1023         return new external_function_parameters(
1024             array(
1025                 'courseid' => new external_value(PARAM_INT, 'course to duplicate id'),
1026                 'fullname' => new external_value(PARAM_TEXT, 'duplicated course full name'),
1027                 'shortname' => new external_value(PARAM_TEXT, 'duplicated course short name'),
1028                 'categoryid' => new external_value(PARAM_INT, 'duplicated course category parent'),
1029                 'visible' => new external_value(PARAM_INT, 'duplicated course visible, default to yes', VALUE_DEFAULT, 1),
1030                 'options' => new external_multiple_structure(
1031                     new external_single_structure(
1032                         array(
1033                                 'name' => new external_value(PARAM_ALPHAEXT, 'The backup option name:
1034                                             "activities" (int) Include course activites (default to 1 that is equal to yes),
1035                                             "blocks" (int) Include course blocks (default to 1 that is equal to yes),
1036                                             "filters" (int) Include course filters  (default to 1 that is equal to yes),
1037                                             "users" (int) Include users (default to 0 that is equal to no),
1038                                             "role_assignments" (int) Include role assignments  (default to 0 that is equal to no),
1039                                             "comments" (int) Include user comments  (default to 0 that is equal to no),
1040                                             "userscompletion" (int) Include user course completion information  (default to 0 that is equal to no),
1041                                             "logs" (int) Include course logs  (default to 0 that is equal to no),
1042                                             "grade_histories" (int) Include histories  (default to 0 that is equal to no)'
1043                                             ),
1044                                 'value' => new external_value(PARAM_RAW, 'the value for the option 1 (yes) or 0 (no)'
1045                             )
1046                         )
1047                     ), VALUE_DEFAULT, array()
1048                 ),
1049             )
1050         );
1051     }
1053     /**
1054      * Duplicate a course
1055      *
1056      * @param int $courseid
1057      * @param string $fullname Duplicated course fullname
1058      * @param string $shortname Duplicated course shortname
1059      * @param int $categoryid Duplicated course parent category id
1060      * @param int $visible Duplicated course availability
1061      * @param array $options List of backup options
1062      * @return array New course info
1063      * @since Moodle 2.3
1064      */
1065     public static function duplicate_course($courseid, $fullname, $shortname, $categoryid, $visible = 1, $options = array()) {
1066         global $CFG, $USER, $DB;
1067         require_once($CFG->dirroot . '/backup/util/includes/backup_includes.php');
1068         require_once($CFG->dirroot . '/backup/util/includes/restore_includes.php');
1070         // Parameter validation.
1071         $params = self::validate_parameters(
1072                 self::duplicate_course_parameters(),
1073                 array(
1074                       'courseid' => $courseid,
1075                       'fullname' => $fullname,
1076                       'shortname' => $shortname,
1077                       'categoryid' => $categoryid,
1078                       'visible' => $visible,
1079                       'options' => $options
1080                 )
1081         );
1083         // Context validation.
1085         if (! ($course = $DB->get_record('course', array('id'=>$params['courseid'])))) {
1086             throw new moodle_exception('invalidcourseid', 'error');
1087         }
1089         // Category where duplicated course is going to be created.
1090         $categorycontext = context_coursecat::instance($params['categoryid']);
1091         self::validate_context($categorycontext);
1093         // Course to be duplicated.
1094         $coursecontext = context_course::instance($course->id);
1095         self::validate_context($coursecontext);
1097         $backupdefaults = array(
1098             'activities' => 1,
1099             'blocks' => 1,
1100             'filters' => 1,
1101             'users' => 0,
1102             'role_assignments' => 0,
1103             'comments' => 0,
1104             'userscompletion' => 0,
1105             'logs' => 0,
1106             'grade_histories' => 0
1107         );
1109         $backupsettings = array();
1110         // Check for backup and restore options.
1111         if (!empty($params['options'])) {
1112             foreach ($params['options'] as $option) {
1114                 // Strict check for a correct value (allways 1 or 0, true or false).
1115                 $value = clean_param($option['value'], PARAM_INT);
1117                 if ($value !== 0 and $value !== 1) {
1118                     throw new moodle_exception('invalidextparam', 'webservice', '', $option['name']);
1119                 }
1121                 if (!isset($backupdefaults[$option['name']])) {
1122                     throw new moodle_exception('invalidextparam', 'webservice', '', $option['name']);
1123                 }
1125                 $backupsettings[$option['name']] = $value;
1126             }
1127         }
1129         // Capability checking.
1131         // The backup controller check for this currently, this may be redundant.
1132         require_capability('moodle/course:create', $categorycontext);
1133         require_capability('moodle/restore:restorecourse', $categorycontext);
1134         require_capability('moodle/backup:backupcourse', $coursecontext);
1136         if (!empty($backupsettings['users'])) {
1137             require_capability('moodle/backup:userinfo', $coursecontext);
1138             require_capability('moodle/restore:userinfo', $categorycontext);
1139         }
1141         // Check if the shortname is used.
1142         if ($foundcourses = $DB->get_records('course', array('shortname'=>$shortname))) {
1143             foreach ($foundcourses as $foundcourse) {
1144                 $foundcoursenames[] = $foundcourse->fullname;
1145             }
1147             $foundcoursenamestring = implode(',', $foundcoursenames);
1148             throw new moodle_exception('shortnametaken', '', '', $foundcoursenamestring);
1149         }
1151         // Backup the course.
1153         $bc = new backup_controller(backup::TYPE_1COURSE, $course->id, backup::FORMAT_MOODLE,
1154         backup::INTERACTIVE_NO, backup::MODE_SAMESITE, $USER->id);
1156         foreach ($backupsettings as $name => $value) {
1157             $bc->get_plan()->get_setting($name)->set_value($value);
1158         }
1160         $backupid       = $bc->get_backupid();
1161         $backupbasepath = $bc->get_plan()->get_basepath();
1163         $bc->execute_plan();
1164         $results = $bc->get_results();
1165         $file = $results['backup_destination'];
1167         $bc->destroy();
1169         // Restore the backup immediately.
1171         // Check if we need to unzip the file because the backup temp dir does not contains backup files.
1172         if (!file_exists($backupbasepath . "/moodle_backup.xml")) {
1173             $file->extract_to_pathname(get_file_packer('application/vnd.moodle.backup'), $backupbasepath);
1174         }
1176         // Create new course.
1177         $newcourseid = restore_dbops::create_new_course($params['fullname'], $params['shortname'], $params['categoryid']);
1179         $rc = new restore_controller($backupid, $newcourseid,
1180                 backup::INTERACTIVE_NO, backup::MODE_SAMESITE, $USER->id, backup::TARGET_NEW_COURSE);
1182         foreach ($backupsettings as $name => $value) {
1183             $setting = $rc->get_plan()->get_setting($name);
1184             if ($setting->get_status() == backup_setting::NOT_LOCKED) {
1185                 $setting->set_value($value);
1186             }
1187         }
1189         if (!$rc->execute_precheck()) {
1190             $precheckresults = $rc->get_precheck_results();
1191             if (is_array($precheckresults) && !empty($precheckresults['errors'])) {
1192                 if (empty($CFG->keeptempdirectoriesonbackup)) {
1193                     fulldelete($backupbasepath);
1194                 }
1196                 $errorinfo = '';
1198                 foreach ($precheckresults['errors'] as $error) {
1199                     $errorinfo .= $error;
1200                 }
1202                 if (array_key_exists('warnings', $precheckresults)) {
1203                     foreach ($precheckresults['warnings'] as $warning) {
1204                         $errorinfo .= $warning;
1205                     }
1206                 }
1208                 throw new moodle_exception('backupprecheckerrors', 'webservice', '', $errorinfo);
1209             }
1210         }
1212         $rc->execute_plan();
1213         $rc->destroy();
1215         $course = $DB->get_record('course', array('id' => $newcourseid), '*', MUST_EXIST);
1216         $course->fullname = $params['fullname'];
1217         $course->shortname = $params['shortname'];
1218         $course->visible = $params['visible'];
1220         // Set shortname and fullname back.
1221         $DB->update_record('course', $course);
1223         if (empty($CFG->keeptempdirectoriesonbackup)) {
1224             fulldelete($backupbasepath);
1225         }
1227         // Delete the course backup file created by this WebService. Originally located in the course backups area.
1228         $file->delete();
1230         return array('id' => $course->id, 'shortname' => $course->shortname);
1231     }
1233     /**
1234      * Returns description of method result value
1235      *
1236      * @return external_description
1237      * @since Moodle 2.3
1238      */
1239     public static function duplicate_course_returns() {
1240         return new external_single_structure(
1241             array(
1242                 'id'       => new external_value(PARAM_INT, 'course id'),
1243                 'shortname' => new external_value(PARAM_TEXT, 'short name'),
1244             )
1245         );
1246     }
1248     /**
1249      * Returns description of method parameters for import_course
1250      *
1251      * @return external_function_parameters
1252      * @since Moodle 2.4
1253      */
1254     public static function import_course_parameters() {
1255         return new external_function_parameters(
1256             array(
1257                 'importfrom' => new external_value(PARAM_INT, 'the id of the course we are importing from'),
1258                 'importto' => new external_value(PARAM_INT, 'the id of the course we are importing to'),
1259                 'deletecontent' => new external_value(PARAM_INT, 'whether to delete the course content where we are importing to (default to 0 = No)', VALUE_DEFAULT, 0),
1260                 'options' => new external_multiple_structure(
1261                     new external_single_structure(
1262                         array(
1263                                 'name' => new external_value(PARAM_ALPHA, 'The backup option name:
1264                                             "activities" (int) Include course activites (default to 1 that is equal to yes),
1265                                             "blocks" (int) Include course blocks (default to 1 that is equal to yes),
1266                                             "filters" (int) Include course filters  (default to 1 that is equal to yes)'
1267                                             ),
1268                                 'value' => new external_value(PARAM_RAW, 'the value for the option 1 (yes) or 0 (no)'
1269                             )
1270                         )
1271                     ), VALUE_DEFAULT, array()
1272                 ),
1273             )
1274         );
1275     }
1277     /**
1278      * Imports a course
1279      *
1280      * @param int $importfrom The id of the course we are importing from
1281      * @param int $importto The id of the course we are importing to
1282      * @param bool $deletecontent Whether to delete the course we are importing to content
1283      * @param array $options List of backup options
1284      * @return null
1285      * @since Moodle 2.4
1286      */
1287     public static function import_course($importfrom, $importto, $deletecontent = 0, $options = array()) {
1288         global $CFG, $USER, $DB;
1289         require_once($CFG->dirroot . '/backup/util/includes/backup_includes.php');
1290         require_once($CFG->dirroot . '/backup/util/includes/restore_includes.php');
1292         // Parameter validation.
1293         $params = self::validate_parameters(
1294             self::import_course_parameters(),
1295             array(
1296                 'importfrom' => $importfrom,
1297                 'importto' => $importto,
1298                 'deletecontent' => $deletecontent,
1299                 'options' => $options
1300             )
1301         );
1303         if ($params['deletecontent'] !== 0 and $params['deletecontent'] !== 1) {
1304             throw new moodle_exception('invalidextparam', 'webservice', '', $params['deletecontent']);
1305         }
1307         // Context validation.
1309         if (! ($importfrom = $DB->get_record('course', array('id'=>$params['importfrom'])))) {
1310             throw new moodle_exception('invalidcourseid', 'error');
1311         }
1313         if (! ($importto = $DB->get_record('course', array('id'=>$params['importto'])))) {
1314             throw new moodle_exception('invalidcourseid', 'error');
1315         }
1317         $importfromcontext = context_course::instance($importfrom->id);
1318         self::validate_context($importfromcontext);
1320         $importtocontext = context_course::instance($importto->id);
1321         self::validate_context($importtocontext);
1323         $backupdefaults = array(
1324             'activities' => 1,
1325             'blocks' => 1,
1326             'filters' => 1
1327         );
1329         $backupsettings = array();
1331         // Check for backup and restore options.
1332         if (!empty($params['options'])) {
1333             foreach ($params['options'] as $option) {
1335                 // Strict check for a correct value (allways 1 or 0, true or false).
1336                 $value = clean_param($option['value'], PARAM_INT);
1338                 if ($value !== 0 and $value !== 1) {
1339                     throw new moodle_exception('invalidextparam', 'webservice', '', $option['name']);
1340                 }
1342                 if (!isset($backupdefaults[$option['name']])) {
1343                     throw new moodle_exception('invalidextparam', 'webservice', '', $option['name']);
1344                 }
1346                 $backupsettings[$option['name']] = $value;
1347             }
1348         }
1350         // Capability checking.
1352         require_capability('moodle/backup:backuptargetimport', $importfromcontext);
1353         require_capability('moodle/restore:restoretargetimport', $importtocontext);
1355         $bc = new backup_controller(backup::TYPE_1COURSE, $importfrom->id, backup::FORMAT_MOODLE,
1356                 backup::INTERACTIVE_NO, backup::MODE_IMPORT, $USER->id);
1358         foreach ($backupsettings as $name => $value) {
1359             $bc->get_plan()->get_setting($name)->set_value($value);
1360         }
1362         $backupid       = $bc->get_backupid();
1363         $backupbasepath = $bc->get_plan()->get_basepath();
1365         $bc->execute_plan();
1366         $bc->destroy();
1368         // Restore the backup immediately.
1370         // Check if we must delete the contents of the destination course.
1371         if ($params['deletecontent']) {
1372             $restoretarget = backup::TARGET_EXISTING_DELETING;
1373         } else {
1374             $restoretarget = backup::TARGET_EXISTING_ADDING;
1375         }
1377         $rc = new restore_controller($backupid, $importto->id,
1378                 backup::INTERACTIVE_NO, backup::MODE_IMPORT, $USER->id, $restoretarget);
1380         foreach ($backupsettings as $name => $value) {
1381             $rc->get_plan()->get_setting($name)->set_value($value);
1382         }
1384         if (!$rc->execute_precheck()) {
1385             $precheckresults = $rc->get_precheck_results();
1386             if (is_array($precheckresults) && !empty($precheckresults['errors'])) {
1387                 if (empty($CFG->keeptempdirectoriesonbackup)) {
1388                     fulldelete($backupbasepath);
1389                 }
1391                 $errorinfo = '';
1393                 foreach ($precheckresults['errors'] as $error) {
1394                     $errorinfo .= $error;
1395                 }
1397                 if (array_key_exists('warnings', $precheckresults)) {
1398                     foreach ($precheckresults['warnings'] as $warning) {
1399                         $errorinfo .= $warning;
1400                     }
1401                 }
1403                 throw new moodle_exception('backupprecheckerrors', 'webservice', '', $errorinfo);
1404             }
1405         } else {
1406             if ($restoretarget == backup::TARGET_EXISTING_DELETING) {
1407                 restore_dbops::delete_course_content($importto->id);
1408             }
1409         }
1411         $rc->execute_plan();
1412         $rc->destroy();
1414         if (empty($CFG->keeptempdirectoriesonbackup)) {
1415             fulldelete($backupbasepath);
1416         }
1418         return null;
1419     }
1421     /**
1422      * Returns description of method result value
1423      *
1424      * @return external_description
1425      * @since Moodle 2.4
1426      */
1427     public static function import_course_returns() {
1428         return null;
1429     }
1431     /**
1432      * Returns description of method parameters
1433      *
1434      * @return external_function_parameters
1435      * @since Moodle 2.3
1436      */
1437     public static function get_categories_parameters() {
1438         return new external_function_parameters(
1439             array(
1440                 'criteria' => new external_multiple_structure(
1441                     new external_single_structure(
1442                         array(
1443                             'key' => new external_value(PARAM_ALPHA,
1444                                          'The category column to search, expected keys (value format) are:'.
1445                                          '"id" (int) the category id,'.
1446                                          '"name" (string) the category name,'.
1447                                          '"parent" (int) the parent category id,'.
1448                                          '"idnumber" (string) category idnumber'.
1449                                          ' - user must have \'moodle/category:manage\' to search on idnumber,'.
1450                                          '"visible" (int) whether the returned categories must be visible or hidden. If the key is not passed,
1451                                              then the function return all categories that the user can see.'.
1452                                          ' - user must have \'moodle/category:manage\' or \'moodle/category:viewhiddencategories\' to search on visible,'.
1453                                          '"theme" (string) only return the categories having this theme'.
1454                                          ' - user must have \'moodle/category:manage\' to search on theme'),
1455                             'value' => new external_value(PARAM_RAW, 'the value to match')
1456                         )
1457                     ), 'criteria', VALUE_DEFAULT, array()
1458                 ),
1459                 'addsubcategories' => new external_value(PARAM_BOOL, 'return the sub categories infos
1460                                           (1 - default) otherwise only the category info (0)', VALUE_DEFAULT, 1)
1461             )
1462         );
1463     }
1465     /**
1466      * Get categories
1467      *
1468      * @param array $criteria Criteria to match the results
1469      * @param booln $addsubcategories obtain only the category (false) or its subcategories (true - default)
1470      * @return array list of categories
1471      * @since Moodle 2.3
1472      */
1473     public static function get_categories($criteria = array(), $addsubcategories = true) {
1474         global $CFG, $DB;
1475         require_once($CFG->dirroot . "/course/lib.php");
1477         // Validate parameters.
1478         $params = self::validate_parameters(self::get_categories_parameters(),
1479                 array('criteria' => $criteria, 'addsubcategories' => $addsubcategories));
1481         // Retrieve the categories.
1482         $categories = array();
1483         if (!empty($params['criteria'])) {
1485             $conditions = array();
1486             $wheres = array();
1487             foreach ($params['criteria'] as $crit) {
1488                 $key = trim($crit['key']);
1490                 // Trying to avoid duplicate keys.
1491                 if (!isset($conditions[$key])) {
1493                     $context = context_system::instance();
1494                     $value = null;
1495                     switch ($key) {
1496                         case 'id':
1497                             $value = clean_param($crit['value'], PARAM_INT);
1498                             break;
1500                         case 'idnumber':
1501                             if (has_capability('moodle/category:manage', $context)) {
1502                                 $value = clean_param($crit['value'], PARAM_RAW);
1503                             } else {
1504                                 // We must throw an exception.
1505                                 // Otherwise the dev client would think no idnumber exists.
1506                                 throw new moodle_exception('criteriaerror',
1507                                         'webservice', '', null,
1508                                         'You don\'t have the permissions to search on the "idnumber" field.');
1509                             }
1510                             break;
1512                         case 'name':
1513                             $value = clean_param($crit['value'], PARAM_TEXT);
1514                             break;
1516                         case 'parent':
1517                             $value = clean_param($crit['value'], PARAM_INT);
1518                             break;
1520                         case 'visible':
1521                             if (has_capability('moodle/category:manage', $context)
1522                                 or has_capability('moodle/category:viewhiddencategories',
1523                                         context_system::instance())) {
1524                                 $value = clean_param($crit['value'], PARAM_INT);
1525                             } else {
1526                                 throw new moodle_exception('criteriaerror',
1527                                         'webservice', '', null,
1528                                         'You don\'t have the permissions to search on the "visible" field.');
1529                             }
1530                             break;
1532                         case 'theme':
1533                             if (has_capability('moodle/category:manage', $context)) {
1534                                 $value = clean_param($crit['value'], PARAM_THEME);
1535                             } else {
1536                                 throw new moodle_exception('criteriaerror',
1537                                         'webservice', '', null,
1538                                         'You don\'t have the permissions to search on the "theme" field.');
1539                             }
1540                             break;
1542                         default:
1543                             throw new moodle_exception('criteriaerror',
1544                                     'webservice', '', null,
1545                                     'You can not search on this criteria: ' . $key);
1546                     }
1548                     if (isset($value)) {
1549                         $conditions[$key] = $crit['value'];
1550                         $wheres[] = $key . " = :" . $key;
1551                     }
1552                 }
1553             }
1555             if (!empty($wheres)) {
1556                 $wheres = implode(" AND ", $wheres);
1558                 $categories = $DB->get_records_select('course_categories', $wheres, $conditions);
1560                 // Retrieve its sub subcategories (all levels).
1561                 if ($categories and !empty($params['addsubcategories'])) {
1562                     $newcategories = array();
1564                     // Check if we required visible/theme checks.
1565                     $additionalselect = '';
1566                     $additionalparams = array();
1567                     if (isset($conditions['visible'])) {
1568                         $additionalselect .= ' AND visible = :visible';
1569                         $additionalparams['visible'] = $conditions['visible'];
1570                     }
1571                     if (isset($conditions['theme'])) {
1572                         $additionalselect .= ' AND theme= :theme';
1573                         $additionalparams['theme'] = $conditions['theme'];
1574                     }
1576                     foreach ($categories as $category) {
1577                         $sqlselect = $DB->sql_like('path', ':path') . $additionalselect;
1578                         $sqlparams = array('path' => $category->path.'/%') + $additionalparams; // It will NOT include the specified category.
1579                         $subcategories = $DB->get_records_select('course_categories', $sqlselect, $sqlparams);
1580                         $newcategories = $newcategories + $subcategories;   // Both arrays have integer as keys.
1581                     }
1582                     $categories = $categories + $newcategories;
1583                 }
1584             }
1586         } else {
1587             // Retrieve all categories in the database.
1588             $categories = $DB->get_records('course_categories');
1589         }
1591         // The not returned categories. key => category id, value => reason of exclusion.
1592         $excludedcats = array();
1594         // The returned categories.
1595         $categoriesinfo = array();
1597         // We need to sort the categories by path.
1598         // The parent cats need to be checked by the algo first.
1599         usort($categories, "core_course_external::compare_categories_by_path");
1601         foreach ($categories as $category) {
1603             // Check if the category is a child of an excluded category, if yes exclude it too (excluded => do not return).
1604             $parents = explode('/', $category->path);
1605             unset($parents[0]); // First key is always empty because path start with / => /1/2/4.
1606             foreach ($parents as $parentid) {
1607                 // Note: when the parent exclusion was due to the context,
1608                 // the sub category could still be returned.
1609                 if (isset($excludedcats[$parentid]) and $excludedcats[$parentid] != 'context') {
1610                     $excludedcats[$category->id] = 'parent';
1611                 }
1612             }
1614             // Check category depth is <= maxdepth (do not check for user who can manage categories).
1615             if ((!empty($CFG->maxcategorydepth) && count($parents) > $CFG->maxcategorydepth)
1616                     and !has_capability('moodle/category:manage', $context)) {
1617                 $excludedcats[$category->id] = 'depth';
1618             }
1620             // Check the user can use the category context.
1621             $context = context_coursecat::instance($category->id);
1622             try {
1623                 self::validate_context($context);
1624             } catch (Exception $e) {
1625                 $excludedcats[$category->id] = 'context';
1627                 // If it was the requested category then throw an exception.
1628                 if (isset($params['categoryid']) && $category->id == $params['categoryid']) {
1629                     $exceptionparam = new stdClass();
1630                     $exceptionparam->message = $e->getMessage();
1631                     $exceptionparam->catid = $category->id;
1632                     throw new moodle_exception('errorcatcontextnotvalid', 'webservice', '', $exceptionparam);
1633                 }
1634             }
1636             // Return the category information.
1637             if (!isset($excludedcats[$category->id])) {
1639                 // Final check to see if the category is visible to the user.
1640                 if ($category->visible
1641                         or has_capability('moodle/category:viewhiddencategories', context_system::instance())
1642                         or has_capability('moodle/category:manage', $context)) {
1644                     $categoryinfo = array();
1645                     $categoryinfo['id'] = $category->id;
1646                     $categoryinfo['name'] = $category->name;
1647                     list($categoryinfo['description'], $categoryinfo['descriptionformat']) =
1648                         external_format_text($category->description, $category->descriptionformat,
1649                                 $context->id, 'coursecat', 'description', null);
1650                     $categoryinfo['parent'] = $category->parent;
1651                     $categoryinfo['sortorder'] = $category->sortorder;
1652                     $categoryinfo['coursecount'] = $category->coursecount;
1653                     $categoryinfo['depth'] = $category->depth;
1654                     $categoryinfo['path'] = $category->path;
1656                     // Some fields only returned for admin.
1657                     if (has_capability('moodle/category:manage', $context)) {
1658                         $categoryinfo['idnumber'] = $category->idnumber;
1659                         $categoryinfo['visible'] = $category->visible;
1660                         $categoryinfo['visibleold'] = $category->visibleold;
1661                         $categoryinfo['timemodified'] = $category->timemodified;
1662                         $categoryinfo['theme'] = $category->theme;
1663                     }
1665                     $categoriesinfo[] = $categoryinfo;
1666                 } else {
1667                     $excludedcats[$category->id] = 'visibility';
1668                 }
1669             }
1670         }
1672         // Sorting the resulting array so it looks a bit better for the client developer.
1673         usort($categoriesinfo, "core_course_external::compare_categories_by_sortorder");
1675         return $categoriesinfo;
1676     }
1678     /**
1679      * Sort categories array by path
1680      * private function: only used by get_categories
1681      *
1682      * @param array $category1
1683      * @param array $category2
1684      * @return int result of strcmp
1685      * @since Moodle 2.3
1686      */
1687     private static function compare_categories_by_path($category1, $category2) {
1688         return strcmp($category1->path, $category2->path);
1689     }
1691     /**
1692      * Sort categories array by sortorder
1693      * private function: only used by get_categories
1694      *
1695      * @param array $category1
1696      * @param array $category2
1697      * @return int result of strcmp
1698      * @since Moodle 2.3
1699      */
1700     private static function compare_categories_by_sortorder($category1, $category2) {
1701         return strcmp($category1['sortorder'], $category2['sortorder']);
1702     }
1704     /**
1705      * Returns description of method result value
1706      *
1707      * @return external_description
1708      * @since Moodle 2.3
1709      */
1710     public static function get_categories_returns() {
1711         return new external_multiple_structure(
1712             new external_single_structure(
1713                 array(
1714                     'id' => new external_value(PARAM_INT, 'category id'),
1715                     'name' => new external_value(PARAM_TEXT, 'category name'),
1716                     'idnumber' => new external_value(PARAM_RAW, 'category id number', VALUE_OPTIONAL),
1717                     'description' => new external_value(PARAM_RAW, 'category description'),
1718                     'descriptionformat' => new external_format_value('description'),
1719                     'parent' => new external_value(PARAM_INT, 'parent category id'),
1720                     'sortorder' => new external_value(PARAM_INT, 'category sorting order'),
1721                     'coursecount' => new external_value(PARAM_INT, 'number of courses in this category'),
1722                     'visible' => new external_value(PARAM_INT, '1: available, 0:not available', VALUE_OPTIONAL),
1723                     'visibleold' => new external_value(PARAM_INT, '1: available, 0:not available', VALUE_OPTIONAL),
1724                     'timemodified' => new external_value(PARAM_INT, 'timestamp', VALUE_OPTIONAL),
1725                     'depth' => new external_value(PARAM_INT, 'category depth'),
1726                     'path' => new external_value(PARAM_TEXT, 'category path'),
1727                     'theme' => new external_value(PARAM_THEME, 'category theme', VALUE_OPTIONAL),
1728                 ), 'List of categories'
1729             )
1730         );
1731     }
1733     /**
1734      * Returns description of method parameters
1735      *
1736      * @return external_function_parameters
1737      * @since Moodle 2.3
1738      */
1739     public static function create_categories_parameters() {
1740         return new external_function_parameters(
1741             array(
1742                 'categories' => new external_multiple_structure(
1743                         new external_single_structure(
1744                             array(
1745                                 'name' => new external_value(PARAM_TEXT, 'new category name'),
1746                                 'parent' => new external_value(PARAM_INT,
1747                                         'the parent category id inside which the new category will be created
1748                                          - set to 0 for a root category',
1749                                         VALUE_DEFAULT, 0),
1750                                 'idnumber' => new external_value(PARAM_RAW,
1751                                         'the new category idnumber', VALUE_OPTIONAL),
1752                                 'description' => new external_value(PARAM_RAW,
1753                                         'the new category description', VALUE_OPTIONAL),
1754                                 'descriptionformat' => new external_format_value('description', VALUE_DEFAULT),
1755                                 'theme' => new external_value(PARAM_THEME,
1756                                         'the new category theme. This option must be enabled on moodle',
1757                                         VALUE_OPTIONAL),
1758                         )
1759                     )
1760                 )
1761             )
1762         );
1763     }
1765     /**
1766      * Create categories
1767      *
1768      * @param array $categories - see create_categories_parameters() for the array structure
1769      * @return array - see create_categories_returns() for the array structure
1770      * @since Moodle 2.3
1771      */
1772     public static function create_categories($categories) {
1773         global $CFG, $DB;
1774         require_once($CFG->libdir . "/coursecatlib.php");
1776         $params = self::validate_parameters(self::create_categories_parameters(),
1777                         array('categories' => $categories));
1779         $transaction = $DB->start_delegated_transaction();
1781         $createdcategories = array();
1782         foreach ($params['categories'] as $category) {
1783             if ($category['parent']) {
1784                 if (!$DB->record_exists('course_categories', array('id' => $category['parent']))) {
1785                     throw new moodle_exception('unknowcategory');
1786                 }
1787                 $context = context_coursecat::instance($category['parent']);
1788             } else {
1789                 $context = context_system::instance();
1790             }
1791             self::validate_context($context);
1792             require_capability('moodle/category:manage', $context);
1794             // this will validate format and throw an exception if there are errors
1795             external_validate_format($category['descriptionformat']);
1797             $newcategory = coursecat::create($category);
1799             $createdcategories[] = array('id' => $newcategory->id, 'name' => $newcategory->name);
1800         }
1802         $transaction->allow_commit();
1804         return $createdcategories;
1805     }
1807     /**
1808      * Returns description of method parameters
1809      *
1810      * @return external_function_parameters
1811      * @since Moodle 2.3
1812      */
1813     public static function create_categories_returns() {
1814         return new external_multiple_structure(
1815             new external_single_structure(
1816                 array(
1817                     'id' => new external_value(PARAM_INT, 'new category id'),
1818                     'name' => new external_value(PARAM_TEXT, 'new category name'),
1819                 )
1820             )
1821         );
1822     }
1824     /**
1825      * Returns description of method parameters
1826      *
1827      * @return external_function_parameters
1828      * @since Moodle 2.3
1829      */
1830     public static function update_categories_parameters() {
1831         return new external_function_parameters(
1832             array(
1833                 'categories' => new external_multiple_structure(
1834                     new external_single_structure(
1835                         array(
1836                             'id'       => new external_value(PARAM_INT, 'course id'),
1837                             'name' => new external_value(PARAM_TEXT, 'category name', VALUE_OPTIONAL),
1838                             'idnumber' => new external_value(PARAM_RAW, 'category id number', VALUE_OPTIONAL),
1839                             'parent' => new external_value(PARAM_INT, 'parent category id', VALUE_OPTIONAL),
1840                             'description' => new external_value(PARAM_RAW, 'category description', VALUE_OPTIONAL),
1841                             'descriptionformat' => new external_format_value('description', VALUE_DEFAULT),
1842                             'theme' => new external_value(PARAM_THEME,
1843                                     'the category theme. This option must be enabled on moodle', VALUE_OPTIONAL),
1844                         )
1845                     )
1846                 )
1847             )
1848         );
1849     }
1851     /**
1852      * Update categories
1853      *
1854      * @param array $categories The list of categories to update
1855      * @return null
1856      * @since Moodle 2.3
1857      */
1858     public static function update_categories($categories) {
1859         global $CFG, $DB;
1860         require_once($CFG->libdir . "/coursecatlib.php");
1862         // Validate parameters.
1863         $params = self::validate_parameters(self::update_categories_parameters(), array('categories' => $categories));
1865         $transaction = $DB->start_delegated_transaction();
1867         foreach ($params['categories'] as $cat) {
1868             $category = coursecat::get($cat['id']);
1870             $categorycontext = context_coursecat::instance($cat['id']);
1871             self::validate_context($categorycontext);
1872             require_capability('moodle/category:manage', $categorycontext);
1874             // this will throw an exception if descriptionformat is not valid
1875             external_validate_format($cat['descriptionformat']);
1877             $category->update($cat);
1878         }
1880         $transaction->allow_commit();
1881     }
1883     /**
1884      * Returns description of method result value
1885      *
1886      * @return external_description
1887      * @since Moodle 2.3
1888      */
1889     public static function update_categories_returns() {
1890         return null;
1891     }
1893     /**
1894      * Returns description of method parameters
1895      *
1896      * @return external_function_parameters
1897      * @since Moodle 2.3
1898      */
1899     public static function delete_categories_parameters() {
1900         return new external_function_parameters(
1901             array(
1902                 'categories' => new external_multiple_structure(
1903                     new external_single_structure(
1904                         array(
1905                             'id' => new external_value(PARAM_INT, 'category id to delete'),
1906                             'newparent' => new external_value(PARAM_INT,
1907                                 'the parent category to move the contents to, if specified', VALUE_OPTIONAL),
1908                             'recursive' => new external_value(PARAM_BOOL, '1: recursively delete all contents inside this
1909                                 category, 0 (default): move contents to newparent or current parent category (except if parent is root)', VALUE_DEFAULT, 0)
1910                         )
1911                     )
1912                 )
1913             )
1914         );
1915     }
1917     /**
1918      * Delete categories
1919      *
1920      * @param array $categories A list of category ids
1921      * @return array
1922      * @since Moodle 2.3
1923      */
1924     public static function delete_categories($categories) {
1925         global $CFG, $DB;
1926         require_once($CFG->dirroot . "/course/lib.php");
1927         require_once($CFG->libdir . "/coursecatlib.php");
1929         // Validate parameters.
1930         $params = self::validate_parameters(self::delete_categories_parameters(), array('categories' => $categories));
1932         $transaction = $DB->start_delegated_transaction();
1934         foreach ($params['categories'] as $category) {
1935             $deletecat = coursecat::get($category['id'], MUST_EXIST);
1936             $context = context_coursecat::instance($deletecat->id);
1937             require_capability('moodle/category:manage', $context);
1938             self::validate_context($context);
1939             self::validate_context(get_category_or_system_context($deletecat->parent));
1941             if ($category['recursive']) {
1942                 // If recursive was specified, then we recursively delete the category's contents.
1943                 if ($deletecat->can_delete_full()) {
1944                     $deletecat->delete_full(false);
1945                 } else {
1946                     throw new moodle_exception('youcannotdeletecategory', '', '', $deletecat->get_formatted_name());
1947                 }
1948             } else {
1949                 // In this situation, we don't delete the category's contents, we either move it to newparent or parent.
1950                 // If the parent is the root, moving is not supported (because a course must always be inside a category).
1951                 // We must move to an existing category.
1952                 if (!empty($category['newparent'])) {
1953                     $newparentcat = coursecat::get($category['newparent']);
1954                 } else {
1955                     $newparentcat = coursecat::get($deletecat->parent);
1956                 }
1958                 // This operation is not allowed. We must move contents to an existing category.
1959                 if (!$newparentcat->id) {
1960                     throw new moodle_exception('movecatcontentstoroot');
1961                 }
1963                 self::validate_context(context_coursecat::instance($newparentcat->id));
1964                 if ($deletecat->can_move_content_to($newparentcat->id)) {
1965                     $deletecat->delete_move($newparentcat->id, false);
1966                 } else {
1967                     throw new moodle_exception('youcannotdeletecategory', '', '', $deletecat->get_formatted_name());
1968                 }
1969             }
1970         }
1972         $transaction->allow_commit();
1973     }
1975     /**
1976      * Returns description of method parameters
1977      *
1978      * @return external_function_parameters
1979      * @since Moodle 2.3
1980      */
1981     public static function delete_categories_returns() {
1982         return null;
1983     }
1985     /**
1986      * Describes the parameters for delete_modules.
1987      *
1988      * @return external_external_function_parameters
1989      * @since Moodle 2.5
1990      */
1991     public static function delete_modules_parameters() {
1992         return new external_function_parameters (
1993             array(
1994                 'cmids' => new external_multiple_structure(new external_value(PARAM_INT, 'course module ID',
1995                         VALUE_REQUIRED, '', NULL_NOT_ALLOWED), 'Array of course module IDs'),
1996             )
1997         );
1998     }
2000     /**
2001      * Deletes a list of provided module instances.
2002      *
2003      * @param array $cmids the course module ids
2004      * @since Moodle 2.5
2005      */
2006     public static function delete_modules($cmids) {
2007         global $CFG, $DB;
2009         // Require course file containing the course delete module function.
2010         require_once($CFG->dirroot . "/course/lib.php");
2012         // Clean the parameters.
2013         $params = self::validate_parameters(self::delete_modules_parameters(), array('cmids' => $cmids));
2015         // Keep track of the course ids we have performed a capability check on to avoid repeating.
2016         $arrcourseschecked = array();
2018         foreach ($params['cmids'] as $cmid) {
2019             // Get the course module.
2020             $cm = $DB->get_record('course_modules', array('id' => $cmid), '*', MUST_EXIST);
2022             // Check if we have not yet confirmed they have permission in this course.
2023             if (!in_array($cm->course, $arrcourseschecked)) {
2024                 // Ensure the current user has required permission in this course.
2025                 $context = context_course::instance($cm->course);
2026                 self::validate_context($context);
2027                 // Add to the array.
2028                 $arrcourseschecked[] = $cm->course;
2029             }
2031             // Ensure they can delete this module.
2032             $modcontext = context_module::instance($cm->id);
2033             require_capability('moodle/course:manageactivities', $modcontext);
2035             // Delete the module.
2036             course_delete_module($cm->id);
2037         }
2038     }
2040     /**
2041      * Describes the delete_modules return value.
2042      *
2043      * @return external_single_structure
2044      * @since Moodle 2.5
2045      */
2046     public static function delete_modules_returns() {
2047         return null;
2048     }
2050     /**
2051      * Returns description of method parameters
2052      *
2053      * @return external_function_parameters
2054      * @since Moodle 2.9
2055      */
2056     public static function view_course_parameters() {
2057         return new external_function_parameters(
2058             array(
2059                 'courseid' => new external_value(PARAM_INT, 'id of the course'),
2060                 'sectionnumber' => new external_value(PARAM_INT, 'section number', VALUE_DEFAULT, 0)
2061             )
2062         );
2063     }
2065     /**
2066      * Trigger the course viewed event.
2067      *
2068      * @param int $courseid id of course
2069      * @param int $sectionnumber sectionnumber (0, 1, 2...)
2070      * @return array of warnings and status result
2071      * @since Moodle 2.9
2072      * @throws moodle_exception
2073      */
2074     public static function view_course($courseid, $sectionnumber = 0) {
2075         global $CFG;
2076         require_once($CFG->dirroot . "/course/lib.php");
2078         $params = self::validate_parameters(self::view_course_parameters(),
2079                                             array(
2080                                                 'courseid' => $courseid,
2081                                                 'sectionnumber' => $sectionnumber
2082                                             ));
2084         $warnings = array();
2086         $course = get_course($params['courseid']);
2087         $context = context_course::instance($course->id);
2088         self::validate_context($context);
2090         if (!empty($params['sectionnumber'])) {
2092             // Get section details and check it exists.
2093             $modinfo = get_fast_modinfo($course);
2094             $coursesection = $modinfo->get_section_info($params['sectionnumber'], MUST_EXIST);
2096             // Check user is allowed to see it.
2097             if (!$coursesection->uservisible) {
2098                 require_capability('moodle/course:viewhiddensections', $context);
2099             }
2100         }
2102         course_view($context, $params['sectionnumber']);
2104         $result = array();
2105         $result['status'] = true;
2106         $result['warnings'] = $warnings;
2107         return $result;
2108     }
2110     /**
2111      * Returns description of method result value
2112      *
2113      * @return external_description
2114      * @since Moodle 2.9
2115      */
2116     public static function view_course_returns() {
2117         return new external_single_structure(
2118             array(
2119                 'status' => new external_value(PARAM_BOOL, 'status: true if success'),
2120                 'warnings' => new external_warnings()
2121             )
2122         );
2123     }
2125     /**
2126      * Returns description of method parameters
2127      *
2128      * @return external_function_parameters
2129      * @since Moodle 3.0
2130      */
2131     public static function search_courses_parameters() {
2132         return new external_function_parameters(
2133             array(
2134                 'criterianame'  => new external_value(PARAM_ALPHA, 'criteria name
2135                                                         (search, modulelist (only admins), blocklist (only admins), tagid)'),
2136                 'criteriavalue' => new external_value(PARAM_RAW, 'criteria value'),
2137                 'page'          => new external_value(PARAM_INT, 'page number (0 based)', VALUE_DEFAULT, 0),
2138                 'perpage'       => new external_value(PARAM_INT, 'items per page', VALUE_DEFAULT, 0),
2139                 'requiredcapabilities' => new external_multiple_structure(
2140                     new external_value(PARAM_CAPABILITY, 'Capability string used to filter courses by permission'),
2141                     VALUE_OPTIONAL
2142                 )
2143             )
2144         );
2145     }
2147     /**
2148      * Search courses following the specified criteria.
2149      *
2150      * @param string $criterianame  Criteria name (search, modulelist (only admins), blocklist (only admins), tagid)
2151      * @param string $criteriavalue Criteria value
2152      * @param int $page             Page number (for pagination)
2153      * @param int $perpage          Items per page
2154      * @param array $requiredcapabilities Optional list of required capabilities (used to filter the list).
2155      * @return array of course objects and warnings
2156      * @since Moodle 3.0
2157      * @throws moodle_exception
2158      */
2159     public static function search_courses($criterianame,
2160                                           $criteriavalue,
2161                                           $page=0,
2162                                           $perpage=0,
2163                                           $requiredcapabilities=array()) {
2164         global $CFG;
2165         require_once($CFG->libdir . '/coursecatlib.php');
2167         $warnings = array();
2169         $parameters = array(
2170             'criterianame'  => $criterianame,
2171             'criteriavalue' => $criteriavalue,
2172             'page'          => $page,
2173             'perpage'       => $perpage,
2174             'requiredcapabilities' => $requiredcapabilities
2175         );
2176         $params = self::validate_parameters(self::search_courses_parameters(), $parameters);
2178         $allowedcriterianames = array('search', 'modulelist', 'blocklist', 'tagid');
2179         if (!in_array($params['criterianame'], $allowedcriterianames)) {
2180             throw new invalid_parameter_exception('Invalid value for criterianame parameter (value: '.$params['criterianame'].'),' .
2181                 'allowed values are: '.implode(',', $allowedcriterianames));
2182         }
2184         if ($params['criterianame'] == 'modulelist' or $params['criterianame'] == 'blocklist') {
2185             require_capability('moodle/site:config', context_system::instance());
2186         }
2188         $paramtype = array(
2189             'search' => PARAM_RAW,
2190             'modulelist' => PARAM_PLUGIN,
2191             'blocklist' => PARAM_INT,
2192             'tagid' => PARAM_INT
2193         );
2194         $params['criteriavalue'] = clean_param($params['criteriavalue'], $paramtype[$params['criterianame']]);
2196         // Prepare the search API options.
2197         $searchcriteria = array();
2198         $searchcriteria[$params['criterianame']] = $params['criteriavalue'];
2200         $options = array();
2201         if ($params['perpage'] != 0) {
2202             $offset = $params['page'] * $params['perpage'];
2203             $options = array('offset' => $offset, 'limit' => $params['perpage']);
2204         }
2206         // Search the courses.
2207         $courses = coursecat::search_courses($searchcriteria, $options, $params['requiredcapabilities']);
2208         $totalcount = coursecat::search_courses_count($searchcriteria, $options, $params['requiredcapabilities']);
2210         $finalcourses = array();
2211         $categoriescache = array();
2213         foreach ($courses as $course) {
2215             $coursecontext = context_course::instance($course->id);
2217             // Category information.
2218             if (!isset($categoriescache[$course->category])) {
2219                 $categoriescache[$course->category] = coursecat::get($course->category);
2220             }
2221             $category = $categoriescache[$course->category];
2223             // Retrieve course overfiew used files.
2224             $files = array();
2225             foreach ($course->get_course_overviewfiles() as $file) {
2226                 $fileurl = moodle_url::make_webservice_pluginfile_url($file->get_contextid(), $file->get_component(),
2227                                                                         $file->get_filearea(), null, $file->get_filepath(),
2228                                                                         $file->get_filename())->out(false);
2229                 $files[] = array(
2230                     'filename' => $file->get_filename(),
2231                     'fileurl' => $fileurl,
2232                     'filesize' => $file->get_filesize()
2233                 );
2234             }
2236             // Retrieve the course contacts,
2237             // we need here the users fullname since if we are not enrolled can be difficult to obtain them via other Web Services.
2238             $coursecontacts = array();
2239             foreach ($course->get_course_contacts() as $contact) {
2240                  $coursecontacts[] = array(
2241                     'id' => $contact['user']->id,
2242                     'fullname' => $contact['username']
2243                 );
2244             }
2246             // Allowed enrolment methods (maybe we can self-enrol).
2247             $enroltypes = array();
2248             $instances = enrol_get_instances($course->id, true);
2249             foreach ($instances as $instance) {
2250                 $enroltypes[] = $instance->enrol;
2251             }
2253             // Format summary.
2254             list($summary, $summaryformat) =
2255                 external_format_text($course->summary, $course->summaryformat, $coursecontext->id, 'course', 'summary', null);
2257             $displayname = get_course_display_name_for_list($course);
2258             $coursereturns = array();
2259             $coursereturns['id']                = $course->id;
2260             $coursereturns['fullname']          = external_format_string($course->fullname, $coursecontext->id);
2261             $coursereturns['displayname']       = external_format_string($displayname, $coursecontext->id);
2262             $coursereturns['shortname']         = external_format_string($course->shortname, $coursecontext->id);
2263             $coursereturns['categoryid']        = $course->category;
2264             $coursereturns['categoryname']      = $category->name;
2265             $coursereturns['summary']           = $summary;
2266             $coursereturns['summaryformat']     = $summaryformat;
2267             $coursereturns['overviewfiles']     = $files;
2268             $coursereturns['contacts']          = $coursecontacts;
2269             $coursereturns['enrollmentmethods'] = $enroltypes;
2270             $finalcourses[] = $coursereturns;
2271         }
2273         return array(
2274             'total' => $totalcount,
2275             'courses' => $finalcourses,
2276             'warnings' => $warnings
2277         );
2278     }
2280     /**
2281      * Returns description of method result value
2282      *
2283      * @return external_description
2284      * @since Moodle 3.0
2285      */
2286     public static function search_courses_returns() {
2288         return new external_single_structure(
2289             array(
2290                 'total' => new external_value(PARAM_INT, 'total course count'),
2291                 'courses' => new external_multiple_structure(
2292                     new external_single_structure(
2293                         array(
2294                             'id' => new external_value(PARAM_INT, 'course id'),
2295                             'fullname' => new external_value(PARAM_TEXT, 'course full name'),
2296                             'displayname' => new external_value(PARAM_TEXT, 'course display name'),
2297                             'shortname' => new external_value(PARAM_TEXT, 'course short name'),
2298                             'categoryid' => new external_value(PARAM_INT, 'category id'),
2299                             'categoryname' => new external_value(PARAM_TEXT, 'category name'),
2300                             'summary' => new external_value(PARAM_RAW, 'summary'),
2301                             'summaryformat' => new external_format_value('summary'),
2302                             'overviewfiles' => new external_multiple_structure(
2303                                 new external_single_structure(
2304                                     array(
2305                                         'filename' => new external_value(PARAM_FILE, 'overview file name'),
2306                                         'fileurl'  => new external_value(PARAM_URL, 'overview file url'),
2307                                         'filesize'  => new external_value(PARAM_INT, 'overview file size'),
2308                                     )
2309                                 ),
2310                                 'additional overview files attached to this course'
2311                             ),
2312                             'contacts' => new external_multiple_structure(
2313                                 new external_single_structure(
2314                                     array(
2315                                         'id' => new external_value(PARAM_INT, 'contact user id'),
2316                                         'fullname'  => new external_value(PARAM_NOTAGS, 'contact user fullname'),
2317                                     )
2318                                 ),
2319                                 'contact users'
2320                             ),
2321                             'enrollmentmethods' => new external_multiple_structure(
2322                                 new external_value(PARAM_PLUGIN, 'enrollment method'),
2323                                 'enrollment methods list'
2324                             ),
2325                         )
2326                     ), 'course'
2327                 ),
2328                 'warnings' => new external_warnings()
2329             )
2330         );
2331     }
2333     /**
2334      * Returns description of method parameters
2335      *
2336      * @return external_function_parameters
2337      * @since Moodle 3.0
2338      */
2339     public static function get_course_module_parameters() {
2340         return new external_function_parameters(
2341             array(
2342                 'cmid' => new external_value(PARAM_INT, 'The course module id')
2343             )
2344         );
2345     }
2347     /**
2348      * Return information about a course module.
2349      *
2350      * @param int $cmid the course module id
2351      * @return array of warnings and the course module
2352      * @since Moodle 3.0
2353      * @throws moodle_exception
2354      */
2355     public static function get_course_module($cmid) {
2357         $params = self::validate_parameters(self::get_course_module_parameters(),
2358                                             array(
2359                                                 'cmid' => $cmid,
2360                                             ));
2362         $warnings = array();
2364         $cm = get_coursemodule_from_id(null, $params['cmid'], 0, true, MUST_EXIST);
2365         $context = context_module::instance($cm->id);
2366         self::validate_context($context);
2368         // If the user has permissions to manage the activity, return all the information.
2369         if (has_capability('moodle/course:manageactivities', $context)) {
2370             $info = $cm;
2371         } else {
2372             // Return information is safe to show to any user.
2373             $info = new stdClass();
2374             $info->id = $cm->id;
2375             $info->course = $cm->course;
2376             $info->module = $cm->module;
2377             $info->modname = $cm->modname;
2378             $info->instance = $cm->instance;
2379             $info->section = $cm->section;
2380             $info->sectionnum = $cm->sectionnum;
2381             $info->groupmode = $cm->groupmode;
2382             $info->groupingid = $cm->groupingid;
2383             $info->completion = $cm->completion;
2384         }
2385         // Format name.
2386         $info->name = external_format_string($cm->name, $context->id);
2388         $result = array();
2389         $result['cm'] = $info;
2390         $result['warnings'] = $warnings;
2391         return $result;
2392     }
2394     /**
2395      * Returns description of method result value
2396      *
2397      * @return external_description
2398      * @since Moodle 3.0
2399      */
2400     public static function get_course_module_returns() {
2401         return new external_single_structure(
2402             array(
2403                 'cm' => new external_single_structure(
2404                     array(
2405                         'id' => new external_value(PARAM_INT, 'The course module id'),
2406                         'course' => new external_value(PARAM_INT, 'The course id'),
2407                         'module' => new external_value(PARAM_INT, 'The module type id'),
2408                         'name' => new external_value(PARAM_RAW, 'The activity name'),
2409                         'modname' => new external_value(PARAM_COMPONENT, 'The module component name (forum, assign, etc..)'),
2410                         'instance' => new external_value(PARAM_INT, 'The activity instance id'),
2411                         'section' => new external_value(PARAM_INT, 'The module section id'),
2412                         'sectionnum' => new external_value(PARAM_INT, 'The module section number'),
2413                         'groupmode' => new external_value(PARAM_INT, 'Group mode'),
2414                         'groupingid' => new external_value(PARAM_INT, 'Grouping id'),
2415                         'completion' => new external_value(PARAM_INT, 'If completion is enabled'),
2416                         'idnumber' => new external_value(PARAM_RAW, 'Module id number', VALUE_OPTIONAL),
2417                         'added' => new external_value(PARAM_INT, 'Time added', VALUE_OPTIONAL),
2418                         'score' => new external_value(PARAM_INT, 'Score', VALUE_OPTIONAL),
2419                         'indent' => new external_value(PARAM_INT, 'Indentation', VALUE_OPTIONAL),
2420                         'visible' => new external_value(PARAM_INT, 'If visible', VALUE_OPTIONAL),
2421                         'visibleold' => new external_value(PARAM_INT, 'Visible old', VALUE_OPTIONAL),
2422                         'completiongradeitemnumber' => new external_value(PARAM_INT, 'Completion grade item', VALUE_OPTIONAL),
2423                         'completionview' => new external_value(PARAM_INT, 'Completion view setting', VALUE_OPTIONAL),
2424                         'completionexpected' => new external_value(PARAM_INT, 'Completion time expected', VALUE_OPTIONAL),
2425                         'showdescription' => new external_value(PARAM_INT, 'If the description is showed', VALUE_OPTIONAL),
2426                         'availability' => new external_value(PARAM_RAW, 'Availability settings', VALUE_OPTIONAL),
2427                     )
2428                 ),
2429                 'warnings' => new external_warnings()
2430             )
2431         );
2432     }
2434     /**
2435      * Returns description of method parameters
2436      *
2437      * @return external_function_parameters
2438      * @since Moodle 3.0
2439      */
2440     public static function get_course_module_by_instance_parameters() {
2441         return new external_function_parameters(
2442             array(
2443                 'module' => new external_value(PARAM_COMPONENT, 'The module name'),
2444                 'instance' => new external_value(PARAM_INT, 'The module instance id')
2445             )
2446         );
2447     }
2449     /**
2450      * Return information about a course module.
2451      *
2452      * @param string $module the module name
2453      * @param int $instance the activity instance id
2454      * @return array of warnings and the course module
2455      * @since Moodle 3.0
2456      * @throws moodle_exception
2457      */
2458     public static function get_course_module_by_instance($module, $instance) {
2460         $params = self::validate_parameters(self::get_course_module_by_instance_parameters(),
2461                                             array(
2462                                                 'module' => $module,
2463                                                 'instance' => $instance,
2464                                             ));
2466         $warnings = array();
2467         $cm = get_coursemodule_from_instance($params['module'], $params['instance'], 0, false, MUST_EXIST);
2469         return self::get_course_module($cm->id);
2470     }
2472     /**
2473      * Returns description of method result value
2474      *
2475      * @return external_description
2476      * @since Moodle 3.0
2477      */
2478     public static function get_course_module_by_instance_returns() {
2479         return self::get_course_module_returns();
2480     }
2484 /**
2485  * Deprecated course external functions
2486  *
2487  * @package    core_course
2488  * @copyright  2009 Petr Skodak
2489  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2490  * @since Moodle 2.0
2491  * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
2492  * @see core_course_external
2493  */
2494 class moodle_course_external extends external_api {
2496     /**
2497      * Returns description of method parameters
2498      *
2499      * @return external_function_parameters
2500      * @since Moodle 2.0
2501      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
2502      * @see core_course_external::get_courses_parameters()
2503      */
2504     public static function get_courses_parameters() {
2505         return core_course_external::get_courses_parameters();
2506     }
2508     /**
2509      * Get courses
2510      *
2511      * @param array $options
2512      * @return array
2513      * @since Moodle 2.0
2514      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
2515      * @see core_course_external::get_courses()
2516      */
2517     public static function get_courses($options) {
2518         return core_course_external::get_courses($options);
2519     }
2521     /**
2522      * Returns description of method result value
2523      *
2524      * @return external_description
2525      * @since Moodle 2.0
2526      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
2527      * @see core_course_external::get_courses_returns()
2528      */
2529     public static function get_courses_returns() {
2530         return core_course_external::get_courses_returns();
2531     }
2533     /**
2534      * Marking the method as deprecated.
2535      *
2536      * @return bool
2537      */
2538     public static function get_courses_is_deprecated() {
2539         return true;
2540     }
2542     /**
2543      * Returns description of method parameters
2544      *
2545      * @return external_function_parameters
2546      * @since Moodle 2.0
2547      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
2548      * @see core_course_external::create_courses_parameters()
2549      */
2550     public static function create_courses_parameters() {
2551         return core_course_external::create_courses_parameters();
2552     }
2554     /**
2555      * Create  courses
2556      *
2557      * @param array $courses
2558      * @return array courses (id and shortname only)
2559      * @since Moodle 2.0
2560      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
2561      * @see core_course_external::create_courses()
2562      */
2563     public static function create_courses($courses) {
2564         return core_course_external::create_courses($courses);
2565     }
2567     /**
2568      * Returns description of method result value
2569      *
2570      * @return external_description
2571      * @since Moodle 2.0
2572      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
2573      * @see core_course_external::create_courses_returns()
2574      */
2575     public static function create_courses_returns() {
2576         return core_course_external::create_courses_returns();
2577     }
2579     /**
2580      * Marking the method as deprecated.
2581      *
2582      * @return bool
2583      */
2584     public static function create_courses_is_deprecated() {
2585         return true;
2586     }