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/>.
  16
  17
  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  */
  26
  27 defined('MOODLE_INTERNAL') || die;
  28
  29 use core_course\external\course_summary_exporter;
  30
  31 require_once("$CFG->libdir/externallib.php");
  32 require_once("lib.php");
  33
  34 /**
  35  * Course external functions
  36  *
  37  * @package    core_course
  38  * @category   external
  39  * @copyright  2011 Jerome Mouneyrac
  40  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  41  * @since Moodle 2.2
  42  */
  43 class core_course_external extends external_api {
  44
  45     /**
  46      * Returns description of method parameters
  47      *
  48      * @return external_function_parameters
  49      * @since Moodle 2.9 Options available
  50      * @since Moodle 2.2
  51      */
  52     public static function get_course_contents_parameters() {
  53         return new external_function_parameters(
  54                 array('courseid' => new external_value(PARAM_INT, 'course id'),
  55                       'options' => new external_multiple_structure (
  56                               new external_single_structure(
  57                                 array(
  58                                     'name' => new external_value(PARAM_ALPHANUM,
  59                                                 'The expected keys (value format) are:
  60                                                 excludemodules (bool) Do not return modules, return only the sections structure
  61                                                 excludecontents (bool) Do not return module contents (i.e: files inside a resource)
  62                                                 includestealthmodules (bool) Return stealth modules for students in a special
  63                                                     section (with id -1)
  64                                                 sectionid (int) Return only this section
  65                                                 sectionnumber (int) Return only this section with number (order)
  66                                                 cmid (int) Return only this module information (among the whole sections structure)
  67                                                 modname (string) Return only modules with this name "label, forum, etc..."
  68                                                 modid (int) Return only the module with this id (to be used with modname'),
  69                                     'value' => new external_value(PARAM_RAW, 'the value of the option,
  70                                                                     this param is personaly validated in the external function.')
  71                               )
  72                       ), 'Options, used since Moodle 2.9', VALUE_DEFAULT, array())
  73                 )
  74         );
  75     }
  76
  77     /**
  78      * Get course contents
  79      *
  80      * @param int $courseid course id
  81      * @param array $options Options for filtering the results, used since Moodle 2.9
  82      * @return array
  83      * @since Moodle 2.9 Options available
  84      * @since Moodle 2.2
  85      */
  86     public static function get_course_contents($courseid, $options = array()) {
  87         global $CFG, $DB;
  88         require_once($CFG->dirroot . "/course/lib.php");
  89         require_once($CFG->libdir . '/completionlib.php');
  90
  91         //validate parameter
  92         $params = self::validate_parameters(self::get_course_contents_parameters(),
  93                         array('courseid' => $courseid, 'options' => $options));
  94
  95         $filters = array();
  96         if (!empty($params['options'])) {
  97
  98             foreach ($params['options'] as $option) {
  99                 $name = trim($option['name']);
 100                 // Avoid duplicated options.
 101                 if (!isset($filters[$name])) {
 102                     switch ($name) {
 103                         case 'excludemodules':
 104                         case 'excludecontents':
 105                         case 'includestealthmodules':
 106                             $value = clean_param($option['value'], PARAM_BOOL);
 107                             $filters[$name] = $value;
 108                             break;
 109                         case 'sectionid':
 110                         case 'sectionnumber':
 111                         case 'cmid':
 112                         case 'modid':
 113                             $value = clean_param($option['value'], PARAM_INT);
 114                             if (is_numeric($value)) {
 115                                 $filters[$name] = $value;
 116                             } else {
 117                                 throw new moodle_exception('errorinvalidparam', 'webservice', '', $name);
 118                             }
 119                             break;
 120                         case 'modname':
 121                             $value = clean_param($option['value'], PARAM_PLUGIN);
 122                             if ($value) {
 123                                 $filters[$name] = $value;
 124                             } else {
 125                                 throw new moodle_exception('errorinvalidparam', 'webservice', '', $name);
 126                             }
 127                             break;
 128                         default:
 129                             throw new moodle_exception('errorinvalidparam', 'webservice', '', $name);
 130                     }
 131                 }
 132             }
 133         }
 134
 135         //retrieve the course
 136         $course = $DB->get_record('course', array('id' => $params['courseid']), '*', MUST_EXIST);
 137
 138         if ($course->id != SITEID) {
 139             // Check course format exist.
 140             if (!file_exists($CFG->dirroot . '/course/format/' . $course->format . '/lib.php')) {
 141                 throw new moodle_exception('cannotgetcoursecontents', 'webservice', '', null,
 142                                             get_string('courseformatnotfound', 'error', $course->format));
 143             } else {
 144                 require_once($CFG->dirroot . '/course/format/' . $course->format . '/lib.php');
 145             }
 146         }
 147
 148         // now security checks
 149         $context = context_course::instance($course->id, IGNORE_MISSING);
 150         try {
 151             self::validate_context($context);
 152         } catch (Exception $e) {
 153             $exceptionparam = new stdClass();
 154             $exceptionparam->message = $e->getMessage();
 155             $exceptionparam->courseid = $course->id;
 156             throw new moodle_exception('errorcoursecontextnotvalid', 'webservice', '', $exceptionparam);
 157         }
 158
 159         $canupdatecourse = has_capability('moodle/course:update', $context);
 160
 161         //create return value
 162         $coursecontents = array();
 163
 164         if ($canupdatecourse or $course->visible
 165                 or has_capability('moodle/course:viewhiddencourses', $context)) {
 166
 167             //retrieve sections
 168             $modinfo = get_fast_modinfo($course);
 169             $sections = $modinfo->get_section_info_all();
 170             $coursenumsections = course_get_format($course)->get_last_section_number();
 171             $stealthmodules = array();   // Array to keep all the modules available but not visible in a course section/topic.
 172
 173             $completioninfo = new completion_info($course);
 174
 175             //for each sections (first displayed to last displayed)
 176             $modinfosections = $modinfo->get_sections();
 177             foreach ($sections as $key => $section) {
 178
 179                 // This becomes true when we are filtering and we found the value to filter with.
 180                 $sectionfound = false;
 181
 182                 // Filter by section id.
 183                 if (!empty($filters['sectionid'])) {
 184                     if ($section->id != $filters['sectionid']) {
 185                         continue;
 186                     } else {
 187                         $sectionfound = true;
 188                     }
 189                 }
 190
 191                 // Filter by section number. Note that 0 is a valid section number.
 192                 if (isset($filters['sectionnumber'])) {
 193                     if ($key != $filters['sectionnumber']) {
 194                         continue;
 195                     } else {
 196                         $sectionfound = true;
 197                     }
 198                 }
 199
 200                 // reset $sectioncontents
 201                 $sectionvalues = array();
 202                 $sectionvalues['id'] = $section->id;
 203                 $sectionvalues['name'] = get_section_name($course, $section);
 204                 $sectionvalues['visible'] = $section->visible;
 205
 206                 $options = (object) array('noclean' => true);
 207                 list($sectionvalues['summary'], $sectionvalues['summaryformat']) =
 208                         external_format_text($section->summary, $section->summaryformat,
 209                                 $context->id, 'course', 'section', $section->id, $options);
 210                 $sectionvalues['section'] = $section->section;
 211                 $sectionvalues['hiddenbynumsections'] = $section->section > $coursenumsections ? 1 : 0;
 212                 $sectionvalues['uservisible'] = $section->uservisible;
 213                 if (!empty($section->availableinfo)) {
 214                     $sectionvalues['availabilityinfo'] = \core_availability\info::format_info($section->availableinfo, $course);
 215                 }
 216
 217                 $sectioncontents = array();
 218
 219                 // For each module of the section.
 220                 if (empty($filters['excludemodules']) and !empty($modinfosections[$section->section])) {
 221                     foreach ($modinfosections[$section->section] as $cmid) {
 222                         $cm = $modinfo->cms[$cmid];
 223
 224                         // Stop here if the module is not visible to the user on the course main page:
 225                         // The user can't access the module and the user can't view the module on the course page.
 226                         if (!$cm->uservisible && !$cm->is_visible_on_course_page()) {
 227                             continue;
 228                         }
 229
 230                         // This becomes true when we are filtering and we found the value to filter with.
 231                         $modfound = false;
 232
 233                         // Filter by cmid.
 234                         if (!empty($filters['cmid'])) {
 235                             if ($cmid != $filters['cmid']) {
 236                                 continue;
 237                             } else {
 238                                 $modfound = true;
 239                             }
 240                         }
 241
 242                         // Filter by module name and id.
 243                         if (!empty($filters['modname'])) {
 244                             if ($cm->modname != $filters['modname']) {
 245                                 continue;
 246                             } else if (!empty($filters['modid'])) {
 247                                 if ($cm->instance != $filters['modid']) {
 248                                     continue;
 249                                 } else {
 250                                     // Note that if we are only filtering by modname we don't break the loop.
 251                                     $modfound = true;
 252                                 }
 253                             }
 254                         }
 255
 256                         $module = array();
 257
 258                         $modcontext = context_module::instance($cm->id);
 259
 260                         //common info (for people being able to see the module or availability dates)
 261                         $module['id'] = $cm->id;
 262                         $module['name'] = external_format_string($cm->name, $modcontext->id);
 263                         $module['instance'] = $cm->instance;
 264                         $module['modname'] = $cm->modname;
 265                         $module['modplural'] = $cm->modplural;
 266                         $module['modicon'] = $cm->get_icon_url()->out(false);
 267                         $module['indent'] = $cm->indent;
 268                         $module['onclick'] = $cm->onclick;
 269                         $module['afterlink'] = $cm->afterlink;
 270                         $module['customdata'] = json_encode($cm->customdata);
 271                         $module['completion'] = $cm->completion;
 272
 273                         // Check module completion.
 274                         $completion = $completioninfo->is_enabled($cm);
 275                         if ($completion != COMPLETION_DISABLED) {
 276                             $completiondata = $completioninfo->get_data($cm, true);
 277                             $module['completiondata'] = array(
 278                                 'state'         => $completiondata->completionstate,
 279                                 'timecompleted' => $completiondata->timemodified,
 280                                 'overrideby'    => $completiondata->overrideby,
 281                                 'valueused'     => core_availability\info::completion_value_used($course, $cm->id)
 282                             );
 283                         }
 284
 285                         if (!empty($cm->showdescription) or $cm->modname == 'label') {
 286                             // We want to use the external format. However from reading get_formatted_content(), $cm->content format is always FORMAT_HTML.
 287                             $options = array('noclean' => true);
 288                             list($module['description'], $descriptionformat) = external_format_text($cm->content,
 289                                 FORMAT_HTML, $modcontext->id, $cm->modname, 'intro', $cm->id, $options);
 290                         }
 291
 292                         //url of the module
 293                         $url = $cm->url;
 294                         if ($url) { //labels don't have url
 295                             $module['url'] = $url->out(false);
 296                         }
 297
 298                         $canviewhidden = has_capability('moodle/course:viewhiddenactivities',
 299                                             context_module::instance($cm->id));
 300                         //user that can view hidden module should know about the visibility
 301                         $module['visible'] = $cm->visible;
 302                         $module['visibleoncoursepage'] = $cm->visibleoncoursepage;
 303                         $module['uservisible'] = $cm->uservisible;
 304                         if (!empty($cm->availableinfo)) {
 305                             $module['availabilityinfo'] = \core_availability\info::format_info($cm->availableinfo, $course);
 306                         }
 307
 308                         // Availability date (also send to user who can see hidden module).
 309                         if ($CFG->enableavailability && ($canviewhidden || $canupdatecourse)) {
 310                             $module['availability'] = $cm->availability;
 311                         }
 312
 313                         // Return contents only if the user can access to the module.
 314                         if ($cm->uservisible) {
 315                             $baseurl = 'webservice/pluginfile.php';
 316
 317                             // Call $modulename_export_contents (each module callback take care about checking the capabilities).
 318                             require_once($CFG->dirroot . '/mod/' . $cm->modname . '/lib.php');
 319                             $getcontentfunction = $cm->modname.'_export_contents';
 320                             if (function_exists($getcontentfunction)) {
 321                                 $contents = $getcontentfunction($cm, $baseurl);
 322                                 $module['contentsinfo'] = array(
 323                                     'filescount' => count($contents),
 324                                     'filessize' => 0,
 325                                     'lastmodified' => 0,
 326                                     'mimetypes' => array(),
 327                                 );
 328                                 foreach ($contents as $content) {
 329                                     if (isset($content['filesize'])) {
 330                                         $module['contentsinfo']['filessize'] += $content['filesize'];
 331                                     }
 332                                     if (isset($content['timemodified']) &&
 333                                             ($content['timemodified'] > $module['contentsinfo']['lastmodified'])) {
 334
 335                                         $module['contentsinfo']['lastmodified'] = $content['timemodified'];
 336                                     }
 337                                     if (isset($content['mimetype'])) {
 338                                         $module['contentsinfo']['mimetypes'][$content['mimetype']] = $content['mimetype'];
 339                                     }
 340                                 }
 341
 342                                 if (empty($filters['excludecontents']) and !empty($contents)) {
 343                                     $module['contents'] = $contents;
 344                                 } else {
 345                                     $module['contents'] = array();
 346                                 }
 347                             }
 348                         }
 349
 350                         // Assign result to $sectioncontents, there is an exception,
 351                         // stealth activities in non-visible sections for students go to a special section.
 352                         if (!empty($filters['includestealthmodules']) && !$section->uservisible && $cm->is_stealth()) {
 353                             $stealthmodules[] = $module;
 354                         } else {
 355                             $sectioncontents[] = $module;
 356                         }
 357
 358                         // If we just did a filtering, break the loop.
 359                         if ($modfound) {
 360                             break;
 361                         }
 362
 363                     }
 364                 }
 365                 $sectionvalues['modules'] = $sectioncontents;
 366
 367                 // assign result to $coursecontents
 368                 $coursecontents[$key] = $sectionvalues;
 369
 370                 // Break the loop if we are filtering.
 371                 if ($sectionfound) {
 372                     break;
 373                 }
 374             }
 375
 376             // Now that we have iterated over all the sections and activities, check the visibility.
 377             // We didn't this before to be able to retrieve stealth activities.
 378             foreach ($coursecontents as $sectionnumber => $sectioncontents) {
 379                 $section = $sections[$sectionnumber];
 380                 // Show the section if the user is permitted to access it, OR if it's not available
 381                 // but there is some available info text which explains the reason & should display.
 382                 $showsection = $section->uservisible ||
 383                     ($section->visible && !$section->available &&
 384                     !empty($section->availableinfo));
 385
 386                 if (!$showsection) {
 387                     unset($coursecontents[$sectionnumber]);
 388                     continue;
 389                 }
 390
 391                 // Remove modules information if the section is not visible for the user.
 392                 if (!$section->uservisible) {
 393                     $coursecontents[$sectionnumber]['modules'] = array();
 394                 }
 395             }
 396
 397             // Include stealth modules in special section (without any info).
 398             if (!empty($stealthmodules)) {
 399                 $coursecontents[] = array(
 400                     'id' => -1,
 401                     'name' => '',
 402                     'summary' => '',
 403                     'summaryformat' => FORMAT_MOODLE,
 404                     'modules' => $stealthmodules
 405                 );
 406             }
 407
 408         }
 409         return $coursecontents;
 410     }
 411
 412     /**
 413      * Returns description of method result value
 414      *
 415      * @return external_description
 416      * @since Moodle 2.2
 417      */
 418     public static function get_course_contents_returns() {
 419         return new external_multiple_structure(
 420             new external_single_structure(
 421                 array(
 422                     'id' => new external_value(PARAM_INT, 'Section ID'),
 423                     'name' => new external_value(PARAM_TEXT, 'Section name'),
 424                     'visible' => new external_value(PARAM_INT, 'is the section visible', VALUE_OPTIONAL),
 425                     'summary' => new external_value(PARAM_RAW, 'Section description'),
 426                     'summaryformat' => new external_format_value('summary'),
 427                     'section' => new external_value(PARAM_INT, 'Section number inside the course', VALUE_OPTIONAL),
 428                     'hiddenbynumsections' => new external_value(PARAM_INT, 'Whether is a section hidden in the course format',
 429                                                                 VALUE_OPTIONAL),
 430                     'uservisible' => new external_value(PARAM_BOOL, 'Is the section visible for the user?', VALUE_OPTIONAL),
 431                     'availabilityinfo' => new external_value(PARAM_RAW, 'Availability information.', VALUE_OPTIONAL),
 432                     'modules' => new external_multiple_structure(
 433                             new external_single_structure(
 434                                 array(
 435                                     'id' => new external_value(PARAM_INT, 'activity id'),
 436                                     'url' => new external_value(PARAM_URL, 'activity url', VALUE_OPTIONAL),
 437                                     'name' => new external_value(PARAM_RAW, 'activity module name'),
 438                                     'instance' => new external_value(PARAM_INT, 'instance id', VALUE_OPTIONAL),
 439                                     'description' => new external_value(PARAM_RAW, 'activity description', VALUE_OPTIONAL),
 440                                     'visible' => new external_value(PARAM_INT, 'is the module visible', VALUE_OPTIONAL),
 441                                     'uservisible' => new external_value(PARAM_BOOL, 'Is the module visible for the user?',
 442                                         VALUE_OPTIONAL),
 443                                     'availabilityinfo' => new external_value(PARAM_RAW, 'Availability information.',
 444                                         VALUE_OPTIONAL),
 445                                     'visibleoncoursepage' => new external_value(PARAM_INT, 'is the module visible on course page',
 446                                         VALUE_OPTIONAL),
 447                                     'modicon' => new external_value(PARAM_URL, 'activity icon url'),
 448                                     'modname' => new external_value(PARAM_PLUGIN, 'activity module type'),
 449                                     'modplural' => new external_value(PARAM_TEXT, 'activity module plural name'),
 450                                     'availability' => new external_value(PARAM_RAW, 'module availability settings', VALUE_OPTIONAL),
 451                                     'indent' => new external_value(PARAM_INT, 'number of identation in the site'),
 452                                     'onclick' => new external_value(PARAM_RAW, 'Onclick action.', VALUE_OPTIONAL),
 453                                     'afterlink' => new external_value(PARAM_RAW, 'After link info to be displayed.',
 454                                         VALUE_OPTIONAL),
 455                                     'customdata' => new external_value(PARAM_RAW, 'Custom data (JSON encoded).', VALUE_OPTIONAL),
 456                                     'completion' => new external_value(PARAM_INT, 'Type of completion tracking:
 457                                         0 means none, 1 manual, 2 automatic.', VALUE_OPTIONAL),
 458                                     'completiondata' => new external_single_structure(
 459                                         array(
 460                                             'state' => new external_value(PARAM_INT, 'Completion state value:
 461                                                 0 means incomplete, 1 complete, 2 complete pass, 3 complete fail'),
 462                                             'timecompleted' => new external_value(PARAM_INT, 'Timestamp for completion status.'),
 463                                             'overrideby' => new external_value(PARAM_INT, 'The user id who has overriden the
 464                                                 status.'),
 465                                             'valueused' => new external_value(PARAM_BOOL, 'Whether the completion status affects
 466                                                 the availability of another activity.', VALUE_OPTIONAL),
 467                                         ), 'Module completion data.', VALUE_OPTIONAL
 468                                     ),
 469                                     'contents' => new external_multiple_structure(
 470                                           new external_single_structure(
 471                                               array(
 472                                                   // content info
 473                                                   'type'=> new external_value(PARAM_TEXT, 'a file or a folder or external link'),
 474                                                   'filename'=> new external_value(PARAM_FILE, 'filename'),
 475                                                   'filepath'=> new external_value(PARAM_PATH, 'filepath'),
 476                                                   'filesize'=> new external_value(PARAM_INT, 'filesize'),
 477                                                   'fileurl' => new external_value(PARAM_URL, 'downloadable file url', VALUE_OPTIONAL),
 478                                                   'content' => new external_value(PARAM_RAW, 'Raw content, will be used when type is content', VALUE_OPTIONAL),
 479                                                   'timecreated' => new external_value(PARAM_INT, 'Time created'),
 480                                                   'timemodified' => new external_value(PARAM_INT, 'Time modified'),
 481                                                   'sortorder' => new external_value(PARAM_INT, 'Content sort order'),
 482                                                   'mimetype' => new external_value(PARAM_RAW, 'File mime type.', VALUE_OPTIONAL),
 483                                                   'isexternalfile' => new external_value(PARAM_BOOL, 'Whether is an external file.',
 484                                                     VALUE_OPTIONAL),
 485                                                   'repositorytype' => new external_value(PARAM_PLUGIN, 'The repository type for external files.',
 486                                                     VALUE_OPTIONAL),
 487
 488                                                   // copyright related info
 489                                                   'userid' => new external_value(PARAM_INT, 'User who added this content to moodle'),
 490                                                   'author' => new external_value(PARAM_TEXT, 'Content owner'),
 491                                                   'license' => new external_value(PARAM_TEXT, 'Content license'),
 492                                               )
 493                                           ), VALUE_DEFAULT, array()
 494                                       ),
 495                                     'contentsinfo' => new external_single_structure(
 496                                         array(
 497                                             'filescount' => new external_value(PARAM_INT, 'Total number of files.'),
 498                                             'filessize' => new external_value(PARAM_INT, 'Total files size.'),
 499                                             'lastmodified' => new external_value(PARAM_INT, 'Last time files were modified.'),
 500                                             'mimetypes' => new external_multiple_structure(
 501                                                 new external_value(PARAM_RAW, 'File mime type.'),
 502                                                 'Files mime types.'
 503                                             ),
 504                                         ), 'Contents summary information.', VALUE_OPTIONAL
 505                                     ),
 506                                 )
 507                             ), 'list of module'
 508                     )
 509                 )
 510             )
 511         );
 512     }
 513
 514     /**
 515      * Returns description of method parameters
 516      *
 517      * @return external_function_parameters
 518      * @since Moodle 2.3
 519      */
 520     public static function get_courses_parameters() {
 521         return new external_function_parameters(
 522                 array('options' => new external_single_structure(
 523                             array('ids' => new external_multiple_structure(
 524                                         new external_value(PARAM_INT, 'Course id')
 525                                         , 'List of course id. If empty return all courses
 526                                             except front page course.',
 527                                         VALUE_OPTIONAL)
 528                             ), 'options - operator OR is used', VALUE_DEFAULT, array())
 529                 )
 530         );
 531     }
 532
 533     /**
 534      * Get courses
 535      *
 536      * @param array $options It contains an array (list of ids)
 537      * @return array
 538      * @since Moodle 2.2
 539      */
 540     public static function get_courses($options = array()) {
 541         global $CFG, $DB;
 542         require_once($CFG->dirroot . "/course/lib.php");
 543
 544         //validate parameter
 545         $params = self::validate_parameters(self::get_courses_parameters(),
 546                         array('options' => $options));
 547
 548         //retrieve courses
 549         if (!array_key_exists('ids', $params['options'])
 550                 or empty($params['options']['ids'])) {
 551             $courses = $DB->get_records('course');
 552         } else {
 553             $courses = $DB->get_records_list('course', 'id', $params['options']['ids']);
 554         }
 555
 556         //create return value
 557         $coursesinfo = array();
 558         foreach ($courses as $course) {
 559
 560             // now security checks
 561             $context = context_course::instance($course->id, IGNORE_MISSING);
 562             $courseformatoptions = course_get_format($course)->get_format_options();
 563             try {
 564                 self::validate_context($context);
 565             } catch (Exception $e) {
 566                 $exceptionparam = new stdClass();
 567                 $exceptionparam->message = $e->getMessage();
 568                 $exceptionparam->courseid = $course->id;
 569                 throw new moodle_exception('errorcoursecontextnotvalid', 'webservice', '', $exceptionparam);
 570             }
 571             if ($course->id != SITEID) {
 572                 require_capability('moodle/course:view', $context);
 573             }
 574
 575             $courseinfo = array();
 576             $courseinfo['id'] = $course->id;
 577             $courseinfo['fullname'] = external_format_string($course->fullname, $context->id);
 578             $courseinfo['shortname'] = external_format_string($course->shortname, $context->id);
 579             $courseinfo['displayname'] = external_format_string(get_course_display_name_for_list($course), $context->id);
 580             $courseinfo['categoryid'] = $course->category;
 581             list($courseinfo['summary'], $courseinfo['summaryformat']) =
 582                 external_format_text($course->summary, $course->summaryformat, $context->id, 'course', 'summary', 0);
 583             $courseinfo['format'] = $course->format;
 584             $courseinfo['startdate'] = $course->startdate;
 585             $courseinfo['enddate'] = $course->enddate;
 586             if (array_key_exists('numsections', $courseformatoptions)) {
 587                 // For backward-compartibility
 588                 $courseinfo['numsections'] = $courseformatoptions['numsections'];
 589             }
 590
 591             $handler = core_course\customfield\course_handler::create();
 592             if ($customfields = $handler->export_instance_data($course->id)) {
 593                 $courseinfo['customfields'] = [];
 594                 foreach ($customfields as $data) {
 595                     $courseinfo['customfields'][] = [
 596                         'type' => $data->get_type(),
 597                         'value' => $data->get_value(),
 598                         'name' => $data->get_name(),
 599                         'shortname' => $data->get_shortname()
 600                     ];
 601                 }
 602             }
 603
 604             //some field should be returned only if the user has update permission
 605             $courseadmin = has_capability('moodle/course:update', $context);
 606             if ($courseadmin) {
 607                 $courseinfo['categorysortorder'] = $course->sortorder;
 608                 $courseinfo['idnumber'] = $course->idnumber;
 609                 $courseinfo['showgrades'] = $course->showgrades;
 610                 $courseinfo['showreports'] = $course->showreports;
 611                 $courseinfo['newsitems'] = $course->newsitems;
 612                 $courseinfo['visible'] = $course->visible;
 613                 $courseinfo['maxbytes'] = $course->maxbytes;
 614                 if (array_key_exists('hiddensections', $courseformatoptions)) {
 615                     // For backward-compartibility
 616                     $courseinfo['hiddensections'] = $courseformatoptions['hiddensections'];
 617                 }
 618                 // Return numsections for backward-compatibility with clients who expect it.
 619                 $courseinfo['numsections'] = course_get_format($course)->get_last_section_number();
 620                 $courseinfo['groupmode'] = $course->groupmode;
 621                 $courseinfo['groupmodeforce'] = $course->groupmodeforce;
 622                 $courseinfo['defaultgroupingid'] = $course->defaultgroupingid;
 623                 $courseinfo['lang'] = clean_param($course->lang, PARAM_LANG);
 624                 $courseinfo['timecreated'] = $course->timecreated;
 625                 $courseinfo['timemodified'] = $course->timemodified;
 626                 $courseinfo['forcetheme'] = clean_param($course->theme, PARAM_THEME);
 627                 $courseinfo['enablecompletion'] = $course->enablecompletion;
 628                 $courseinfo['completionnotify'] = $course->completionnotify;
 629                 $courseinfo['courseformatoptions'] = array();
 630                 foreach ($courseformatoptions as $key => $value) {
 631                     $courseinfo['courseformatoptions'][] = array(
 632                         'name' => $key,
 633                         'value' => $value
 634                     );
 635                 }
 636             }
 637
 638             if ($courseadmin or $course->visible
 639                     or has_capability('moodle/course:viewhiddencourses', $context)) {
 640                 $coursesinfo[] = $courseinfo;
 641             }
 642         }
 643
 644         return $coursesinfo;
 645     }
 646
 647     /**
 648      * Returns description of method result value
 649      *
 650      * @return external_description
 651      * @since Moodle 2.2
 652      */
 653     public static function get_courses_returns() {
 654         return new external_multiple_structure(
 655                 new external_single_structure(
 656                         array(
 657                             'id' => new external_value(PARAM_INT, 'course id'),
 658                             'shortname' => new external_value(PARAM_TEXT, 'course short name'),
 659                             'categoryid' => new external_value(PARAM_INT, 'category id'),
 660                             'categorysortorder' => new external_value(PARAM_INT,
 661                                     'sort order into the category', VALUE_OPTIONAL),
 662                             'fullname' => new external_value(PARAM_TEXT, 'full name'),
 663                             'displayname' => new external_value(PARAM_TEXT, 'course display name'),
 664                             'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL),
 665                             'summary' => new external_value(PARAM_RAW, 'summary'),
 666                             'summaryformat' => new external_format_value('summary'),
 667                             'format' => new external_value(PARAM_PLUGIN,
 668                                     'course format: weeks, topics, social, site,..'),
 669                             'showgrades' => new external_value(PARAM_INT,
 670                                     '1 if grades are shown, otherwise 0', VALUE_OPTIONAL),
 671                             'newsitems' => new external_value(PARAM_INT,
 672                                     'number of recent items appearing on the course page', VALUE_OPTIONAL),
 673                             'startdate' => new external_value(PARAM_INT,
 674                                     'timestamp when the course start'),
 675                             'enddate' => new external_value(PARAM_INT,
 676                                     'timestamp when the course end'),
 677                             'numsections' => new external_value(PARAM_INT,
 678                                     '(deprecated, use courseformatoptions) number of weeks/topics',
 679                                     VALUE_OPTIONAL),
 680                             'maxbytes' => new external_value(PARAM_INT,
 681                                     'largest size of file that can be uploaded into the course',
 682                                     VALUE_OPTIONAL),
 683                             'showreports' => new external_value(PARAM_INT,
 684                                     'are activity report shown (yes = 1, no =0)', VALUE_OPTIONAL),
 685                             'visible' => new external_value(PARAM_INT,
 686                                     '1: available to student, 0:not available', VALUE_OPTIONAL),
 687                             'hiddensections' => new external_value(PARAM_INT,
 688                                     '(deprecated, use courseformatoptions) How the hidden sections in the course are displayed to students',
 689                                     VALUE_OPTIONAL),
 690                             'groupmode' => new external_value(PARAM_INT, 'no group, separate, visible',
 691                                     VALUE_OPTIONAL),
 692                             'groupmodeforce' => new external_value(PARAM_INT, '1: yes, 0: no',
 693                                     VALUE_OPTIONAL),
 694                             'defaultgroupingid' => new external_value(PARAM_INT, 'default grouping id',
 695                                     VALUE_OPTIONAL),
 696                             'timecreated' => new external_value(PARAM_INT,
 697                                     'timestamp when the course have been created', VALUE_OPTIONAL),
 698                             'timemodified' => new external_value(PARAM_INT,
 699                                     'timestamp when the course have been modified', VALUE_OPTIONAL),
 700                             'enablecompletion' => new external_value(PARAM_INT,
 701                                     'Enabled, control via completion and activity settings. Disbaled,
 702                                         not shown in activity settings.',
 703                                     VALUE_OPTIONAL),
 704                             'completionnotify' => new external_value(PARAM_INT,
 705                                     '1: yes 0: no', VALUE_OPTIONAL),
 706                             'lang' => new external_value(PARAM_SAFEDIR,
 707                                     'forced course language', VALUE_OPTIONAL),
 708                             'forcetheme' => new external_value(PARAM_PLUGIN,
 709                                     'name of the force theme', VALUE_OPTIONAL),
 710                             'courseformatoptions' => new external_multiple_structure(
 711                                 new external_single_structure(
 712                                     array('name' => new external_value(PARAM_ALPHANUMEXT, 'course format option name'),
 713                                         'value' => new external_value(PARAM_RAW, 'course format option value')
 714                                 )), 'additional options for particular course format', VALUE_OPTIONAL
 715                              ),
 716                             'customfields' => new external_multiple_structure(
 717                                 new external_single_structure(
 718                                     ['name' => new external_value(PARAM_TEXT, 'The name of the custom field'),
 719                                      'shortname' => new external_value(PARAM_ALPHANUMEXT, 'The shortname of the custom field'),
 720                                      'type'  => new external_value(PARAM_COMPONENT,
 721                                          'The type of the custom field - text, checkbox...'),
 722                                      'value' => new external_value(PARAM_RAW, 'The value of the custom field')]
 723                                 ), 'Custom fields and associated values', VALUE_OPTIONAL),
 724                         ), 'course'
 725                 )
 726         );
 727     }
 728
 729     /**
 730      * Returns description of method parameters
 731      *
 732      * @return external_function_parameters
 733      * @since Moodle 2.2
 734      */
 735     public static function create_courses_parameters() {
 736         $courseconfig = get_config('moodlecourse'); //needed for many default values
 737         return new external_function_parameters(
 738             array(
 739                 'courses' => new external_multiple_structure(
 740                     new external_single_structure(
 741                         array(
 742                             'fullname' => new external_value(PARAM_TEXT, 'full name'),
 743                             'shortname' => new external_value(PARAM_TEXT, 'course short name'),
 744                             'categoryid' => new external_value(PARAM_INT, 'category id'),
 745                             'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL),
 746                             'summary' => new external_value(PARAM_RAW, 'summary', VALUE_OPTIONAL),
 747                             'summaryformat' => new external_format_value('summary', VALUE_DEFAULT),
 748                             'format' => new external_value(PARAM_PLUGIN,
 749                                     'course format: weeks, topics, social, site,..',
 750                                     VALUE_DEFAULT, $courseconfig->format),
 751                             'showgrades' => new external_value(PARAM_INT,
 752                                     '1 if grades are shown, otherwise 0', VALUE_DEFAULT,
 753                                     $courseconfig->showgrades),
 754                             'newsitems' => new external_value(PARAM_INT,
 755                                     'number of recent items appearing on the course page',
 756                                     VALUE_DEFAULT, $courseconfig->newsitems),
 757                             'startdate' => new external_value(PARAM_INT,
 758                                     'timestamp when the course start', VALUE_OPTIONAL),
 759                             'enddate' => new external_value(PARAM_INT,
 760                                     'timestamp when the course end', VALUE_OPTIONAL),
 761                             'numsections' => new external_value(PARAM_INT,
 762                                     '(deprecated, use courseformatoptions) number of weeks/topics',
 763                                     VALUE_OPTIONAL),
 764                             'maxbytes' => new external_value(PARAM_INT,
 765                                     'largest size of file that can be uploaded into the course',
 766                                     VALUE_DEFAULT, $courseconfig->maxbytes),
 767                             'showreports' => new external_value(PARAM_INT,
 768                                     'are activity report shown (yes = 1, no =0)', VALUE_DEFAULT,
 769                                     $courseconfig->showreports),
 770                             'visible' => new external_value(PARAM_INT,
 771                                     '1: available to student, 0:not available', VALUE_OPTIONAL),
 772                             'hiddensections' => new external_value(PARAM_INT,
 773                                     '(deprecated, use courseformatoptions) How the hidden sections in the course are displayed to students',
 774                                     VALUE_OPTIONAL),
 775                             'groupmode' => new external_value(PARAM_INT, 'no group, separate, visible',
 776                                     VALUE_DEFAULT, $courseconfig->groupmode),
 777                             'groupmodeforce' => new external_value(PARAM_INT, '1: yes, 0: no',
 778                                     VALUE_DEFAULT, $courseconfig->groupmodeforce),
 779                             'defaultgroupingid' => new external_value(PARAM_INT, 'default grouping id',
 780                                     VALUE_DEFAULT, 0),
 781                             'enablecompletion' => new external_value(PARAM_INT,
 782                                     'Enabled, control via completion and activity settings. Disabled,
 783                                         not shown in activity settings.',
 784                                     VALUE_OPTIONAL),
 785                             'completionnotify' => new external_value(PARAM_INT,
 786                                     '1: yes 0: no', VALUE_OPTIONAL),
 787                             'lang' => new external_value(PARAM_SAFEDIR,
 788                                     'forced course language', VALUE_OPTIONAL),
 789                             'forcetheme' => new external_value(PARAM_PLUGIN,
 790                                     'name of the force theme', VALUE_OPTIONAL),
 791                             'courseformatoptions' => new external_multiple_structure(
 792                                 new external_single_structure(
 793                                     array('name' => new external_value(PARAM_ALPHANUMEXT, 'course format option name'),
 794                                         'value' => new external_value(PARAM_RAW, 'course format option value')
 795                                 )),
 796                                     'additional options for particular course format', VALUE_OPTIONAL),
 797                             'customfields' => new external_multiple_structure(
 798                                 new external_single_structure(
 799                                     array(
 800                                         'shortname'  => new external_value(PARAM_ALPHANUMEXT, 'The shortname of the custom field'),
 801                                         'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
 802                                 )), 'custom fields for the course', VALUE_OPTIONAL
 803                             )
 804                     )), 'courses to create'
 805                 )
 806             )
 807         );
 808     }
 809
 810     /**
 811      * Create  courses
 812      *
 813      * @param array $courses
 814      * @return array courses (id and shortname only)
 815      * @since Moodle 2.2
 816      */
 817     public static function create_courses($courses) {
 818         global $CFG, $DB;
 819         require_once($CFG->dirroot . "/course/lib.php");
 820         require_once($CFG->libdir . '/completionlib.php');
 821
 822         $params = self::validate_parameters(self::create_courses_parameters(),
 823                         array('courses' => $courses));
 824
 825         $availablethemes = core_component::get_plugin_list('theme');
 826         $availablelangs = get_string_manager()->get_list_of_translations();
 827
 828         $transaction = $DB->start_delegated_transaction();
 829
 830         foreach ($params['courses'] as $course) {
 831
 832             // Ensure the current user is allowed to run this function
 833             $context = context_coursecat::instance($course['categoryid'], IGNORE_MISSING);
 834             try {
 835                 self::validate_context($context);
 836             } catch (Exception $e) {
 837                 $exceptionparam = new stdClass();
 838                 $exceptionparam->message = $e->getMessage();
 839                 $exceptionparam->catid = $course['categoryid'];
 840                 throw new moodle_exception('errorcatcontextnotvalid', 'webservice', '', $exceptionparam);
 841             }
 842             require_capability('moodle/course:create', $context);
 843
 844             // Make sure lang is valid
 845             if (array_key_exists('lang', $course)) {
 846                 if (empty($availablelangs[$course['lang']])) {
 847                     throw new moodle_exception('errorinvalidparam', 'webservice', '', 'lang');
 848                 }
 849                 if (!has_capability('moodle/course:setforcedlanguage', $context)) {
 850                     unset($course['lang']);
 851                 }
 852             }
 853
 854             // Make sure theme is valid
 855             if (array_key_exists('forcetheme', $course)) {
 856                 if (!empty($CFG->allowcoursethemes)) {
 857                     if (empty($availablethemes[$course['forcetheme']])) {
 858                         throw new moodle_exception('errorinvalidparam', 'webservice', '', 'forcetheme');
 859                     } else {
 860                         $course['theme'] = $course['forcetheme'];
 861                     }
 862                 }
 863             }
 864
 865             //force visibility if ws user doesn't have the permission to set it
 866             $category = $DB->get_record('course_categories', array('id' => $course['categoryid']));
 867             if (!has_capability('moodle/course:visibility', $context)) {
 868                 $course['visible'] = $category->visible;
 869             }
 870
 871             //set default value for completion
 872             $courseconfig = get_config('moodlecourse');
 873             if (completion_info::is_enabled_for_site()) {
 874                 if (!array_key_exists('enablecompletion', $course)) {
 875                     $course['enablecompletion'] = $courseconfig->enablecompletion;
 876                 }
 877             } else {
 878                 $course['enablecompletion'] = 0;
 879             }
 880
 881             $course['category'] = $course['categoryid'];
 882
 883             // Summary format.
 884             $course['summaryformat'] = external_validate_format($course['summaryformat']);
 885
 886             if (!empty($course['courseformatoptions'])) {
 887                 foreach ($course['courseformatoptions'] as $option) {
 888                     $course[$option['name']] = $option['value'];
 889                 }
 890             }
 891
 892             // Custom fields.
 893             if (!empty($course['customfields'])) {
 894                 foreach ($course['customfields'] as $field) {
 895                     $course['customfield_'.$field['shortname']] = $field['value'];
 896                 }
 897             }
 898
 899             //Note: create_course() core function check shortname, idnumber, category
 900             $course['id'] = create_course((object) $course)->id;
 901
 902             $resultcourses[] = array('id' => $course['id'], 'shortname' => $course['shortname']);
 903         }
 904
 905         $transaction->allow_commit();
 906
 907         return $resultcourses;
 908     }
 909
 910     /**
 911      * Returns description of method result value
 912      *
 913      * @return external_description
 914      * @since Moodle 2.2
 915      */
 916     public static function create_courses_returns() {
 917         return new external_multiple_structure(
 918             new external_single_structure(
 919                 array(
 920                     'id'       => new external_value(PARAM_INT, 'course id'),
 921                     'shortname' => new external_value(PARAM_TEXT, 'short name'),
 922                 )
 923             )
 924         );
 925     }
 926
 927     /**
 928      * Update courses
 929      *
 930      * @return external_function_parameters
 931      * @since Moodle 2.5
 932      */
 933     public static function update_courses_parameters() {
 934         return new external_function_parameters(
 935             array(
 936                 'courses' => new external_multiple_structure(
 937                     new external_single_structure(
 938                         array(
 939                             'id' => new external_value(PARAM_INT, 'ID of the course'),
 940                             'fullname' => new external_value(PARAM_TEXT, 'full name', VALUE_OPTIONAL),
 941                             'shortname' => new external_value(PARAM_TEXT, 'course short name', VALUE_OPTIONAL),
 942                             'categoryid' => new external_value(PARAM_INT, 'category id', VALUE_OPTIONAL),
 943                             'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL),
 944                             'summary' => new external_value(PARAM_RAW, 'summary', VALUE_OPTIONAL),
 945                             'summaryformat' => new external_format_value('summary', VALUE_OPTIONAL),
 946                             'format' => new external_value(PARAM_PLUGIN,
 947                                     'course format: weeks, topics, social, site,..', VALUE_OPTIONAL),
 948                             'showgrades' => new external_value(PARAM_INT,
 949                                     '1 if grades are shown, otherwise 0', VALUE_OPTIONAL),
 950                             'newsitems' => new external_value(PARAM_INT,
 951                                     'number of recent items appearing on the course page', VALUE_OPTIONAL),
 952                             'startdate' => new external_value(PARAM_INT,
 953                                     'timestamp when the course start', VALUE_OPTIONAL),
 954                             'enddate' => new external_value(PARAM_INT,
 955                                     'timestamp when the course end', VALUE_OPTIONAL),
 956                             'numsections' => new external_value(PARAM_INT,
 957                                     '(deprecated, use courseformatoptions) number of weeks/topics', VALUE_OPTIONAL),
 958                             'maxbytes' => new external_value(PARAM_INT,
 959                                     'largest size of file that can be uploaded into the course', VALUE_OPTIONAL),
 960                             'showreports' => new external_value(PARAM_INT,
 961                                     'are activity report shown (yes = 1, no =0)', VALUE_OPTIONAL),
 962                             'visible' => new external_value(PARAM_INT,
 963                                     '1: available to student, 0:not available', VALUE_OPTIONAL),
 964                             'hiddensections' => new external_value(PARAM_INT,
 965                                     '(deprecated, use courseformatoptions) How the hidden sections in the course are
 966                                         displayed to students', VALUE_OPTIONAL),
 967                             'groupmode' => new external_value(PARAM_INT, 'no group, separate, visible', VALUE_OPTIONAL),
 968                             'groupmodeforce' => new external_value(PARAM_INT, '1: yes, 0: no', VALUE_OPTIONAL),
 969                             'defaultgroupingid' => new external_value(PARAM_INT, 'default grouping id', VALUE_OPTIONAL),
 970                             'enablecompletion' => new external_value(PARAM_INT,
 971                                     'Enabled, control via completion and activity settings. Disabled,
 972                                         not shown in activity settings.', VALUE_OPTIONAL),
 973                             'completionnotify' => new external_value(PARAM_INT, '1: yes 0: no', VALUE_OPTIONAL),
 974                             'lang' => new external_value(PARAM_SAFEDIR, 'forced course language', VALUE_OPTIONAL),
 975                             'forcetheme' => new external_value(PARAM_PLUGIN, 'name of the force theme', VALUE_OPTIONAL),
 976                             'courseformatoptions' => new external_multiple_structure(
 977                                 new external_single_structure(
 978                                     array('name' => new external_value(PARAM_ALPHANUMEXT, 'course format option name'),
 979                                         'value' => new external_value(PARAM_RAW, 'course format option value')
 980                                 )), 'additional options for particular course format', VALUE_OPTIONAL),
 981                             'customfields' => new external_multiple_structure(
 982                                 new external_single_structure(
 983                                     [
 984                                         'shortname'  => new external_value(PARAM_ALPHANUMEXT, 'The shortname of the custom field'),
 985                                         'value' => new external_value(PARAM_RAW, 'The value of the custom field')
 986                                     ]
 987                                 ), 'Custom fields', VALUE_OPTIONAL),
 988                         )
 989                     ), 'courses to update'
 990                 )
 991             )
 992         );
 993     }
 994
 995     /**
 996      * Update courses
 997      *
 998      * @param array $courses
 999      * @since Moodle 2.5
1000      */
1001     public static function update_courses($courses) {
1002         global $CFG, $DB;
1003         require_once($CFG->dirroot . "/course/lib.php");
1004         $warnings = array();
1005
1006         $params = self::validate_parameters(self::update_courses_parameters(),
1007                         array('courses' => $courses));
1008
1009         $availablethemes = core_component::get_plugin_list('theme');
1010         $availablelangs = get_string_manager()->get_list_of_translations();
1011
1012         foreach ($params['courses'] as $course) {
1013             // Catch any exception while updating course and return as warning to user.
1014             try {
1015                 // Ensure the current user is allowed to run this function.
1016                 $context = context_course::instance($course['id'], MUST_EXIST);
1017                 self::validate_context($context);
1018
1019                 $oldcourse = course_get_format($course['id'])->get_course();
1020
1021                 require_capability('moodle/course:update', $context);
1022
1023                 // Check if user can change category.
1024                 if (array_key_exists('categoryid', $course) && ($oldcourse->category != $course['categoryid'])) {
1025                     require_capability('moodle/course:changecategory', $context);
1026                     $course['category'] = $course['categoryid'];
1027                 }
1028
1029                 // Check if the user can change fullname.
1030                 if (array_key_exists('fullname', $course) && ($oldcourse->fullname != $course['fullname'])) {
1031                     require_capability('moodle/course:changefullname', $context);
1032                 }
1033
1034                 // Check if the user can change shortname.
1035                 if (array_key_exists('shortname', $course) && ($oldcourse->shortname != $course['shortname'])) {
1036                     require_capability('moodle/course:changeshortname', $context);
1037                 }
1038
1039                 // Check if the user can change the idnumber.
1040                 if (array_key_exists('idnumber', $course) && ($oldcourse->idnumber != $course['idnumber'])) {
1041                     require_capability('moodle/course:changeidnumber', $context);
1042                 }
1043
1044                 // Check if user can change summary.
1045                 if (array_key_exists('summary', $course) && ($oldcourse->summary != $course['summary'])) {
1046                     require_capability('moodle/course:changesummary', $context);
1047                 }
1048
1049                 // Summary format.
1050                 if (array_key_exists('summaryformat', $course) && ($oldcourse->summaryformat != $course['summaryformat'])) {
1051                     require_capability('moodle/course:changesummary', $context);
1052                     $course['summaryformat'] = external_validate_format($course['summaryformat']);
1053                 }
1054
1055                 // Check if user can change visibility.
1056                 if (array_key_exists('visible', $course) && ($oldcourse->visible != $course['visible'])) {
1057                     require_capability('moodle/course:visibility', $context);
1058                 }
1059
1060                 // Make sure lang is valid.
1061                 if (array_key_exists('lang', $course) && ($oldcourse->lang != $course['lang'])) {
1062                     require_capability('moodle/course:setforcedlanguage', $context);
1063                     if (empty($availablelangs[$course['lang']])) {
1064                         throw new moodle_exception('errorinvalidparam', 'webservice', '', 'lang');
1065                     }
1066                 }
1067
1068                 // Make sure theme is valid.
1069                 if (array_key_exists('forcetheme', $course)) {
1070                     if (!empty($CFG->allowcoursethemes)) {
1071                         if (empty($availablethemes[$course['forcetheme']])) {
1072                             throw new moodle_exception('errorinvalidparam', 'webservice', '', 'forcetheme');
1073                         } else {
1074                             $course['theme'] = $course['forcetheme'];
1075                         }
1076                     }
1077                 }
1078
1079                 // Make sure completion is enabled before setting it.
1080                 if (array_key_exists('enabledcompletion', $course) && !completion_info::is_enabled_for_site()) {
1081                     $course['enabledcompletion'] = 0;
1082                 }
1083
1084                 // Make sure maxbytes are less then CFG->maxbytes.
1085                 if (array_key_exists('maxbytes', $course)) {
1086                     // We allow updates back to 0 max bytes, a special value denoting the course uses the site limit.
1087                     // Otherwise, either use the size specified, or cap at the max size for the course.
1088                     if ($course['maxbytes'] != 0) {
1089                         $course['maxbytes'] = get_max_upload_file_size($CFG->maxbytes, $course['maxbytes']);
1090                     }
1091                 }
1092
1093                 if (!empty($course['courseformatoptions'])) {
1094                     foreach ($course['courseformatoptions'] as $option) {
1095                         if (isset($option['name']) && isset($option['value'])) {
1096                             $course[$option['name']] = $option['value'];
1097                         }
1098                     }
1099                 }
1100
1101                 // Prepare list of custom fields.
1102                 if (isset($course['customfields'])) {
1103                     foreach ($course['customfields'] as $field) {
1104                         $course['customfield_' . $field['shortname']] = $field['value'];
1105                     }
1106                 }
1107
1108                 // Update course if user has all required capabilities.
1109                 update_course((object) $course);
1110             } catch (Exception $e) {
1111                 $warning = array();
1112                 $warning['item'] = 'course';
1113                 $warning['itemid'] = $course['id'];
1114                 if ($e instanceof moodle_exception) {
1115                     $warning['warningcode'] = $e->errorcode;
1116                 } else {
1117                     $warning['warningcode'] = $e->getCode();
1118                 }
1119                 $warning['message'] = $e->getMessage();
1120                 $warnings[] = $warning;
1121             }
1122         }
1123
1124         $result = array();
1125         $result['warnings'] = $warnings;
1126         return $result;
1127     }
1128
1129     /**
1130      * Returns description of method result value
1131      *
1132      * @return external_description
1133      * @since Moodle 2.5
1134      */
1135     public static function update_courses_returns() {
1136         return new external_single_structure(
1137             array(
1138                 'warnings' => new external_warnings()
1139             )
1140         );
1141     }
1142
1143     /**
1144      * Returns description of method parameters
1145      *
1146      * @return external_function_parameters
1147      * @since Moodle 2.2
1148      */
1149     public static function delete_courses_parameters() {
1150         return new external_function_parameters(
1151             array(
1152                 'courseids' => new external_multiple_structure(new external_value(PARAM_INT, 'course ID')),
1153             )
1154         );
1155     }
1156
1157     /**
1158      * Delete courses
1159      *
1160      * @param array $courseids A list of course ids
1161      * @since Moodle 2.2
1162      */
1163     public static function delete_courses($courseids) {
1164         global $CFG, $DB;
1165         require_once($CFG->dirroot."/course/lib.php");
1166
1167         // Parameter validation.
1168         $params = self::validate_parameters(self::delete_courses_parameters(), array('courseids'=>$courseids));
1169
1170         $warnings = array();
1171
1172         foreach ($params['courseids'] as $courseid) {
1173             $course = $DB->get_record('course', array('id' => $courseid));
1174
1175             if ($course === false) {
1176                 $warnings[] = array(
1177                                 'item' => 'course',
1178                                 'itemid' => $courseid,
1179                                 'warningcode' => 'unknowncourseidnumber',
1180                                 'message' => 'Unknown course ID ' . $courseid
1181                             );
1182                 continue;
1183             }
1184
1185             // Check if the context is valid.
1186             $coursecontext = context_course::instance($course->id);
1187             self::validate_context($coursecontext);
1188
1189             // Check if the current user has permission.
1190             if (!can_delete_course($courseid)) {
1191                 $warnings[] = array(
1192                                 'item' => 'course',
1193                                 'itemid' => $courseid,
1194                                 'warningcode' => 'cannotdeletecourse',
1195                                 'message' => 'You do not have the permission to delete this course' . $courseid
1196                             );
1197                 continue;
1198             }
1199
1200             if (delete_course($course, false) === false) {
1201                 $warnings[] = array(
1202                                 'item' => 'course',
1203                                 'itemid' => $courseid,
1204                                 'warningcode' => 'cannotdeletecategorycourse',
1205                                 'message' => 'Course ' . $courseid . ' failed to be deleted'
1206                             );
1207                 continue;
1208             }
1209         }
1210
1211         fix_course_sortorder();
1212
1213         return array('warnings' => $warnings);
1214     }
1215
1216     /**
1217      * Returns description of method result value
1218      *
1219      * @return external_description
1220      * @since Moodle 2.2
1221      */
1222     public static function delete_courses_returns() {
1223         return new external_single_structure(
1224             array(
1225                 'warnings' => new external_warnings()
1226             )
1227         );
1228     }
1229
1230     /**
1231      * Returns description of method parameters
1232      *
1233      * @return external_function_parameters
1234      * @since Moodle 2.3
1235      */
1236     public static function duplicate_course_parameters() {
1237         return new external_function_parameters(
1238             array(
1239                 'courseid' => new external_value(PARAM_INT, 'course to duplicate id'),
1240                 'fullname' => new external_value(PARAM_TEXT, 'duplicated course full name'),
1241                 'shortname' => new external_value(PARAM_TEXT, 'duplicated course short name'),
1242                 'categoryid' => new external_value(PARAM_INT, 'duplicated course category parent'),
1243                 'visible' => new external_value(PARAM_INT, 'duplicated course visible, default to yes', VALUE_DEFAULT, 1),
1244                 'options' => new external_multiple_structure(
1245                     new external_single_structure(
1246                         array(
1247                                 'name' => new external_value(PARAM_ALPHAEXT, 'The backup option name:
1248                                             "activities" (int) Include course activites (default to 1 that is equal to yes),
1249                                             "blocks" (int) Include course blocks (default to 1 that is equal to yes),
1250                                             "filters" (int) Include course filters  (default to 1 that is equal to yes),
1251                                             "users" (int) Include users (default to 0 that is equal to no),
1252                                             "enrolments" (int) Include enrolment methods (default to 1 - restore only with users),
1253                                             "role_assignments" (int) Include role assignments  (default to 0 that is equal to no),
1254                                             "comments" (int) Include user comments  (default to 0 that is equal to no),
1255                                             "userscompletion" (int) Include user course completion information  (default to 0 that is equal to no),
1256                                             "logs" (int) Include course logs  (default to 0 that is equal to no),
1257                                             "grade_histories" (int) Include histories  (default to 0 that is equal to no)'
1258                                             ),
1259                                 'value' => new external_value(PARAM_RAW, 'the value for the option 1 (yes) or 0 (no)'
1260                             )
1261                         )
1262                     ), VALUE_DEFAULT, array()
1263                 ),
1264             )
1265         );
1266     }
1267
1268     /**
1269      * Duplicate a course
1270      *
1271      * @param int $courseid
1272      * @param string $fullname Duplicated course fullname
1273      * @param string $shortname Duplicated course shortname
1274      * @param int $categoryid Duplicated course parent category id
1275      * @param int $visible Duplicated course availability
1276      * @param array $options List of backup options
1277      * @return array New course info
1278      * @since Moodle 2.3
1279      */
1280     public static function duplicate_course($courseid, $fullname, $shortname, $categoryid, $visible = 1, $options = array()) {
1281         global $CFG, $USER, $DB;
1282         require_once($CFG->dirroot . '/backup/util/includes/backup_includes.php');
1283         require_once($CFG->dirroot . '/backup/util/includes/restore_includes.php');
1284
1285         // Parameter validation.
1286         $params = self::validate_parameters(
1287                 self::duplicate_course_parameters(),
1288                 array(
1289                       'courseid' => $courseid,
1290                       'fullname' => $fullname,
1291                       'shortname' => $shortname,
1292                       'categoryid' => $categoryid,
1293                       'visible' => $visible,
1294                       'options' => $options
1295                 )
1296         );
1297
1298         // Context validation.
1299
1300         if (! ($course = $DB->get_record('course', array('id'=>$params['courseid'])))) {
1301             throw new moodle_exception('invalidcourseid', 'error');
1302         }
1303
1304         // Category where duplicated course is going to be created.
1305         $categorycontext = context_coursecat::instance($params['categoryid']);
1306         self::validate_context($categorycontext);
1307
1308         // Course to be duplicated.
1309         $coursecontext = context_course::instance($course->id);
1310         self::validate_context($coursecontext);
1311
1312         $backupdefaults = array(
1313             'activities' => 1,
1314             'blocks' => 1,
1315             'filters' => 1,
1316             'users' => 0,
1317             'enrolments' => backup::ENROL_WITHUSERS,
1318             'role_assignments' => 0,
1319             'comments' => 0,
1320             'userscompletion' => 0,
1321             'logs' => 0,
1322             'grade_histories' => 0
1323         );
1324
1325         $backupsettings = array();
1326         // Check for backup and restore options.
1327         if (!empty($params['options'])) {
1328             foreach ($params['options'] as $option) {
1329
1330                 // Strict check for a correct value (allways 1 or 0, true or false).
1331                 $value = clean_param($option['value'], PARAM_INT);
1332
1333                 if ($value !== 0 and $value !== 1) {
1334                     throw new moodle_exception('invalidextparam', 'webservice', '', $option['name']);
1335                 }
1336
1337                 if (!isset($backupdefaults[$option['name']])) {
1338                     throw new moodle_exception('invalidextparam', 'webservice', '', $option['name']);
1339                 }
1340
1341                 $backupsettings[$option['name']] = $value;
1342             }
1343         }
1344
1345         // Capability checking.
1346
1347         // The backup controller check for this currently, this may be redundant.
1348         require_capability('moodle/course:create', $categorycontext);
1349         require_capability('moodle/restore:restorecourse', $categorycontext);
1350         require_capability('moodle/backup:backupcourse', $coursecontext);
1351
1352         if (!empty($backupsettings['users'])) {
1353             require_capability('moodle/backup:userinfo', $coursecontext);
1354             require_capability('moodle/restore:userinfo', $categorycontext);
1355         }
1356
1357         // Check if the shortname is used.
1358         if ($foundcourses = $DB->get_records('course', array('shortname'=>$shortname))) {
1359             foreach ($foundcourses as $foundcourse) {
1360                 $foundcoursenames[] = $foundcourse->fullname;
1361             }
1362
1363             $foundcoursenamestring = implode(',', $foundcoursenames);
1364             throw new moodle_exception('shortnametaken', '', '', $foundcoursenamestring);
1365         }
1366
1367         // Backup the course.
1368
1369         $bc = new backup_controller(backup::TYPE_1COURSE, $course->id, backup::FORMAT_MOODLE,
1370         backup::INTERACTIVE_NO, backup::MODE_SAMESITE, $USER->id);
1371
1372         foreach ($backupsettings as $name => $value) {
1373             if ($setting = $bc->get_plan()->get_setting($name)) {
1374                 $bc->get_plan()->get_setting($name)->set_value($value);
1375             }
1376         }
1377
1378         $backupid       = $bc->get_backupid();
1379         $backupbasepath = $bc->get_plan()->get_basepath();
1380
1381         $bc->execute_plan();
1382         $results = $bc->get_results();
1383         $file = $results['backup_destination'];
1384
1385         $bc->destroy();
1386
1387         // Restore the backup immediately.
1388
1389         // Check if we need to unzip the file because the backup temp dir does not contains backup files.
1390         if (!file_exists($backupbasepath . "/moodle_backup.xml")) {
1391             $file->extract_to_pathname(get_file_packer('application/vnd.moodle.backup'), $backupbasepath);
1392         }
1393
1394         // Create new course.
1395         $newcourseid = restore_dbops::create_new_course($params['fullname'], $params['shortname'], $params['categoryid']);
1396
1397         $rc = new restore_controller($backupid, $newcourseid,
1398                 backup::INTERACTIVE_NO, backup::MODE_SAMESITE, $USER->id, backup::TARGET_NEW_COURSE);
1399
1400         foreach ($backupsettings as $name => $value) {
1401             $setting = $rc->get_plan()->get_setting($name);
1402             if ($setting->get_status() == backup_setting::NOT_LOCKED) {
1403                 $setting->set_value($value);
1404             }
1405         }
1406
1407         if (!$rc->execute_precheck()) {
1408             $precheckresults = $rc->get_precheck_results();
1409             if (is_array($precheckresults) && !empty($precheckresults['errors'])) {
1410                 if (empty($CFG->keeptempdirectoriesonbackup)) {
1411                     fulldelete($backupbasepath);
1412                 }
1413
1414                 $errorinfo = '';
1415
1416                 foreach ($precheckresults['errors'] as $error) {
1417                     $errorinfo .= $error;
1418                 }
1419
1420                 if (array_key_exists('warnings', $precheckresults)) {
1421                     foreach ($precheckresults['warnings'] as $warning) {
1422                         $errorinfo .= $warning;
1423                     }
1424                 }
1425
1426                 throw new moodle_exception('backupprecheckerrors', 'webservice', '', $errorinfo);
1427             }
1428         }
1429
1430         $rc->execute_plan();
1431         $rc->destroy();
1432
1433         $course = $DB->get_record('course', array('id' => $newcourseid), '*', MUST_EXIST);
1434         $course->fullname = $params['fullname'];
1435         $course->shortname = $params['shortname'];
1436         $course->visible = $params['visible'];
1437
1438         // Set shortname and fullname back.
1439         $DB->update_record('course', $course);
1440
1441         if (empty($CFG->keeptempdirectoriesonbackup)) {
1442             fulldelete($backupbasepath);
1443         }
1444
1445         // Delete the course backup file created by this WebService. Originally located in the course backups area.
1446         $file->delete();
1447
1448         return array('id' => $course->id, 'shortname' => $course->shortname);
1449     }
1450
1451     /**
1452      * Returns description of method result value
1453      *
1454      * @return external_description
1455      * @since Moodle 2.3
1456      */
1457     public static function duplicate_course_returns() {
1458         return new external_single_structure(
1459             array(
1460                 'id'       => new external_value(PARAM_INT, 'course id'),
1461                 'shortname' => new external_value(PARAM_TEXT, 'short name'),
1462             )
1463         );
1464     }
1465
1466     /**
1467      * Returns description of method parameters for import_course
1468      *
1469      * @return external_function_parameters
1470      * @since Moodle 2.4
1471      */
1472     public static function import_course_parameters() {
1473         return new external_function_parameters(
1474             array(
1475                 'importfrom' => new external_value(PARAM_INT, 'the id of the course we are importing from'),
1476                 'importto' => new external_value(PARAM_INT, 'the id of the course we are importing to'),
1477                 'deletecontent' => new external_value(PARAM_INT, 'whether to delete the course content where we are importing to (default to 0 = No)', VALUE_DEFAULT, 0),
1478                 'options' => new external_multiple_structure(
1479                     new external_single_structure(
1480                         array(
1481                                 'name' => new external_value(PARAM_ALPHA, 'The backup option name:
1482                                             "activities" (int) Include course activites (default to 1 that is equal to yes),
1483                                             "blocks" (int) Include course blocks (default to 1 that is equal to yes),
1484                                             "filters" (int) Include course filters  (default to 1 that is equal to yes)'
1485                                             ),
1486                                 'value' => new external_value(PARAM_RAW, 'the value for the option 1 (yes) or 0 (no)'
1487                             )
1488                         )
1489                     ), VALUE_DEFAULT, array()
1490                 ),
1491             )
1492         );
1493     }
1494
1495     /**
1496      * Imports a course
1497      *
1498      * @param int $importfrom The id of the course we are importing from
1499      * @param int $importto The id of the course we are importing to
1500      * @param bool $deletecontent Whether to delete the course we are importing to content
1501      * @param array $options List of backup options
1502      * @return null
1503      * @since Moodle 2.4
1504      */
1505     public static function import_course($importfrom, $importto, $deletecontent = 0, $options = array()) {
1506         global $CFG, $USER, $DB;
1507         require_once($CFG->dirroot . '/backup/util/includes/backup_includes.php');
1508         require_once($CFG->dirroot . '/backup/util/includes/restore_includes.php');
1509
1510         // Parameter validation.
1511         $params = self::validate_parameters(
1512             self::import_course_parameters(),
1513             array(
1514                 'importfrom' => $importfrom,
1515                 'importto' => $importto,
1516                 'deletecontent' => $deletecontent,
1517                 'options' => $options
1518             )
1519         );
1520
1521         if ($params['deletecontent'] !== 0 and $params['deletecontent'] !== 1) {
1522             throw new moodle_exception('invalidextparam', 'webservice', '', $params['deletecontent']);
1523         }
1524
1525         // Context validation.
1526
1527         if (! ($importfrom = $DB->get_record('course', array('id'=>$params['importfrom'])))) {
1528             throw new moodle_exception('invalidcourseid', 'error');
1529         }
1530
1531         if (! ($importto = $DB->get_record('course', array('id'=>$params['importto'])))) {
1532             throw new moodle_exception('invalidcourseid', 'error');
1533         }
1534
1535         $importfromcontext = context_course::instance($importfrom->id);
1536         self::validate_context($importfromcontext);
1537
1538         $importtocontext = context_course::instance($importto->id);
1539         self::validate_context($importtocontext);
1540
1541         $backupdefaults = array(
1542             'activities' => 1,
1543             'blocks' => 1,
1544             'filters' => 1
1545         );
1546
1547         $backupsettings = array();
1548
1549         // Check for backup and restore options.
1550         if (!empty($params['options'])) {
1551             foreach ($params['options'] as $option) {
1552
1553                 // Strict check for a correct value (allways 1 or 0, true or false).
1554                 $value = clean_param($option['value'], PARAM_INT);
1555
1556                 if ($value !== 0 and $value !== 1) {
1557                     throw new moodle_exception('invalidextparam', 'webservice', '', $option['name']);
1558                 }
1559
1560                 if (!isset($backupdefaults[$option['name']])) {
1561                     throw new moodle_exception('invalidextparam', 'webservice', '', $option['name']);
1562                 }
1563
1564                 $backupsettings[$option['name']] = $value;
1565             }
1566         }
1567
1568         // Capability checking.
1569
1570         require_capability('moodle/backup:backuptargetimport', $importfromcontext);
1571         require_capability('moodle/restore:restoretargetimport', $importtocontext);
1572
1573         $bc = new backup_controller(backup::TYPE_1COURSE, $importfrom->id, backup::FORMAT_MOODLE,
1574                 backup::INTERACTIVE_NO, backup::MODE_IMPORT, $USER->id);
1575
1576         foreach ($backupsettings as $name => $value) {
1577             $bc->get_plan()->get_setting($name)->set_value($value);
1578         }
1579
1580         $backupid       = $bc->get_backupid();
1581         $backupbasepath = $bc->get_plan()->get_basepath();
1582
1583         $bc->execute_plan();
1584         $bc->destroy();
1585
1586         // Restore the backup immediately.
1587
1588         // Check if we must delete the contents of the destination course.
1589         if ($params['deletecontent']) {
1590             $restoretarget = backup::TARGET_EXISTING_DELETING;
1591         } else {
1592             $restoretarget = backup::TARGET_EXISTING_ADDING;
1593         }
1594
1595         $rc = new restore_controller($backupid, $importto->id,
1596                 backup::INTERACTIVE_NO, backup::MODE_IMPORT, $USER->id, $restoretarget);
1597
1598         foreach ($backupsettings as $name => $value) {
1599             $rc->get_plan()->get_setting($name)->set_value($value);
1600         }
1601
1602         if (!$rc->execute_precheck()) {
1603             $precheckresults = $rc->get_precheck_results();
1604             if (is_array($precheckresults) && !empty($precheckresults['errors'])) {
1605                 if (empty($CFG->keeptempdirectoriesonbackup)) {
1606                     fulldelete($backupbasepath);
1607                 }
1608
1609                 $errorinfo = '';
1610
1611                 foreach ($precheckresults['errors'] as $error) {
1612                     $errorinfo .= $error;
1613                 }
1614
1615                 if (array_key_exists('warnings', $precheckresults)) {
1616                     foreach ($precheckresults['warnings'] as $warning) {
1617                         $errorinfo .= $warning;
1618                     }
1619                 }
1620
1621                 throw new moodle_exception('backupprecheckerrors', 'webservice', '', $errorinfo);
1622             }
1623         } else {
1624             if ($restoretarget == backup::TARGET_EXISTING_DELETING) {
1625                 restore_dbops::delete_course_content($importto->id);
1626             }
1627         }
1628
1629         $rc->execute_plan();
1630         $rc->destroy();
1631
1632         if (empty($CFG->keeptempdirectoriesonbackup)) {
1633             fulldelete($backupbasepath);
1634         }
1635
1636         return null;
1637     }
1638
1639     /**
1640      * Returns description of method result value
1641      *
1642      * @return external_description
1643      * @since Moodle 2.4
1644      */
1645     public static function import_course_returns() {
1646         return null;
1647     }
1648
1649     /**
1650      * Returns description of method parameters
1651      *
1652      * @return external_function_parameters
1653      * @since Moodle 2.3
1654      */
1655     public static function get_categories_parameters() {
1656         return new external_function_parameters(
1657             array(
1658                 'criteria' => new external_multiple_structure(
1659                     new external_single_structure(
1660                         array(
1661                             'key' => new external_value(PARAM_ALPHA,
1662                                          'The category column to search, expected keys (value format) are:'.
1663                                          '"id" (int) the category id,'.
1664                                          '"ids" (string) category ids separated by commas,'.
1665                                          '"name" (string) the category name,'.
1666                                          '"parent" (int) the parent category id,'.
1667                                          '"idnumber" (string) category idnumber'.
1668                                          ' - user must have \'moodle/category:manage\' to search on idnumber,'.
1669                                          '"visible" (int) whether the returned categories must be visible or hidden. If the key is not passed,
1670                                              then the function return all categories that the user can see.'.
1671                                          ' - user must have \'moodle/category:manage\' or \'moodle/category:viewhiddencategories\' to search on visible,'.
1672                                          '"theme" (string) only return the categories having this theme'.
1673                                          ' - user must have \'moodle/category:manage\' to search on theme'),
1674                             'value' => new external_value(PARAM_RAW, 'the value to match')
1675                         )
1676                     ), 'criteria', VALUE_DEFAULT, array()
1677                 ),
1678                 'addsubcategories' => new external_value(PARAM_BOOL, 'return the sub categories infos
1679                                           (1 - default) otherwise only the category info (0)', VALUE_DEFAULT, 1)
1680             )
1681         );
1682     }
1683
1684     /**
1685      * Get categories
1686      *
1687      * @param array $criteria Criteria to match the results
1688      * @param booln $addsubcategories obtain only the category (false) or its subcategories (true - default)
1689      * @return array list of categories
1690      * @since Moodle 2.3
1691      */
1692     public static function get_categories($criteria = array(), $addsubcategories = true) {
1693         global $CFG, $DB;
1694         require_once($CFG->dirroot . "/course/lib.php");
1695
1696         // Validate parameters.
1697         $params = self::validate_parameters(self::get_categories_parameters(),
1698                 array('criteria' => $criteria, 'addsubcategories' => $addsubcategories));
1699
1700         // Retrieve the categories.
1701         $categories = array();
1702         if (!empty($params['criteria'])) {
1703
1704             $conditions = array();
1705             $wheres = array();
1706             foreach ($params['criteria'] as $crit) {
1707                 $key = trim($crit['key']);
1708
1709                 // Trying to avoid duplicate keys.
1710                 if (!isset($conditions[$key])) {
1711
1712                     $context = context_system::instance();
1713                     $value = null;
1714                     switch ($key) {
1715                         case 'id':
1716                             $value = clean_param($crit['value'], PARAM_INT);
1717                             $conditions[$key] = $value;
1718                             $wheres[] = $key . " = :" . $key;
1719                             break;
1720
1721                         case 'ids':
1722                             $value = clean_param($crit['value'], PARAM_SEQUENCE);
1723                             $ids = explode(',', $value);
1724                             list($sqlids, $paramids) = $DB->get_in_or_equal($ids, SQL_PARAMS_NAMED);
1725                             $conditions = array_merge($conditions, $paramids);
1726                             $wheres[] = 'id ' . $sqlids;
1727                             break;
1728
1729                         case 'idnumber':
1730                             if (has_capability('moodle/category:manage', $context)) {
1731                                 $value = clean_param($crit['value'], PARAM_RAW);
1732                                 $conditions[$key] = $value;
1733                                 $wheres[] = $key . " = :" . $key;
1734                             } else {
1735                                 // We must throw an exception.
1736                                 // Otherwise the dev client would think no idnumber exists.
1737                                 throw new moodle_exception('criteriaerror',
1738                                         'webservice', '', null,
1739                                         'You don\'t have the permissions to search on the "idnumber" field.');
1740                             }
1741                             break;
1742
1743                         case 'name':
1744                             $value = clean_param($crit['value'], PARAM_TEXT);
1745                             $conditions[$key] = $value;
1746                             $wheres[] = $key . " = :" . $key;
1747                             break;
1748
1749                         case 'parent':
1750                             $value = clean_param($crit['value'], PARAM_INT);
1751                             $conditions[$key] = $value;
1752                             $wheres[] = $key . " = :" . $key;
1753                             break;
1754
1755                         case 'visible':
1756                             if (has_capability('moodle/category:viewhiddencategories', $context)) {
1757                                 $value = clean_param($crit['value'], PARAM_INT);
1758                                 $conditions[$key] = $value;
1759                                 $wheres[] = $key . " = :" . $key;
1760                             } else {
1761                                 throw new moodle_exception('criteriaerror',
1762                                         'webservice', '', null,
1763                                         'You don\'t have the permissions to search on the "visible" field.');
1764                             }
1765                             break;
1766
1767                         case 'theme':
1768                             if (has_capability('moodle/category:manage', $context)) {
1769                                 $value = clean_param($crit['value'], PARAM_THEME);
1770                                 $conditions[$key] = $value;
1771                                 $wheres[] = $key . " = :" . $key;
1772                             } else {
1773                                 throw new moodle_exception('criteriaerror',
1774                                         'webservice', '', null,
1775                                         'You don\'t have the permissions to search on the "theme" field.');
1776                             }
1777                             break;
1778
1779                         default:
1780                             throw new moodle_exception('criteriaerror',
1781                                     'webservice', '', null,
1782                                     'You can not search on this criteria: ' . $key);
1783                     }
1784                 }
1785             }
1786
1787             if (!empty($wheres)) {
1788                 $wheres = implode(" AND ", $wheres);
1789
1790                 $categories = $DB->get_records_select('course_categories', $wheres, $conditions);
1791
1792                 // Retrieve its sub subcategories (all levels).
1793                 if ($categories and !empty($params['addsubcategories'])) {
1794                     $newcategories = array();
1795
1796                     // Check if we required visible/theme checks.
1797                     $additionalselect = '';
1798                     $additionalparams = array();
1799                     if (isset($conditions['visible'])) {
1800                         $additionalselect .= ' AND visible = :visible';
1801                         $additionalparams['visible'] = $conditions['visible'];
1802                     }
1803                     if (isset($conditions['theme'])) {
1804                         $additionalselect .= ' AND theme= :theme';
1805                         $additionalparams['theme'] = $conditions['theme'];
1806                     }
1807
1808                     foreach ($categories as $category) {
1809                         $sqlselect = $DB->sql_like('path', ':path') . $additionalselect;
1810                         $sqlparams = array('path' => $category->path.'/%') + $additionalparams; // It will NOT include the specified category.
1811                         $subcategories = $DB->get_records_select('course_categories', $sqlselect, $sqlparams);
1812                         $newcategories = $newcategories + $subcategories;   // Both arrays have integer as keys.
1813                     }
1814                     $categories = $categories + $newcategories;
1815                 }
1816             }
1817
1818         } else {
1819             // Retrieve all categories in the database.
1820             $categories = $DB->get_records('course_categories');
1821         }
1822
1823         // The not returned categories. key => category id, value => reason of exclusion.
1824         $excludedcats = array();
1825
1826         // The returned categories.
1827         $categoriesinfo = array();
1828
1829         // We need to sort the categories by path.
1830         // The parent cats need to be checked by the algo first.
1831         usort($categories, "core_course_external::compare_categories_by_path");
1832
1833         foreach ($categories as $category) {
1834
1835             // Check if the category is a child of an excluded category, if yes exclude it too (excluded => do not return).
1836             $parents = explode('/', $category->path);
1837             unset($parents[0]); // First key is always empty because path start with / => /1/2/4.
1838             foreach ($parents as $parentid) {
1839                 // Note: when the parent exclusion was due to the context,
1840                 // the sub category could still be returned.
1841                 if (isset($excludedcats[$parentid]) and $excludedcats[$parentid] != 'context') {
1842                     $excludedcats[$category->id] = 'parent';
1843                 }
1844             }
1845
1846             // Check the user can use the category context.
1847             $context = context_coursecat::instance($category->id);
1848             try {
1849                 self::validate_context($context);
1850             } catch (Exception $e) {
1851                 $excludedcats[$category->id] = 'context';
1852
1853                 // If it was the requested category then throw an exception.
1854                 if (isset($params['categoryid']) && $category->id == $params['categoryid']) {
1855                     $exceptionparam = new stdClass();
1856                     $exceptionparam->message = $e->getMessage();
1857                     $exceptionparam->catid = $category->id;
1858                     throw new moodle_exception('errorcatcontextnotvalid', 'webservice', '', $exceptionparam);
1859                 }
1860             }
1861
1862             // Return the category information.
1863             if (!isset($excludedcats[$category->id])) {
1864
1865                 // Final check to see if the category is visible to the user.
1866                 if ($category->visible or has_capability('moodle/category:viewhiddencategories', $context)) {
1867
1868                     $categoryinfo = array();
1869                     $categoryinfo['id'] = $category->id;
1870                     $categoryinfo['name'] = external_format_string($category->name, $context);
1871                     list($categoryinfo['description'], $categoryinfo['descriptionformat']) =
1872                         external_format_text($category->description, $category->descriptionformat,
1873                                 $context->id, 'coursecat', 'description', null);
1874                     $categoryinfo['parent'] = $category->parent;
1875                     $categoryinfo['sortorder'] = $category->sortorder;
1876                     $categoryinfo['coursecount'] = $category->coursecount;
1877                     $categoryinfo['depth'] = $category->depth;
1878                     $categoryinfo['path'] = $category->path;
1879
1880                     // Some fields only returned for admin.
1881                     if (has_capability('moodle/category:manage', $context)) {
1882                         $categoryinfo['idnumber'] = $category->idnumber;
1883                         $categoryinfo['visible'] = $category->visible;
1884                         $categoryinfo['visibleold'] = $category->visibleold;
1885                         $categoryinfo['timemodified'] = $category->timemodified;
1886                         $categoryinfo['theme'] = clean_param($category->theme, PARAM_THEME);
1887                     }
1888
1889                     $categoriesinfo[] = $categoryinfo;
1890                 } else {
1891                     $excludedcats[$category->id] = 'visibility';
1892                 }
1893             }
1894         }
1895
1896         // Sorting the resulting array so it looks a bit better for the client developer.
1897         usort($categoriesinfo, "core_course_external::compare_categories_by_sortorder");
1898
1899         return $categoriesinfo;
1900     }
1901
1902     /**
1903      * Sort categories array by path
1904      * private function: only used by get_categories
1905      *
1906      * @param array $category1
1907      * @param array $category2
1908      * @return int result of strcmp
1909      * @since Moodle 2.3
1910      */
1911     private static function compare_categories_by_path($category1, $category2) {
1912         return strcmp($category1->path, $category2->path);
1913     }
1914
1915     /**
1916      * Sort categories array by sortorder
1917      * private function: only used by get_categories
1918      *
1919      * @param array $category1
1920      * @param array $category2
1921      * @return int result of strcmp
1922      * @since Moodle 2.3
1923      */
1924     private static function compare_categories_by_sortorder($category1, $category2) {
1925         return strcmp($category1['sortorder'], $category2['sortorder']);
1926     }
1927
1928     /**
1929      * Returns description of method result value
1930      *
1931      * @return external_description
1932      * @since Moodle 2.3
1933      */
1934     public static function get_categories_returns() {
1935         return new external_multiple_structure(
1936             new external_single_structure(
1937                 array(
1938                     'id' => new external_value(PARAM_INT, 'category id'),
1939                     'name' => new external_value(PARAM_TEXT, 'category name'),
1940                     'idnumber' => new external_value(PARAM_RAW, 'category id number', VALUE_OPTIONAL),
1941                     'description' => new external_value(PARAM_RAW, 'category description'),
1942                     'descriptionformat' => new external_format_value('description'),
1943                     'parent' => new external_value(PARAM_INT, 'parent category id'),
1944                     'sortorder' => new external_value(PARAM_INT, 'category sorting order'),
1945                     'coursecount' => new external_value(PARAM_INT, 'number of courses in this category'),
1946                     'visible' => new external_value(PARAM_INT, '1: available, 0:not available', VALUE_OPTIONAL),
1947                     'visibleold' => new external_value(PARAM_INT, '1: available, 0:not available', VALUE_OPTIONAL),
1948                     'timemodified' => new external_value(PARAM_INT, 'timestamp', VALUE_OPTIONAL),
1949                     'depth' => new external_value(PARAM_INT, 'category depth'),
1950                     'path' => new external_value(PARAM_TEXT, 'category path'),
1951                     'theme' => new external_value(PARAM_THEME, 'category theme', VALUE_OPTIONAL),
1952                 ), 'List of categories'
1953             )
1954         );
1955     }
1956
1957     /**
1958      * Returns description of method parameters
1959      *
1960      * @return external_function_parameters
1961      * @since Moodle 2.3
1962      */
1963     public static function create_categories_parameters() {
1964         return new external_function_parameters(
1965             array(
1966                 'categories' => new external_multiple_structure(
1967                         new external_single_structure(
1968                             array(
1969                                 'name' => new external_value(PARAM_TEXT, 'new category name'),
1970                                 'parent' => new external_value(PARAM_INT,
1971                                         'the parent category id inside which the new category will be created
1972                                          - set to 0 for a root category',
1973                                         VALUE_DEFAULT, 0),
1974                                 'idnumber' => new external_value(PARAM_RAW,
1975                                         'the new category idnumber', VALUE_OPTIONAL),
1976                                 'description' => new external_value(PARAM_RAW,
1977                                         'the new category description', VALUE_OPTIONAL),
1978                                 'descriptionformat' => new external_format_value('description', VALUE_DEFAULT),
1979                                 'theme' => new external_value(PARAM_THEME,
1980                                         'the new category theme. This option must be enabled on moodle',
1981                                         VALUE_OPTIONAL),
1982                         )
1983                     )
1984                 )
1985             )
1986         );
1987     }
1988
1989     /**
1990      * Create categories
1991      *
1992      * @param array $categories - see create_categories_parameters() for the array structure
1993      * @return array - see create_categories_returns() for the array structure
1994      * @since Moodle 2.3
1995      */
1996     public static function create_categories($categories) {
1997         global $DB;
1998
1999         $params = self::validate_parameters(self::create_categories_parameters(),
2000                         array('categories' => $categories));
2001
2002         $transaction = $DB->start_delegated_transaction();
2003
2004         $createdcategories = array();
2005         foreach ($params['categories'] as $category) {
2006             if ($category['parent']) {
2007                 if (!$DB->record_exists('course_categories', array('id' => $category['parent']))) {
2008                     throw new moodle_exception('unknowcategory');
2009                 }
2010                 $context = context_coursecat::instance($category['parent']);
2011             } else {
2012                 $context = context_system::instance();
2013             }
2014             self::validate_context($context);
2015             require_capability('moodle/category:manage', $context);
2016
2017             // this will validate format and throw an exception if there are errors
2018             external_validate_format($category['descriptionformat']);
2019
2020             $newcategory = core_course_category::create($category);
2021             $context = context_coursecat::instance($newcategory->id);
2022
2023             $createdcategories[] = array(
2024                 'id' => $newcategory->id,
2025                 'name' => external_format_string($newcategory->name, $context),
2026             );
2027         }
2028
2029         $transaction->allow_commit();
2030
2031         return $createdcategories;
2032     }
2033
2034     /**
2035      * Returns description of method parameters
2036      *
2037      * @return external_function_parameters
2038      * @since Moodle 2.3
2039      */
2040     public static function create_categories_returns() {
2041         return new external_multiple_structure(
2042             new external_single_structure(
2043                 array(
2044                     'id' => new external_value(PARAM_INT, 'new category id'),
2045                     'name' => new external_value(PARAM_TEXT, 'new category name'),
2046                 )
2047             )
2048         );
2049     }
2050
2051     /**
2052      * Returns description of method parameters
2053      *
2054      * @return external_function_parameters
2055      * @since Moodle 2.3
2056      */
2057     public static function update_categories_parameters() {
2058         return new external_function_parameters(
2059             array(
2060                 'categories' => new external_multiple_structure(
2061                     new external_single_structure(
2062                         array(
2063                             'id'       => new external_value(PARAM_INT, 'course id'),
2064                             'name' => new external_value(PARAM_TEXT, 'category name', VALUE_OPTIONAL),
2065                             'idnumber' => new external_value(PARAM_RAW, 'category id number', VALUE_OPTIONAL),
2066                             'parent' => new external_value(PARAM_INT, 'parent category id', VALUE_OPTIONAL),
2067                             'description' => new external_value(PARAM_RAW, 'category description', VALUE_OPTIONAL),
2068                             'descriptionformat' => new external_format_value('description', VALUE_DEFAULT),
2069                             'theme' => new external_value(PARAM_THEME,
2070                                     'the category theme. This option must be enabled on moodle', VALUE_OPTIONAL),
2071                         )
2072                     )
2073                 )
2074             )
2075         );
2076     }
2077
2078     /**
2079      * Update categories
2080      *
2081      * @param array $categories The list of categories to update
2082      * @return null
2083      * @since Moodle 2.3
2084      */
2085     public static function update_categories($categories) {
2086         global $DB;
2087
2088         // Validate parameters.
2089         $params = self::validate_parameters(self::update_categories_parameters(), array('categories' => $categories));
2090
2091         $transaction = $DB->start_delegated_transaction();
2092
2093         foreach ($params['categories'] as $cat) {
2094             $category = core_course_category::get($cat['id']);
2095
2096             $categorycontext = context_coursecat::instance($cat['id']);
2097             self::validate_context($categorycontext);
2098             require_capability('moodle/category:manage', $categorycontext);
2099
2100             // this will throw an exception if descriptionformat is not valid
2101             external_validate_format($cat['descriptionformat']);
2102
2103             $category->update($cat);
2104         }
2105
2106         $transaction->allow_commit();
2107     }
2108
2109     /**
2110      * Returns description of method result value
2111      *
2112      * @return external_description
2113      * @since Moodle 2.3
2114      */
2115     public static function update_categories_returns() {
2116         return null;
2117     }
2118
2119     /**
2120      * Returns description of method parameters
2121      *
2122      * @return external_function_parameters
2123      * @since Moodle 2.3
2124      */
2125     public static function delete_categories_parameters() {
2126         return new external_function_parameters(
2127             array(
2128                 'categories' => new external_multiple_structure(
2129                     new external_single_structure(
2130                         array(
2131                             'id' => new external_value(PARAM_INT, 'category id to delete'),
2132                             'newparent' => new external_value(PARAM_INT,
2133                                 'the parent category to move the contents to, if specified', VALUE_OPTIONAL),
2134                             'recursive' => new external_value(PARAM_BOOL, '1: recursively delete all contents inside this
2135                                 category, 0 (default): move contents to newparent or current parent category (except if parent is root)', VALUE_DEFAULT, 0)
2136                         )
2137                     )
2138                 )
2139             )
2140         );
2141     }
2142
2143     /**
2144      * Delete categories
2145      *
2146      * @param array $categories A list of category ids
2147      * @return array
2148      * @since Moodle 2.3
2149      */
2150     public static function delete_categories($categories) {
2151         global $CFG, $DB;
2152         require_once($CFG->dirroot . "/course/lib.php");
2153
2154         // Validate parameters.
2155         $params = self::validate_parameters(self::delete_categories_parameters(), array('categories' => $categories));
2156
2157         $transaction = $DB->start_delegated_transaction();
2158
2159         foreach ($params['categories'] as $category) {
2160             $deletecat = core_course_category::get($category['id'], MUST_EXIST);
2161             $context = context_coursecat::instance($deletecat->id);
2162             require_capability('moodle/category:manage', $context);
2163             self::validate_context($context);
2164             self::validate_context(get_category_or_system_context($deletecat->parent));
2165
2166             if ($category['recursive']) {
2167                 // If recursive was specified, then we recursively delete the category's contents.
2168                 if ($deletecat->can_delete_full()) {
2169                     $deletecat->delete_full(false);
2170                 } else {
2171                     throw new moodle_exception('youcannotdeletecategory', '', '', $deletecat->get_formatted_name());
2172                 }
2173             } else {
2174                 // In this situation, we don't delete the category's contents, we either move it to newparent or parent.
2175                 // If the parent is the root, moving is not supported (because a course must always be inside a category).
2176                 // We must move to an existing category.
2177                 if (!empty($category['newparent'])) {
2178                     $newparentcat = core_course_category::get($category['newparent']);
2179                 } else {
2180                     $newparentcat = core_course_category::get($deletecat->parent);
2181                 }
2182
2183                 // This operation is not allowed. We must move contents to an existing category.
2184                 if (!$newparentcat->id) {
2185                     throw new moodle_exception('movecatcontentstoroot');
2186                 }
2187
2188                 self::validate_context(context_coursecat::instance($newparentcat->id));
2189                 if ($deletecat->can_move_content_to($newparentcat->id)) {
2190                     $deletecat->delete_move($newparentcat->id, false);
2191                 } else {
2192                     throw new moodle_exception('youcannotdeletecategory', '', '', $deletecat->get_formatted_name());
2193                 }
2194             }
2195         }
2196
2197         $transaction->allow_commit();
2198     }
2199
2200     /**
2201      * Returns description of method parameters
2202      *
2203      * @return external_function_parameters
2204      * @since Moodle 2.3
2205      */
2206     public static function delete_categories_returns() {
2207         return null;
2208     }
2209
2210     /**
2211      * Describes the parameters for delete_modules.
2212      *
2213      * @return external_function_parameters
2214      * @since Moodle 2.5
2215      */
2216     public static function delete_modules_parameters() {
2217         return new external_function_parameters (
2218             array(
2219                 'cmids' => new external_multiple_structure(new external_value(PARAM_INT, 'course module ID',
2220                         VALUE_REQUIRED, '', NULL_NOT_ALLOWED), 'Array of course module IDs'),
2221             )
2222         );
2223     }
2224
2225     /**
2226      * Deletes a list of provided module instances.
2227      *
2228      * @param array $cmids the course module ids
2229      * @since Moodle 2.5
2230      */
2231     public static function delete_modules($cmids) {
2232         global $CFG, $DB;
2233
2234         // Require course file containing the course delete module function.
2235         require_once($CFG->dirroot . "/course/lib.php");
2236
2237         // Clean the parameters.
2238         $params = self::validate_parameters(self::delete_modules_parameters(), array('cmids' => $cmids));
2239
2240         // Keep track of the course ids we have performed a capability check on to avoid repeating.
2241         $arrcourseschecked = array();
2242
2243         foreach ($params['cmids'] as $cmid) {
2244             // Get the course module.
2245             $cm = $DB->get_record('course_modules', array('id' => $cmid), '*', MUST_EXIST);
2246
2247             // Check if we have not yet confirmed they have permission in this course.
2248             if (!in_array($cm->course, $arrcourseschecked)) {
2249                 // Ensure the current user has required permission in this course.
2250                 $context = context_course::instance($cm->course);
2251                 self::validate_context($context);
2252                 // Add to the array.
2253                 $arrcourseschecked[] = $cm->course;
2254             }
2255
2256             // Ensure they can delete this module.
2257             $modcontext = context_module::instance($cm->id);
2258             require_capability('moodle/course:manageactivities', $modcontext);
2259
2260             // Delete the module.
2261             course_delete_module($cm->id);
2262         }
2263     }
2264
2265     /**
2266      * Describes the delete_modules return value.
2267      *
2268      * @return external_single_structure
2269      * @since Moodle 2.5
2270      */
2271     public static function delete_modules_returns() {
2272         return null;
2273     }
2274
2275     /**
2276      * Returns description of method parameters
2277      *
2278      * @return external_function_parameters
2279      * @since Moodle 2.9
2280      */
2281     public static function view_course_parameters() {
2282         return new external_function_parameters(
2283             array(
2284                 'courseid' => new external_value(PARAM_INT, 'id of the course'),
2285                 'sectionnumber' => new external_value(PARAM_INT, 'section number', VALUE_DEFAULT, 0)
2286             )
2287         );
2288     }
2289
2290     /**
2291      * Trigger the course viewed event.
2292      *
2293      * @param int $courseid id of course
2294      * @param int $sectionnumber sectionnumber (0, 1, 2...)
2295      * @return array of warnings and status result
2296      * @since Moodle 2.9
2297      * @throws moodle_exception
2298      */
2299     public static function view_course($courseid, $sectionnumber = 0) {
2300         global $CFG;
2301         require_once($CFG->dirroot . "/course/lib.php");
2302
2303         $params = self::validate_parameters(self::view_course_parameters(),
2304                                             array(
2305                                                 'courseid' => $courseid,
2306                                                 'sectionnumber' => $sectionnumber
2307                                             ));
2308
2309         $warnings = array();
2310
2311         $course = get_course($params['courseid']);
2312         $context = context_course::instance($course->id);
2313         self::validate_context($context);
2314
2315         if (!empty($params['sectionnumber'])) {
2316
2317             // Get section details and check it exists.
2318             $modinfo = get_fast_modinfo($course);
2319             $coursesection = $modinfo->get_section_info($params['sectionnumber'], MUST_EXIST);
2320
2321             // Check user is allowed to see it.
2322             if (!$coursesection->uservisible) {
2323                 require_capability('moodle/course:viewhiddensections', $context);
2324             }
2325         }
2326
2327         course_view($context, $params['sectionnumber']);
2328
2329         $result = array();
2330         $result['status'] = true;
2331         $result['warnings'] = $warnings;
2332         return $result;
2333     }
2334
2335     /**
2336      * Returns description of method result value
2337      *
2338      * @return external_description
2339      * @since Moodle 2.9
2340      */
2341     public static function view_course_returns() {
2342         return new external_single_structure(
2343             array(
2344                 'status' => new external_value(PARAM_BOOL, 'status: true if success'),
2345                 'warnings' => new external_warnings()
2346             )
2347         );
2348     }
2349
2350     /**
2351      * Returns description of method parameters
2352      *
2353      * @return external_function_parameters
2354      * @since Moodle 3.0
2355      */
2356     public static function search_courses_parameters() {
2357         return new external_function_parameters(
2358             array(
2359                 'criterianame'  => new external_value(PARAM_ALPHA, 'criteria name
2360                                                         (search, modulelist (only admins), blocklist (only admins), tagid)'),
2361                 'criteriavalue' => new external_value(PARAM_RAW, 'criteria value'),
2362                 'page'          => new external_value(PARAM_INT, 'page number (0 based)', VALUE_DEFAULT, 0),
2363                 'perpage'       => new external_value(PARAM_INT, 'items per page', VALUE_DEFAULT, 0),
2364                 'requiredcapabilities' => new external_multiple_structure(
2365                     new external_value(PARAM_CAPABILITY, 'Capability string used to filter courses by permission'),
2366                     'Optional list of required capabilities (used to filter the list)', VALUE_DEFAULT, array()
2367                 ),
2368                 'limittoenrolled' => new external_value(PARAM_BOOL, 'limit to enrolled courses', VALUE_DEFAULT, 0),
2369             )
2370         );
2371     }
2372
2373     /**
2374      * Return the course information that is public (visible by every one)
2375      *
2376      * @param  core_course_list_element $course        course in list object
2377      * @param  stdClass       $coursecontext course context object
2378      * @return array the course information
2379      * @since  Moodle 3.2
2380      */
2381     protected static function get_course_public_information(core_course_list_element $course, $coursecontext) {
2382
2383         static $categoriescache = array();
2384
2385         // Category information.
2386         if (!array_key_exists($course->category, $categoriescache)) {
2387             $categoriescache[$course->category] = core_course_category::get($course->category, IGNORE_MISSING);
2388         }
2389         $category = $categoriescache[$course->category];
2390
2391         // Retrieve course overview used files.
2392         $files = array();
2393         foreach ($course->get_course_overviewfiles() as $file) {
2394             $fileurl = moodle_url::make_webservice_pluginfile_url($file->get_contextid(), $file->get_component(),
2395                                                                     $file->get_filearea(), null, $file->get_filepath(),
2396                                                                     $file->get_filename())->out(false);
2397             $files[] = array(
2398                 'filename' => $file->get_filename(),
2399                 'fileurl' => $fileurl,
2400                 'filesize' => $file->get_filesize(),
2401                 'filepath' => $file->get_filepath(),
2402                 'mimetype' => $file->get_mimetype(),
2403                 'timemodified' => $file->get_timemodified(),
2404             );
2405         }
2406
2407         // Retrieve the course contacts,
2408         // we need here the users fullname since if we are not enrolled can be difficult to obtain them via other Web Services.
2409         $coursecontacts = array();
2410         foreach ($course->get_course_contacts() as $contact) {
2411              $coursecontacts[] = array(
2412                 'id' => $contact['user']->id,
2413                 'fullname' => $contact['username'],
2414                 'roles' => array_map(function($role){
2415                     return array('id' => $role->id, 'name' => $role->displayname);
2416                 }, $contact['roles']),
2417                 'role' => array('id' => $contact['role']->id, 'name' => $contact['role']->displayname),
2418                 'rolename' => $contact['rolename']
2419              );
2420         }
2421
2422         // Allowed enrolment methods (maybe we can self-enrol).
2423         $enroltypes = array();
2424         $instances = enrol_get_instances($course->id, true);
2425         foreach ($instances as $instance) {
2426             $enroltypes[] = $instance->enrol;
2427         }
2428
2429         // Format summary.
2430         list($summary, $summaryformat) =
2431             external_format_text($course->summary, $course->summaryformat, $coursecontext->id, 'course', 'summary', null);
2432
2433         $categoryname = '';
2434         if (!empty($category)) {
2435             $categoryname = external_format_string($category->name, $category->get_context());
2436         }
2437
2438         $displayname = get_course_display_name_for_list($course);
2439         $coursereturns = array();
2440         $coursereturns['id']                = $course->id;
2441         $coursereturns['fullname']          = external_format_string($course->fullname, $coursecontext->id);
2442         $coursereturns['displayname']       = external_format_string($displayname, $coursecontext->id);
2443         $coursereturns['shortname']         = external_format_string($course->shortname, $coursecontext->id);
2444         $coursereturns['categoryid']        = $course->category;
2445         $coursereturns['categoryname']      = $categoryname;
2446         $coursereturns['summary']           = $summary;
2447         $coursereturns['summaryformat']     = $summaryformat;
2448         $coursereturns['summaryfiles']      = external_util::get_area_files($coursecontext->id, 'course', 'summary', false, false);
2449         $coursereturns['overviewfiles']     = $files;
2450         $coursereturns['contacts']          = $coursecontacts;
2451         $coursereturns['enrollmentmethods'] = $enroltypes;
2452         $coursereturns['sortorder']         = $course->sortorder;
2453         return $coursereturns;
2454     }
2455
2456     /**
2457      * Search courses following the specified criteria.
2458      *
2459      * @param string $criterianame  Criteria name (search, modulelist (only admins), blocklist (only admins), tagid)
2460      * @param string $criteriavalue Criteria value
2461      * @param int $page             Page number (for pagination)
2462      * @param int $perpage          Items per page
2463      * @param array $requiredcapabilities Optional list of required capabilities (used to filter the list).
2464      * @param int $limittoenrolled  Limit to only enrolled courses
2465      * @return array of course objects and warnings
2466      * @since Moodle 3.0
2467      * @throws moodle_exception
2468      */
2469     public static function search_courses($criterianame,
2470                                           $criteriavalue,
2471                                           $page=0,
2472                                           $perpage=0,
2473                                           $requiredcapabilities=array(),
2474                                           $limittoenrolled=0) {
2475         global $CFG;
2476
2477         $warnings = array();
2478
2479         $parameters = array(
2480             'criterianame'  => $criterianame,
2481             'criteriavalue' => $criteriavalue,
2482             'page'          => $page,
2483             'perpage'       => $perpage,
2484             'requiredcapabilities' => $requiredcapabilities
2485         );
2486         $params = self::validate_parameters(self::search_courses_parameters(), $parameters);
2487         self::validate_context(context_system::instance());
2488
2489         $allowedcriterianames = array('search', 'modulelist', 'blocklist', 'tagid');
2490         if (!in_array($params['criterianame'], $allowedcriterianames)) {
2491             throw new invalid_parameter_exception('Invalid value for criterianame parameter (value: '.$params['criterianame'].'),' .
2492                 'allowed values are: '.implode(',', $allowedcriterianames));
2493         }
2494
2495         if ($params['criterianame'] == 'modulelist' or $params['criterianame'] == 'blocklist') {
2496             require_capability('moodle/site:config', context_system::instance());
2497         }
2498
2499         $paramtype = array(
2500             'search' => PARAM_RAW,
2501             'modulelist' => PARAM_PLUGIN,
2502             'blocklist' => PARAM_INT,
2503             'tagid' => PARAM_INT
2504         );
2505         $params['criteriavalue'] = clean_param($params['criteriavalue'], $paramtype[$params['criterianame']]);
2506
2507         // Prepare the search API options.
2508         $searchcriteria = array();
2509         $searchcriteria[$params['criterianame']] = $params['criteriavalue'];
2510
2511         $options = array();
2512         if ($params['perpage'] != 0) {
2513             $offset = $params['page'] * $params['perpage'];
2514             $options = array('offset' => $offset, 'limit' => $params['perpage']);
2515         }
2516
2517         // Search the courses.
2518         $courses = core_course_category::search_courses($searchcriteria, $options, $params['requiredcapabilities']);
2519         $totalcount = core_course_category::search_courses_count($searchcriteria, $options, $params['requiredcapabilities']);
2520
2521         if (!empty($limittoenrolled)) {
2522             // Get the courses where the current user has access.
2523             $enrolled = enrol_get_my_courses(array('id', 'cacherev'));
2524         }
2525
2526         $finalcourses = array();
2527         $categoriescache = array();
2528
2529         foreach ($courses as $course) {
2530             if (!empty($limittoenrolled)) {
2531                 // Filter out not enrolled courses.
2532                 if (!isset($enrolled[$course->id])) {
2533                     $totalcount--;
2534                     continue;
2535                 }
2536             }
2537
2538             $coursecontext = context_course::instance($course->id);
2539
2540             $finalcourses[] = self::get_course_public_information($course, $coursecontext);
2541         }
2542
2543         return array(
2544             'total' => $totalcount,
2545             'courses' => $finalcourses,
2546             'warnings' => $warnings
2547         );
2548     }
2549
2550     /**
2551      * Returns a course structure definition
2552      *
2553      * @param  boolean $onlypublicdata set to true, to retrieve only fields viewable by anyone when the course is visible
2554      * @return array the course structure
2555      * @since  Moodle 3.2
2556      */
2557     protected static function get_course_structure($onlypublicdata = true) {
2558         $coursestructure = array(
2559             'id' => new external_value(PARAM_INT, 'course id'),
2560             'fullname' => new external_value(PARAM_TEXT, 'course full name'),
2561             'displayname' => new external_value(PARAM_TEXT, 'course display name'),
2562             'shortname' => new external_value(PARAM_TEXT, 'course short name'),
2563             'categoryid' => new external_value(PARAM_INT, 'category id'),
2564             'categoryname' => new external_value(PARAM_TEXT, 'category name'),
2565             'sortorder' => new external_value(PARAM_INT, 'Sort order in the category', VALUE_OPTIONAL),
2566             'summary' => new external_value(PARAM_RAW, 'summary'),
2567             'summaryformat' => new external_format_value('summary'),
2568             'summaryfiles' => new external_files('summary files in the summary field', VALUE_OPTIONAL),
2569             'overviewfiles' => new external_files('additional overview files attached to this course'),
2570             'contacts' => new external_multiple_structure(
2571                 new external_single_structure(
2572                     array(
2573                         'id' => new external_value(PARAM_INT, 'contact user id'),
2574                         'fullname'  => new external_value(PARAM_NOTAGS, 'contact user fullname'),
2575                     )
2576                 ),
2577                 'contact users'
2578             ),
2579             'enrollmentmethods' => new external_multiple_structure(
2580                 new external_value(PARAM_PLUGIN, 'enrollment method'),
2581                 'enrollment methods list'
2582             ),
2583             'customfields' => new external_multiple_structure(
2584                 new external_single_structure(
2585                     array(
2586                         'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
2587                         'shortname' => new external_value(PARAM_RAW,
2588                             'The shortname of the custom field - to be able to build the field class in the code'),
2589                         'type'  => new external_value(PARAM_ALPHANUMEXT,
2590                             'The type of the custom field - text field, checkbox...'),
2591                         'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
2592                     )
2593                 ), 'Custom fields', VALUE_OPTIONAL),
2594         );
2595
2596         if (!$onlypublicdata) {
2597             $extra = array(
2598                 'idnumber' => new external_value(PARAM_RAW, 'Id number', VALUE_OPTIONAL),
2599                 'format' => new external_value(PARAM_PLUGIN, 'Course format: weeks, topics, social, site,..', VALUE_OPTIONAL),
2600                 'showgrades' => new external_value(PARAM_INT, '1 if grades are shown, otherwise 0', VALUE_OPTIONAL),
2601                 'newsitems' => new external_value(PARAM_INT, 'Number of recent items appearing on the course page', VALUE_OPTIONAL),
2602                 'startdate' => new external_value(PARAM_INT, 'Timestamp when the course start', VALUE_OPTIONAL),
2603                 'enddate' => new external_value(PARAM_INT, 'Timestamp when the course end', VALUE_OPTIONAL),
2604                 'maxbytes' => new external_value(PARAM_INT, 'Largest size of file that can be uploaded into', VALUE_OPTIONAL),
2605                 'showreports' => new external_value(PARAM_INT, 'Are activity report shown (yes = 1, no =0)', VALUE_OPTIONAL),
2606                 'visible' => new external_value(PARAM_INT, '1: available to student, 0:not available', VALUE_OPTIONAL),
2607                 'groupmode' => new external_value(PARAM_INT, 'no group, separate, visible', VALUE_OPTIONAL),
2608                 'groupmodeforce' => new external_value(PARAM_INT, '1: yes, 0: no', VALUE_OPTIONAL),
2609                 'defaultgroupingid' => new external_value(PARAM_INT, 'default grouping id', VALUE_OPTIONAL),
2610                 'enablecompletion' => new external_value(PARAM_INT, 'Completion enabled? 1: yes 0: no', VALUE_OPTIONAL),
2611                 'completionnotify' => new external_value(PARAM_INT, '1: yes 0: no', VALUE_OPTIONAL),
2612                 'lang' => new external_value(PARAM_SAFEDIR, 'Forced course language', VALUE_OPTIONAL),
2613                 'theme' => new external_value(PARAM_PLUGIN, 'Fame of the forced theme', VALUE_OPTIONAL),
2614                 'marker' => new external_value(PARAM_INT, 'Current course marker', VALUE_OPTIONAL),
2615                 'legacyfiles' => new external_value(PARAM_INT, 'If legacy files are enabled', VALUE_OPTIONAL),
2616                 'calendartype' => new external_value(PARAM_PLUGIN, 'Calendar type', VALUE_OPTIONAL),
2617                 'timecreated' => new external_value(PARAM_INT, 'Time when the course was created', VALUE_OPTIONAL),
2618                 'timemodified' => new external_value(PARAM_INT, 'Last time  the course was updated', VALUE_OPTIONAL),
2619                 'requested' => new external_value(PARAM_INT, 'If is a requested course', VALUE_OPTIONAL),
2620                 'cacherev' => new external_value(PARAM_INT, 'Cache revision number', VALUE_OPTIONAL),
2621                 'filters' => new external_multiple_structure(
2622                     new external_single_structure(
2623                         array(
2624                             'filter'  => new external_value(PARAM_PLUGIN, 'Filter plugin name'),
2625                             'localstate' => new external_value(PARAM_INT, 'Filter state: 1 for on, -1 for off, 0 if inherit'),
2626                             'inheritedstate' => new external_value(PARAM_INT, '1 or 0 to use when localstate is set to inherit'),
2627                         )
2628                     ),
2629                     'Course filters', VALUE_OPTIONAL
2630                 ),
2631                 'courseformatoptions' => new external_multiple_structure(
2632                     new external_single_structure(
2633                         array(
2634                             'name' => new external_value(PARAM_RAW, 'Course format option name.'),
2635                             'value' => new external_value(PARAM_RAW, 'Course format option value.'),
2636                         )
2637                     ),
2638                     'Additional options for particular course format.', VALUE_OPTIONAL
2639                 ),
2640             );
2641             $coursestructure = array_merge($coursestructure, $extra);
2642         }
2643         return new external_single_structure($coursestructure);
2644     }
2645
2646     /**
2647      * Returns description of method result value
2648      *
2649      * @return external_description
2650      * @since Moodle 3.0
2651      */
2652     public static function search_courses_returns() {
2653         return new external_single_structure(
2654             array(
2655                 'total' => new external_value(PARAM_INT, 'total course count'),
2656                 'courses' => new external_multiple_structure(self::get_course_structure(), 'course'),
2657                 'warnings' => new external_warnings()
2658             )
2659         );
2660     }
2661
2662     /**
2663      * Returns description of method parameters
2664      *
2665      * @return external_function_parameters
2666      * @since Moodle 3.0
2667      */
2668     public static function get_course_module_parameters() {
2669         return new external_function_parameters(
2670             array(
2671                 'cmid' => new external_value(PARAM_INT, 'The course module id')
2672             )
2673         );
2674     }
2675
2676     /**
2677      * Return information about a course module.
2678      *
2679      * @param int $cmid the course module id
2680      * @return array of warnings and the course module
2681      * @since Moodle 3.0
2682      * @throws moodle_exception
2683      */
2684     public static function get_course_module($cmid) {
2685         global $CFG, $DB;
2686
2687         $params = self::validate_parameters(self::get_course_module_parameters(), array('cmid' => $cmid));
2688         $warnings = array();
2689
2690         $cm = get_coursemodule_from_id(null, $params['cmid'], 0, true, MUST_EXIST);
2691         $context = context_module::instance($cm->id);
2692         self::validate_context($context);
2693
2694         // If the user has permissions to manage the activity, return all the information.
2695         if (has_capability('moodle/course:manageactivities', $context)) {
2696             require_once($CFG->dirroot . '/course/modlib.php');
2697             require_once($CFG->libdir . '/gradelib.php');
2698
2699             $info = $cm;
2700             // Get the extra information: grade, advanced grading and outcomes data.
2701             $course = get_course($cm->course);
2702             list($newcm, $newcontext, $module, $extrainfo, $cw) = get_moduleinfo_data($cm, $course);
2703             // Grades.
2704             $gradeinfo = array('grade', 'gradepass', 'gradecat');
2705             foreach ($gradeinfo as $gfield) {
2706                 if (isset($extrainfo->{$gfield})) {
2707                     $info->{$gfield} = $extrainfo->{$gfield};
2708                 }
2709             }
2710             if (isset($extrainfo->grade) and $extrainfo->grade < 0) {
2711                 $info->scale = $DB->get_field('scale', 'scale', array('id' => abs($extrainfo->grade)));
2712             }
2713             // Advanced grading.
2714             if (isset($extrainfo->_advancedgradingdata)) {
2715                 $info->advancedgrading = array();
2716                 foreach ($extrainfo as $key => $val) {
2717                     if (strpos($key, 'advancedgradingmethod_') === 0) {
2718                         $info->advancedgrading[] = array(
2719                             'area' => str_replace('advancedgradingmethod_', '', $key),
2720                             'method' => $val
2721                         );
2722                     }
2723                 }
2724             }
2725             // Outcomes.
2726             foreach ($extrainfo as $key => $val) {
2727                 if (strpos($key, 'outcome_') === 0) {
2728                     if (!isset($info->outcomes)) {
2729                         $info->outcomes = array();
2730                     }
2731                     $id = str_replace('outcome_', '', $key);
2732                     $outcome = grade_outcome::fetch(array('id' => $id));
2733                     $scaleitems = $outcome->load_scale();
2734                     $info->outcomes[] = array(
2735                         'id' => $id,
2736                         'name' => external_format_string($outcome->get_name(), $context->id),
2737                         'scale' => $scaleitems->scale
2738                     );
2739                 }
2740             }
2741         } else {
2742             // Return information is safe to show to any user.
2743             $info = new stdClass();
2744             $info->id = $cm->id;
2745             $info->course = $cm->course;
2746             $info->module = $cm->module;
2747             $info->modname = $cm->modname;
2748             $info->instance = $cm->instance;
2749             $info->section = $cm->section;
2750             $info->sectionnum = $cm->sectionnum;
2751             $info->groupmode = $cm->groupmode;
2752             $info->groupingid = $cm->groupingid;
2753             $info->completion = $cm->completion;
2754         }
2755         // Format name.
2756         $info->name = external_format_string($cm->name, $context->id);
2757         $result = array();
2758         $result['cm'] = $info;
2759         $result['warnings'] = $warnings;
2760         return $result;
2761     }
2762
2763     /**
2764      * Returns description of method result value
2765      *
2766      * @return external_description
2767      * @since Moodle 3.0
2768      */
2769     public static function get_course_module_returns() {
2770         return new external_single_structure(
2771             array(
2772                 'cm' => new external_single_structure(
2773                     array(
2774                         'id' => new external_value(PARAM_INT, 'The course module id'),
2775                         'course' => new external_value(PARAM_INT, 'The course id'),
2776                         'module' => new external_value(PARAM_INT, 'The module type id'),
2777                         'name' => new external_value(PARAM_RAW, 'The activity name'),
2778                         'modname' => new external_value(PARAM_COMPONENT, 'The module component name (forum, assign, etc..)'),
2779                         'instance' => new external_value(PARAM_INT, 'The activity instance id'),
2780                         'section' => new external_value(PARAM_INT, 'The module section id'),
2781                         'sectionnum' => new external_value(PARAM_INT, 'The module section number'),
2782                         'groupmode' => new external_value(PARAM_INT, 'Group mode'),
2783                         'groupingid' => new external_value(PARAM_INT, 'Grouping id'),
2784                         'completion' => new external_value(PARAM_INT, 'If completion is enabled'),
2785                         'idnumber' => new external_value(PARAM_RAW, 'Module id number', VALUE_OPTIONAL),
2786                         'added' => new external_value(PARAM_INT, 'Time added', VALUE_OPTIONAL),
2787                         'score' => new external_value(PARAM_INT, 'Score', VALUE_OPTIONAL),
2788                         'indent' => new external_value(PARAM_INT, 'Indentation', VALUE_OPTIONAL),
2789                         'visible' => new external_value(PARAM_INT, 'If visible', VALUE_OPTIONAL),
2790                         'visibleoncoursepage' => new external_value(PARAM_INT, 'If visible on course page', VALUE_OPTIONAL),
2791                         'visibleold' => new external_value(PARAM_INT, 'Visible old', VALUE_OPTIONAL),
2792                         'completiongradeitemnumber' => new external_value(PARAM_INT, 'Completion grade item', VALUE_OPTIONAL),
2793                         'completionview' => new external_value(PARAM_INT, 'Completion view setting', VALUE_OPTIONAL),
2794                         'completionexpected' => new external_value(PARAM_INT, 'Completion time expected', VALUE_OPTIONAL),
2795                         'showdescription' => new external_value(PARAM_INT, 'If the description is showed', VALUE_OPTIONAL),
2796                         'availability' => new external_value(PARAM_RAW, 'Availability settings', VALUE_OPTIONAL),
2797                         'grade' => new external_value(PARAM_FLOAT, 'Grade (max value or scale id)', VALUE_OPTIONAL),
2798                         'scale' => new external_value(PARAM_TEXT, 'Scale items (if used)', VALUE_OPTIONAL),
2799                         'gradepass' => new external_value(PARAM_RAW, 'Grade to pass (float)', VALUE_OPTIONAL),
2800                         'gradecat' => new external_value(PARAM_INT, 'Grade category', VALUE_OPTIONAL),
2801                         'advancedgrading' => new external_multiple_structure(
2802                             new external_single_structure(
2803                                 array(
2804                                     'area' => new external_value(PARAM_AREA, 'Gradable area name'),
2805                                     'method'  => new external_value(PARAM_COMPONENT, 'Grading method'),
2806                                 )
2807                             ),
2808                             'Advanced grading settings', VALUE_OPTIONAL
2809                         ),
2810                         'outcomes' => new external_multiple_structure(
2811                             new external_single_structure(
2812                                 array(
2813                                     'id' => new external_value(PARAM_ALPHANUMEXT, 'Outcome id'),
2814                                     'name'  => new external_value(PARAM_TEXT, 'Outcome full name'),
2815                                     'scale' => new external_value(PARAM_TEXT, 'Scale items')
2816                                 )
2817                             ),
2818                             'Outcomes information', VALUE_OPTIONAL
2819                         ),
2820                     )
2821                 ),
2822                 'warnings' => new external_warnings()
2823             )
2824         );
2825     }
2826
2827     /**
2828      * Returns description of method parameters
2829      *
2830      * @return external_function_parameters
2831      * @since Moodle 3.0
2832      */
2833     public static function get_course_module_by_instance_parameters() {
2834         return new external_function_parameters(
2835             array(
2836                 'module' => new external_value(PARAM_COMPONENT, 'The module name'),
2837                 'instance' => new external_value(PARAM_INT, 'The module instance id')
2838             )
2839         );
2840     }
2841
2842     /**
2843      * Return information about a course module.
2844      *
2845      * @param string $module the module name
2846      * @param int $instance the activity instance id
2847      * @return array of warnings and the course module
2848      * @since Moodle 3.0
2849      * @throws moodle_exception
2850      */
2851     public static function get_course_module_by_instance($module, $instance) {
2852
2853         $params = self::validate_parameters(self::get_course_module_by_instance_parameters(),
2854                                             array(
2855                                                 'module' => $module,
2856                                                 'instance' => $instance,
2857                                             ));
2858
2859         $warnings = array();
2860         $cm = get_coursemodule_from_instance($params['module'], $params['instance'], 0, false, MUST_EXIST);
2861
2862         return self::get_course_module($cm->id);
2863     }
2864
2865     /**
2866      * Returns description of method result value
2867      *
2868      * @return external_description
2869      * @since Moodle 3.0
2870      */
2871     public static function get_course_module_by_instance_returns() {
2872         return self::get_course_module_returns();
2873     }
2874
2875     /**
2876      * Returns description of method parameters
2877      *
2878      * @deprecated since 3.3
2879      * @todo The final deprecation of this function will take place in Moodle 3.7 - see MDL-57487.
2880      * @return external_function_parameters
2881      * @since Moodle 3.2
2882      */
2883     public static function get_activities_overview_parameters() {
2884         return new external_function_parameters(
2885             array(
2886                 'courseids' => new external_multiple_structure(new external_value(PARAM_INT, 'Course id.')),
2887             )
2888         );
2889     }
2890
2891     /**
2892      * Return activities overview for the given courses.
2893      *
2894      * @deprecated since 3.3
2895      * @todo The final deprecation of this function will take place in Moodle 3.7 - see MDL-57487.
2896      * @param array $courseids a list of course ids
2897      * @return array of warnings and the activities overview
2898      * @since Moodle 3.2
2899      * @throws moodle_exception
2900      */
2901     public static function get_activities_overview($courseids) {
2902         global $USER;
2903
2904         // Parameter validation.
2905         $params = self::validate_parameters(self::get_activities_overview_parameters(), array('courseids' => $courseids));
2906         $courseoverviews = array();
2907
2908         list($courses, $warnings) = external_util::validate_courses($params['courseids']);
2909
2910         if (!empty($courses)) {
2911             // Add lastaccess to each course (required by print_overview function).
2912             // We need the complete user data, the ws server does not load a complete one.
2913             $user = get_complete_user_data('id', $USER->id);
2914             foreach ($courses as $course) {
2915                 if (isset($user->lastcourseaccess[$course->id])) {
2916                     $course->lastaccess = $user->lastcourseaccess[$course->id];
2917                 } else {
2918                     $course->lastaccess = 0;
2919                 }
2920             }
2921
2922             $overviews = array();
2923             if ($modules = get_plugin_list_with_function('mod', 'print_overview')) {
2924                 foreach ($modules as $fname) {
2925                     $fname($courses, $overviews);
2926                 }
2927             }
2928
2929             // Format output.
2930             foreach ($overviews as $courseid => $modules) {
2931                 $courseoverviews[$courseid]['id'] = $courseid;
2932                 $courseoverviews[$courseid]['overviews'] = array();
2933
2934                 foreach ($modules as $modname => $overviewtext) {
2935                     $courseoverviews[$courseid]['overviews'][] = array(
2936                         'module' => $modname,
2937                         'overviewtext' => $overviewtext // This text doesn't need formatting.
2938                     );
2939                 }
2940             }
2941         }
2942
2943         $result = array(
2944             'courses' => $courseoverviews,
2945             'warnings' => $warnings
2946         );
2947         return $result;
2948     }
2949
2950     /**
2951      * Returns description of method result value
2952      *
2953      * @deprecated since 3.3
2954      * @todo The final deprecation of this function will take place in Moodle 3.7 - see MDL-57487.
2955      * @return external_description
2956      * @since Moodle 3.2
2957      */
2958     public static function get_activities_overview_returns() {
2959         return new external_single_structure(
2960             array(
2961                 'courses' => new external_multiple_structure(
2962                     new external_single_structure(
2963                         array(
2964                             'id' => new external_value(PARAM_INT, 'Course id'),
2965                             'overviews' => new external_multiple_structure(
2966                                 new external_single_structure(
2967                                     array(
2968                                         'module' => new external_value(PARAM_PLUGIN, 'Module name'),
2969                                         'overviewtext' => new external_value(PARAM_RAW, 'Overview text'),
2970                                     )
2971                                 )
2972                             )
2973                         )
2974                     ), 'List of courses'
2975                 ),
2976                 'warnings' => new external_warnings()
2977             )
2978         );
2979     }
2980
2981     /**
2982      *