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 require_once("$CFG->libdir/externallib.php");
  30
  31 /**
  32  * Course external functions
  33  *
  34  * @package    core_course
  35  * @category   external
  36  * @copyright  2011 Jerome Mouneyrac
  37  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  38  * @since Moodle 2.2
  39  */
  40 class core_course_external extends external_api {
  41
  42     /**
  43      * Returns description of method parameters
  44      *
  45      * @return external_function_parameters
  46      * @since Moodle 2.2
  47      */
  48     public static function get_course_contents_parameters() {
  49         return new external_function_parameters(
  50                 array('courseid' => new external_value(PARAM_INT, 'course id'),
  51                       'options' => new external_multiple_structure (
  52                               new external_single_structure(
  53                                     array('name' => new external_value(PARAM_ALPHANUM, 'option name'),
  54                                           'value' => new external_value(PARAM_RAW, 'the value of the option, this param is personaly validated in the external function.')
  55                               )
  56                       ), 'Options, not used yet, might be used in later version', VALUE_DEFAULT, array())
  57                 )
  58         );
  59     }
  60
  61     /**
  62      * Get course contents
  63      *
  64      * @param int $courseid course id
  65      * @param array $options These options are not used yet, might be used in later version
  66      * @return array
  67      * @since Moodle 2.2
  68      */
  69     public static function get_course_contents($courseid, $options) {
  70         global $CFG, $DB;
  71         require_once($CFG->dirroot . "/course/lib.php");
  72
  73         //validate parameter
  74         $params = self::validate_parameters(self::get_course_contents_parameters(),
  75                         array('courseid' => $courseid, 'options' => $options));
  76
  77         //retrieve the course
  78         $course = $DB->get_record('course', array('id' => $params['courseid']), '*', MUST_EXIST);
  79
  80         //check course format exist
  81         if (!file_exists($CFG->dirroot . '/course/format/' . $course->format . '/lib.php')) {
  82             throw new moodle_exception('cannotgetcoursecontents', 'webservice', '', null, get_string('courseformatnotfound', 'error', '', $course->format));
  83         } else {
  84             require_once($CFG->dirroot . '/course/format/' . $course->format . '/lib.php');
  85         }
  86
  87         // now security checks
  88         $context = get_context_instance(CONTEXT_COURSE, $course->id);
  89         try {
  90             self::validate_context($context);
  91         } catch (Exception $e) {
  92             $exceptionparam = new stdClass();
  93             $exceptionparam->message = $e->getMessage();
  94             $exceptionparam->courseid = $course->id;
  95             throw new moodle_exception('errorcoursecontextnotvalid', 'webservice', '', $exceptionparam);
  96         }
  97
  98         $canupdatecourse = has_capability('moodle/course:update', $context);
  99
 100         //create return value
 101         $coursecontents = array();
 102
 103         if ($canupdatecourse or $course->visible
 104                 or has_capability('moodle/course:viewhiddencourses', $context)) {
 105
 106             //retrieve sections
 107             $modinfo = get_fast_modinfo($course);
 108             $sections = get_all_sections($course->id);
 109
 110             //for each sections (first displayed to last displayed)
 111             foreach ($sections as $key => $section) {
 112
 113                 $showsection = (has_capability('moodle/course:viewhiddensections', $context) or $section->visible or !$course->hiddensections);
 114                 if (!$showsection) {
 115                     continue;
 116                 }
 117
 118                 // reset $sectioncontents
 119                 $sectionvalues = array();
 120                 $sectionvalues['id'] = $section->id;
 121                 $sectionvalues['name'] = get_section_name($course, $section);
 122                 $summary = file_rewrite_pluginfile_urls($section->summary, 'webservice/pluginfile.php', $context->id, 'course', 'section', $section->id);
 123                 $sectionvalues['visible'] = $section->visible;
 124                 $sectionvalues['summary'] = format_text($summary, $section->summaryformat);
 125                 $sectioncontents = array();
 126
 127                 //for each module of the section
 128                 foreach ($modinfo->sections[$section->section] as $cmid) { //matching /course/lib.php:print_section() logic
 129                     $cm = $modinfo->cms[$cmid];
 130
 131                     // stop here if the module is not visible to the user
 132                     if (!$cm->uservisible) {
 133                         continue;
 134                     }
 135
 136                     $module = array();
 137
 138                     //common info (for people being able to see the module or availability dates)
 139                     $module['id'] = $cm->id;
 140                     $module['name'] = format_string($cm->name, true);
 141                     $module['modname'] = $cm->modname;
 142                     $module['modplural'] = $cm->modplural;
 143                     $module['modicon'] = $cm->get_icon_url()->out(false);
 144                     $module['indent'] = $cm->indent;
 145
 146                     $modcontext = get_context_instance(CONTEXT_MODULE, $cm->id);
 147
 148                     if (!empty($cm->showdescription)) {
 149                         $module['description'] = $cm->get_content();
 150                     }
 151
 152                     //url of the module
 153                     $url = $cm->get_url();
 154                     if ($url) { //labels don't have url
 155                         $module['url'] = $cm->get_url()->out();
 156                     }
 157
 158                     $canviewhidden = has_capability('moodle/course:viewhiddenactivities',
 159                                         get_context_instance(CONTEXT_MODULE, $cm->id));
 160                     //user that can view hidden module should know about the visibility
 161                     $module['visible'] = $cm->visible;
 162
 163                     //availability date (also send to user who can see hidden module when the showavailabilyt is ON)
 164                     if ($canupdatecourse or ($CFG->enableavailability && $canviewhidden && $cm->showavailability)) {
 165                         $module['availablefrom'] = $cm->availablefrom;
 166                         $module['availableuntil'] = $cm->availableuntil;
 167                     }
 168
 169                     $baseurl = 'webservice/pluginfile.php';
 170
 171                     //call $modulename_export_contents
 172                     //(each module callback take care about checking the capabilities)
 173                     require_once($CFG->dirroot . '/mod/' . $cm->modname . '/lib.php');
 174                     $getcontentfunction = $cm->modname.'_export_contents';
 175                     if (function_exists($getcontentfunction)) {
 176                         if ($contents = $getcontentfunction($cm, $baseurl)) {
 177                             $module['contents'] = $contents;
 178                         }
 179                     }
 180
 181                     //assign result to $sectioncontents
 182                     $sectioncontents[] = $module;
 183
 184                 }
 185                 $sectionvalues['modules'] = $sectioncontents;
 186
 187                 // assign result to $coursecontents
 188                 $coursecontents[] = $sectionvalues;
 189             }
 190         }
 191         return $coursecontents;
 192     }
 193
 194     /**
 195      * Returns description of method result value
 196      *
 197      * @return external_description
 198      * @since Moodle 2.2
 199      */
 200     public static function get_course_contents_returns() {
 201         return new external_multiple_structure(
 202             new external_single_structure(
 203                 array(
 204                     'id' => new external_value(PARAM_INT, 'Section ID'),
 205                     'name' => new external_value(PARAM_TEXT, 'Section name'),
 206                     'visible' => new external_value(PARAM_INT, 'is the section visible', VALUE_OPTIONAL),
 207                     'summary' => new external_value(PARAM_RAW, 'Section description'),
 208                     'modules' => new external_multiple_structure(
 209                             new external_single_structure(
 210                                 array(
 211                                     'id' => new external_value(PARAM_INT, 'activity id'),
 212                                     'url' => new external_value(PARAM_URL, 'activity url', VALUE_OPTIONAL),
 213                                     'name' => new external_value(PARAM_TEXT, 'activity module name'),
 214                                     'description' => new external_value(PARAM_RAW, 'activity description', VALUE_OPTIONAL),
 215                                     'visible' => new external_value(PARAM_INT, 'is the module visible', VALUE_OPTIONAL),
 216                                     'modicon' => new external_value(PARAM_URL, 'activity icon url'),
 217                                     'modname' => new external_value(PARAM_PLUGIN, 'activity module type'),
 218                                     'modplural' => new external_value(PARAM_TEXT, 'activity module plural name'),
 219                                     'availablefrom' => new external_value(PARAM_INT, 'module availability start date', VALUE_OPTIONAL),
 220                                     'availableuntil' => new external_value(PARAM_INT, 'module availability en date', VALUE_OPTIONAL),
 221                                     'indent' => new external_value(PARAM_INT, 'number of identation in the site'),
 222                                     'contents' => new external_multiple_structure(
 223                                           new external_single_structure(
 224                                               array(
 225                                                   // content info
 226                                                   'type'=> new external_value(PARAM_TEXT, 'a file or a folder or external link'),
 227                                                   'filename'=> new external_value(PARAM_FILE, 'filename'),
 228                                                   'filepath'=> new external_value(PARAM_PATH, 'filepath'),
 229                                                   'filesize'=> new external_value(PARAM_INT, 'filesize'),
 230                                                   'fileurl' => new external_value(PARAM_URL, 'downloadable file url', VALUE_OPTIONAL),
 231                                                   'content' => new external_value(PARAM_RAW, 'Raw content, will be used when type is content', VALUE_OPTIONAL),
 232                                                   'timecreated' => new external_value(PARAM_INT, 'Time created'),
 233                                                   'timemodified' => new external_value(PARAM_INT, 'Time modified'),
 234                                                   'sortorder' => new external_value(PARAM_INT, 'Content sort order'),
 235
 236                                                   // copyright related info
 237                                                   'userid' => new external_value(PARAM_INT, 'User who added this content to moodle'),
 238                                                   'author' => new external_value(PARAM_TEXT, 'Content owner'),
 239                                                   'license' => new external_value(PARAM_TEXT, 'Content license'),
 240                                               )
 241                                           ), VALUE_DEFAULT, array()
 242                                       )
 243                                 )
 244                             ), 'list of module'
 245                     )
 246                 )
 247             )
 248         );
 249     }
 250
 251     /**
 252      * Returns description of method parameters
 253      *
 254      * @return external_function_parameters
 255      * @since Moodle 2.2
 256      */
 257     public static function get_courses_parameters() {
 258         return new external_function_parameters(
 259                 array('options' => new external_single_structure(
 260                             array('ids' => new external_multiple_structure(
 261                                         new external_value(PARAM_INT, 'Course id')
 262                                         , 'List of course id. If empty return all courses
 263                                             except front page course.',
 264                                         VALUE_OPTIONAL)
 265                             ), 'options - operator OR is used', VALUE_DEFAULT, array())
 266                 )
 267         );
 268     }
 269
 270     /**
 271      * Get courses
 272      *
 273      * @param array $options It contains an array (list of ids)
 274      * @return array
 275      * @since Moodle 2.2
 276      */
 277     public static function get_courses($options) {
 278         global $CFG, $DB;
 279         require_once($CFG->dirroot . "/course/lib.php");
 280
 281         //validate parameter
 282         $params = self::validate_parameters(self::get_courses_parameters(),
 283                         array('options' => $options));
 284
 285         //retrieve courses
 286         if (!key_exists('ids', $params['options'])
 287                 or empty($params['options']['ids'])) {
 288             $courses = $DB->get_records('course');
 289         } else {
 290             $courses = $DB->get_records_list('course', 'id', $params['options']['ids']);
 291         }
 292
 293         //create return value
 294         $coursesinfo = array();
 295         foreach ($courses as $course) {
 296
 297             // now security checks
 298             $context = get_context_instance(CONTEXT_COURSE, $course->id);
 299             try {
 300                 self::validate_context($context);
 301             } catch (Exception $e) {
 302                 $exceptionparam = new stdClass();
 303                 $exceptionparam->message = $e->getMessage();
 304                 $exceptionparam->courseid = $course->id;
 305                 throw new moodle_exception(
 306                         get_string('errorcoursecontextnotvalid', 'webservice', $exceptionparam));
 307             }
 308             require_capability('moodle/course:view', $context);
 309
 310             $courseinfo = array();
 311             $courseinfo['id'] = $course->id;
 312             $courseinfo['fullname'] = $course->fullname;
 313             $courseinfo['shortname'] = $course->shortname;
 314             $courseinfo['categoryid'] = $course->category;
 315             $courseinfo['summary'] = $course->summary;
 316             $courseinfo['summaryformat'] = $course->summaryformat;
 317             $courseinfo['format'] = $course->format;
 318             $courseinfo['startdate'] = $course->startdate;
 319             $courseinfo['numsections'] = $course->numsections;
 320
 321             //some field should be returned only if the user has update permission
 322             $courseadmin = has_capability('moodle/course:update', $context);
 323             if ($courseadmin) {
 324                 $courseinfo['categorysortorder'] = $course->sortorder;
 325                 $courseinfo['idnumber'] = $course->idnumber;
 326                 $courseinfo['showgrades'] = $course->showgrades;
 327                 $courseinfo['showreports'] = $course->showreports;
 328                 $courseinfo['newsitems'] = $course->newsitems;
 329                 $courseinfo['visible'] = $course->visible;
 330                 $courseinfo['maxbytes'] = $course->maxbytes;
 331                 $courseinfo['hiddensections'] = $course->hiddensections;
 332                 $courseinfo['groupmode'] = $course->groupmode;
 333                 $courseinfo['groupmodeforce'] = $course->groupmodeforce;
 334                 $courseinfo['defaultgroupingid'] = $course->defaultgroupingid;
 335                 $courseinfo['lang'] = $course->lang;
 336                 $courseinfo['timecreated'] = $course->timecreated;
 337                 $courseinfo['timemodified'] = $course->timemodified;
 338                 $courseinfo['forcetheme'] = $course->theme;
 339                 $courseinfo['enablecompletion'] = $course->enablecompletion;
 340                 $courseinfo['completionstartonenrol'] = $course->completionstartonenrol;
 341                 $courseinfo['completionnotify'] = $course->completionnotify;
 342             }
 343
 344             if ($courseadmin or $course->visible
 345                     or has_capability('moodle/course:viewhiddencourses', $context)) {
 346                 $coursesinfo[] = $courseinfo;
 347             }
 348         }
 349
 350         return $coursesinfo;
 351     }
 352
 353     /**
 354      * Returns description of method result value
 355      *
 356      * @return external_description
 357      * @since Moodle 2.2
 358      */
 359     public static function get_courses_returns() {
 360         return new external_multiple_structure(
 361                 new external_single_structure(
 362                         array(
 363                             'id' => new external_value(PARAM_INT, 'course id'),
 364                             'shortname' => new external_value(PARAM_TEXT, 'course short name'),
 365                             'categoryid' => new external_value(PARAM_INT, 'category id'),
 366                             'categorysortorder' => new external_value(PARAM_INT,
 367                                     'sort order into the category', VALUE_OPTIONAL),
 368                             'fullname' => new external_value(PARAM_TEXT, 'full name'),
 369                             'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL),
 370                             'summary' => new external_value(PARAM_RAW, 'summary'),
 371                             'summaryformat' => new external_value(PARAM_INT,
 372                                     'the summary text Moodle format'),
 373                             'format' => new external_value(PARAM_PLUGIN,
 374                                     'course format: weeks, topics, social, site,..'),
 375                             'showgrades' => new external_value(PARAM_INT,
 376                                     '1 if grades are shown, otherwise 0', VALUE_OPTIONAL),
 377                             'newsitems' => new external_value(PARAM_INT,
 378                                     'number of recent items appearing on the course page', VALUE_OPTIONAL),
 379                             'startdate' => new external_value(PARAM_INT,
 380                                     'timestamp when the course start'),
 381                             'numsections' => new external_value(PARAM_INT, 'number of weeks/topics'),
 382                             'maxbytes' => new external_value(PARAM_INT,
 383                                     'largest size of file that can be uploaded into the course',
 384                                     VALUE_OPTIONAL),
 385                             'showreports' => new external_value(PARAM_INT,
 386                                     'are activity report shown (yes = 1, no =0)', VALUE_OPTIONAL),
 387                             'visible' => new external_value(PARAM_INT,
 388                                     '1: available to student, 0:not available', VALUE_OPTIONAL),
 389                             'hiddensections' => new external_value(PARAM_INT,
 390                                     'How the hidden sections in the course are displayed to students',
 391                                     VALUE_OPTIONAL),
 392                             'groupmode' => new external_value(PARAM_INT, 'no group, separate, visible',
 393                                     VALUE_OPTIONAL),
 394                             'groupmodeforce' => new external_value(PARAM_INT, '1: yes, 0: no',
 395                                     VALUE_OPTIONAL),
 396                             'defaultgroupingid' => new external_value(PARAM_INT, 'default grouping id',
 397                                     VALUE_OPTIONAL),
 398                             'timecreated' => new external_value(PARAM_INT,
 399                                     'timestamp when the course have been created', VALUE_OPTIONAL),
 400                             'timemodified' => new external_value(PARAM_INT,
 401                                     'timestamp when the course have been modified', VALUE_OPTIONAL),
 402                             'enablecompletion' => new external_value(PARAM_INT,
 403                                     'Enabled, control via completion and activity settings. Disbaled,
 404                                         not shown in activity settings.',
 405                                     VALUE_OPTIONAL),
 406                             'completionstartonenrol' => new external_value(PARAM_INT,
 407                                     '1: begin tracking a student\'s progress in course completion
 408                                         after course enrolment. 0: does not',
 409                                     VALUE_OPTIONAL),
 410                             'completionnotify' => new external_value(PARAM_INT,
 411                                     '1: yes 0: no', VALUE_OPTIONAL),
 412                             'lang' => new external_value(PARAM_SAFEDIR,
 413                                     'forced course language', VALUE_OPTIONAL),
 414                             'forcetheme' => new external_value(PARAM_PLUGIN,
 415                                     'name of the force theme', VALUE_OPTIONAL),
 416                         ), 'course'
 417                 )
 418         );
 419     }
 420
 421     /**
 422     * Returns description of method parameters
 423     *
 424     * @return external_function_parameters
 425     * @since Moodle 2.3
 426     * TODO is PARAM_CLEANHTML for the description enough secured?
 427     *      Is it possible to still pass some script tag that pass PARAM_CLEANHTML
 428     *      and execute dangereous javascript in the browser?
 429     */
 430     public static function create_categories_parameters() {
 431         return new external_function_parameters(
 432             array(
 433                 'categories' => new external_multiple_structure(
 434                         new external_single_structure(
 435                             array(
 436                                 'name' => new external_value(PARAM_TEXT, 'new category name'),
 437                                 'parent' => new external_value(PARAM_INT, 'the parent category id inside which the new category will be created'),
 438                                 'idnumber' => new external_value(PARAM_RAW, 'the new category idnumber', VALUE_OPTIONAL),
 439                                 'description' => new external_value(PARAM_CLEANHTML, 'the new category description', VALUE_OPTIONAL),
 440                                 'theme' => new external_value(PARAM_THEME,
 441                                         'the new category theme. This option must be enabled on moodle', VALUE_OPTIONAL),
 442                         )
 443                     )
 444                 )
 445             )
 446         );
 447     }
 448
 449     /**
 450      * Create categories
 451      *
 452      * @param array $categories - see create_categories_parameters() for the array structure
 453      * @return array - see create_categories_returns() for the array structure
 454      * @since Moodle 2.3
 455      * TODO: check exceptions
 456      */
 457     public static function create_categories($categories) {
 458         global $CFG, $DB;
 459         require_once($CFG->dirroot . "/course/lib.php");
 460
 461         $params = self::validate_parameters(self::create_categories_parameters(),
 462                         array('categories' => $categories));
 463
 464         $transaction = $DB->start_delegated_transaction();
 465
 466         $createdcategories = array();
 467         foreach($params['categories'] as $category) {
 468
 469             $newcategory = new stdClass();
 470             $newcategory->sortorder = 999; //same as in the course/editcategory.php
 471             $newcategory->parent = $category['parent'];
 472
 473             if ($category['parent']) {
 474                 if (!$DB->record_exists('course_categories', array('id' => $category['parent']))) {
 475                     throw new moodle_exception('unknowncategory');
 476                 }
 477                 $context = context_coursecat::instance($category['parent']);
 478             }
 479             else {
 480                 $context = context_system::instance();
 481             }
 482             self::validate_context($context);
 483             require_capability('moodle/category:manage', $context);
 484
 485             //check id number
 486             if (!empty($category['idnumber'])) { //same as in course/editcategory_form.php
 487                 if (strlen($category['idnumber'])>100) {
 488                     throw new moodle_exception('id number is too long');
 489                 }
 490
 491                 if ($existing = $DB->get_record('course_categories', array('idnumber' => $category['idnumber']))) {
 492                     if ($existing->id) {
 493                         throw new moodle_exception('idnumbertaken');
 494                     }
 495                 }
 496             }
 497             $newcategory->idnumber = $category['idnumber'];
 498
 499             //check name
 500             if (strlen($category['name'])>30) {
 501                     throw new moodle_exception('category name is too long.');
 502             }
 503             $newcategory->name = $category['name'];
 504
 505             //Format the description
 506             if (!empty($newcategory->description)) {
 507                 $options = new stdClass();
 508                 $options->para = false;
 509                 $options->newlines = false;
 510                 $options->context = $context;
 511                 $newcategory->description = format_text($category['description'], FORMAT_HTML, $options);
 512             }
 513             $newcategory->descriptionformat = FORMAT_HTML;
 514
 515             if (isset($category['theme']) and !empty($CFG->allowcategorythemes)) {
 516                 $newcategory->theme = $category['theme'];
 517             }
 518             $newcategory->id = $DB->insert_record('course_categories', $newcategory);
 519             $newcategory->context = context_coursecat::instance($newcategory->id);
 520             mark_context_dirty($newcategory->context->path);
 521
 522             //populate special fields
 523             fix_course_sortorder();
 524
 525             $createdcategories[] = array('id' => $newcategory->id, 'name' => $newcategory->name);
 526         }
 527
 528         $transaction->allow_commit();
 529
 530         return $createdcategories;
 531     }
 532
 533     /**
 534     * Returns description of method parameters
 535     *
 536     * @return external_function_parameters
 537     * @since Moodle 2.3
 538     */
 539     public static function create_categories_returns() {
 540         return new external_multiple_structure(
 541             new external_single_structure(
 542                 array(
 543                     'id' => new external_value(PARAM_INT, 'new category id'),
 544                     'name' => new external_value(PARAM_TEXT, 'new category name'),
 545                 )
 546             )
 547         );
 548     }
 549
 550     /**
 551      * Returns description of method parameters
 552      *
 553      * @return external_function_parameters
 554      * @since Moodle 2.2
 555      */
 556     public static function create_courses_parameters() {
 557         $courseconfig = get_config('moodlecourse'); //needed for many default values
 558         return new external_function_parameters(
 559             array(
 560                 'courses' => new external_multiple_structure(
 561                     new external_single_structure(
 562                         array(
 563                             'fullname' => new external_value(PARAM_TEXT, 'full name'),
 564                             'shortname' => new external_value(PARAM_TEXT, 'course short name'),
 565                             'categoryid' => new external_value(PARAM_INT, 'category id'),
 566                             'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL),
 567                             'summary' => new external_value(PARAM_RAW, 'summary', VALUE_OPTIONAL),
 568                             'summaryformat' => new external_value(PARAM_INT,
 569                                     'the summary text Moodle format', VALUE_DEFAULT, FORMAT_MOODLE),
 570                             'format' => new external_value(PARAM_PLUGIN,
 571                                     'course format: weeks, topics, social, site,..',
 572                                     VALUE_DEFAULT, $courseconfig->format),
 573                             'showgrades' => new external_value(PARAM_INT,
 574                                     '1 if grades are shown, otherwise 0', VALUE_DEFAULT,
 575                                     $courseconfig->showgrades),
 576                             'newsitems' => new external_value(PARAM_INT,
 577                                     'number of recent items appearing on the course page',
 578                                     VALUE_DEFAULT, $courseconfig->newsitems),
 579                             'startdate' => new external_value(PARAM_INT,
 580                                     'timestamp when the course start', VALUE_OPTIONAL),
 581                             'numsections' => new external_value(PARAM_INT, 'number of weeks/topics',
 582                                     VALUE_DEFAULT, $courseconfig->numsections),
 583                             'maxbytes' => new external_value(PARAM_INT,
 584                                     'largest size of file that can be uploaded into the course',
 585                                     VALUE_DEFAULT, $courseconfig->maxbytes),
 586                             'showreports' => new external_value(PARAM_INT,
 587                                     'are activity report shown (yes = 1, no =0)', VALUE_DEFAULT,
 588                                     $courseconfig->showreports),
 589                             'visible' => new external_value(PARAM_INT,
 590                                     '1: available to student, 0:not available', VALUE_OPTIONAL),
 591                             'hiddensections' => new external_value(PARAM_INT,
 592                                     'How the hidden sections in the course are displayed to students',
 593                                     VALUE_DEFAULT, $courseconfig->hiddensections),
 594                             'groupmode' => new external_value(PARAM_INT, 'no group, separate, visible',
 595                                     VALUE_DEFAULT, $courseconfig->groupmode),
 596                             'groupmodeforce' => new external_value(PARAM_INT, '1: yes, 0: no',
 597                                     VALUE_DEFAULT, $courseconfig->groupmodeforce),
 598                             'defaultgroupingid' => new external_value(PARAM_INT, 'default grouping id',
 599                                     VALUE_DEFAULT, 0),
 600                             'enablecompletion' => new external_value(PARAM_INT,
 601                                     'Enabled, control via completion and activity settings. Disabled,
 602                                         not shown in activity settings.',
 603                                     VALUE_OPTIONAL),
 604                             'completionstartonenrol' => new external_value(PARAM_INT,
 605                                     '1: begin tracking a student\'s progress in course completion after
 606                                         course enrolment. 0: does not',
 607                                     VALUE_OPTIONAL),
 608                             'completionnotify' => new external_value(PARAM_INT,
 609                                     '1: yes 0: no', VALUE_OPTIONAL),
 610                             'lang' => new external_value(PARAM_SAFEDIR,
 611                                     'forced course language', VALUE_OPTIONAL),
 612                             'forcetheme' => new external_value(PARAM_PLUGIN,
 613                                     'name of the force theme', VALUE_OPTIONAL),
 614                         )
 615                     ), 'courses to create'
 616                 )
 617             )
 618         );
 619     }
 620
 621     /**
 622      * Create  courses
 623      *
 624      * @param array $courses
 625      * @return array courses (id and shortname only)
 626      * @since Moodle 2.2
 627      */
 628     public static function create_courses($courses) {
 629         global $CFG, $DB;
 630         require_once($CFG->dirroot . "/course/lib.php");
 631         require_once($CFG->libdir . '/completionlib.php');
 632
 633
 634         $params = self::validate_parameters(self::create_courses_parameters(),
 635                         array('courses' => $courses));
 636
 637         $availablethemes = get_plugin_list('theme');
 638         $availablelangs = get_string_manager()->get_list_of_translations();
 639
 640         $transaction = $DB->start_delegated_transaction();
 641
 642         foreach ($params['courses'] as $course) {
 643
 644             // Ensure the current user is allowed to run this function
 645             $context = get_context_instance(CONTEXT_COURSECAT, $course['categoryid']);
 646             try {
 647                 self::validate_context($context);
 648             } catch (Exception $e) {
 649                 $exceptionparam = new stdClass();
 650                 $exceptionparam->message = $e->getMessage();
 651                 $exceptionparam->catid = $course['categoryid'];
 652                 throw new moodle_exception(
 653                         get_string('errorcatcontextnotvalid', 'webservice', $exceptionparam));
 654             }
 655             require_capability('moodle/course:create', $context);
 656
 657             // Make sure lang is valid
 658             if (key_exists('lang', $course) and empty($availablelangs[$course['lang']])) {
 659                 throw new moodle_exception(
 660                         get_string('errorinvalidparam', 'webservice', 'lang'));
 661             }
 662
 663             // Make sure theme is valid
 664             if (key_exists('forcetheme', $course)) {
 665                 if (!empty($CFG->allowcoursethemes)) {
 666                     if (empty($availablethemes[$course['forcetheme']])) {
 667                         throw new moodle_exception(
 668                                 get_string('errorinvalidparam', 'webservice', 'forcetheme'));
 669                     } else {
 670                         $course['theme'] = $course['forcetheme'];
 671                     }
 672                 }
 673             }
 674
 675             //force visibility if ws user doesn't have the permission to set it
 676             $category = $DB->get_record('course_categories', array('id' => $course['categoryid']));
 677             if (!has_capability('moodle/course:visibility', $context)) {
 678                 $course['visible'] = $category->visible;
 679             }
 680
 681             //set default value for completion
 682             $courseconfig = get_config('moodlecourse');
 683             if (completion_info::is_enabled_for_site()) {
 684                 if (!key_exists('enablecompletion', $course)) {
 685                     $course['enablecompletion'] = $courseconfig->enablecompletion;
 686                 }
 687                 if (!key_exists('completionstartonenrol', $course)) {
 688                     $course['completionstartonenrol'] = $courseconfig->completionstartonenrol;
 689                 }
 690             } else {
 691                 $course['enablecompletion'] = 0;
 692                 $course['completionstartonenrol'] = 0;
 693             }
 694
 695             $course['category'] = $course['categoryid'];
 696
 697             //Note: create_course() core function check shortname, idnumber, category
 698             $course['id'] = create_course((object) $course)->id;
 699
 700             $resultcourses[] = array('id' => $course['id'], 'shortname' => $course['shortname']);
 701         }
 702
 703         $transaction->allow_commit();
 704
 705         return $resultcourses;
 706     }
 707
 708     /**
 709      * Returns description of method result value
 710      *
 711      * @return external_description
 712      * @since Moodle 2.2
 713      */
 714     public static function create_courses_returns() {
 715         return new external_multiple_structure(
 716             new external_single_structure(
 717                 array(
 718                     'id'       => new external_value(PARAM_INT, 'course id'),
 719                     'shortname' => new external_value(PARAM_TEXT, 'short name'),
 720                 )
 721             )
 722         );
 723     }
 724
 725     /**
 726      * Returns description of method parameters
 727      * @return external_function_parameters
 728      */
 729     public static function delete_courses_parameters() {
 730         return new external_function_parameters(
 731             array(
 732                 'courseids' => new external_multiple_structure(new external_value(PARAM_INT, 'course ID')),
 733             )
 734         );
 735     }
 736
 737     /**
 738      * Delete courses
 739      * @param array $courseids A list of course ids
 740      */
 741     public static function delete_courses($courseids) {
 742         global $CFG, $DB;
 743         require_once($CFG->dirroot."/course/lib.php");
 744
 745         // Parameter validation.
 746         $params = self::validate_parameters(self::delete_courses_parameters(), array('courseids'=>$courseids));
 747
 748         $transaction = $DB->start_delegated_transaction();
 749
 750         foreach ($params['courseids'] as $courseid) {
 751             $course = $DB->get_record('course', array('id'=>$courseid), '*', MUST_EXIST);
 752
 753             // Check if the context is valid.
 754             $coursecontext = context_course::instance($course->id);
 755             self::validate_context($coursecontext);
 756
 757             // Check if the current user has enought permissions.
 758             if (!can_delete_course($courseid)) {
 759                 throw new moodle_exception('cannotdeletecategorycourse', 'error', '', format_string($course->fullname)." (id: $courseid)");
 760             }
 761
 762             delete_course($course, false);
 763         }
 764
 765         $transaction->allow_commit();
 766
 767         return null;
 768     }
 769
 770     /**
 771      * Returns description of method result value
 772      * @return external_description
 773      */
 774     public static function delete_courses_returns() {
 775         return null;
 776     }
 777
 778 }
 779
 780 /**
 781  * Deprecated course external functions
 782  *
 783  * @package    core_course
 784  * @copyright  2009 Petr Skodak
 785  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 786  * @since Moodle 2.0
 787  * @deprecated Moodle 2.2 MDL-29106 - Please do not use this class any more.
 788  * @todo MDL-31194 This will be deleted in Moodle 2.5.
 789  * @see core_course_external
 790  */
 791 class moodle_course_external extends external_api {
 792
 793     /**
 794      * Returns description of method parameters
 795      *
 796      * @return external_function_parameters
 797      * @since Moodle 2.0
 798      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 799      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 800      * @see core_course_external::get_courses_parameters()
 801      */
 802     public static function get_courses_parameters() {
 803         return core_course_external::get_courses_parameters();
 804     }
 805
 806     /**
 807      * Get courses
 808      *
 809      * @param array $options
 810      * @return array
 811      * @since Moodle 2.0
 812      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 813      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 814      * @see core_course_external::get_courses()
 815      */
 816     public static function get_courses($options) {
 817         return core_course_external::get_courses($options);
 818     }
 819
 820     /**
 821      * Returns description of method result value
 822      *
 823      * @return external_description
 824      * @since Moodle 2.0
 825      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 826      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 827      * @see core_course_external::get_courses_returns()
 828      */
 829     public static function get_courses_returns() {
 830         return core_course_external::get_courses_returns();
 831     }
 832
 833     /**
 834      * Returns description of method parameters
 835      *
 836      * @return external_function_parameters
 837      * @since Moodle 2.0
 838      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 839      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 840      * @see core_course_external::create_courses_parameters()
 841      */
 842     public static function create_courses_parameters() {
 843         return core_course_external::create_courses_parameters();
 844     }
 845
 846     /**
 847      * Create  courses
 848      *
 849      * @param array $courses
 850      * @return array courses (id and shortname only)
 851      * @since Moodle 2.0
 852      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 853      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 854      * @see core_course_external::create_courses()
 855      */
 856     public static function create_courses($courses) {
 857         return core_course_external::create_courses($courses);
 858     }
 859
 860     /**
 861      * Returns description of method result value
 862      *
 863      * @return external_description
 864      * @since Moodle 2.0
 865      * @deprecated Moodle 2.2 MDL-29106 - Please do not call this function any more.
 866      * @todo MDL-31194 This will be deleted in Moodle 2.5.
 867      * @see core_course_external::create_courses_returns()
 868      */
 869     public static function create_courses_returns() {
 870         return core_course_external::create_courses_returns();
 871     }
 872
 873 }