course/externallib.php

   1 <?php
   2
   3 // This file is part of Moodle - http://moodle.org/
   4 //
   5 // Moodle is free software: you can redistribute it and/or modify
   6 // it under the terms of the GNU General Public License as published by
   7 // the Free Software Foundation, either version 3 of the License, or
   8 // (at your option) any later version.
   9 //
  10 // Moodle is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 // GNU General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  17
  18 /**
  19  * External course API
  20  *
  21  * @package    core
  22  * @subpackage course
  23  * @copyright  2010 Moodle Pty Ltd (http://moodle.com)
  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 class moodle_course_external extends external_api {
  32
  33     /**
  34      * Returns description of method parameters
  35      * @return external_function_parameters
  36      */
  37     public static function get_courses_parameters() {
  38         return new external_function_parameters(
  39                 array('options' => new external_single_structure(
  40                             array('ids' => new external_multiple_structure(
  41                                         new external_value(PARAM_INT, 'Course id')
  42                                         , 'List of course id. If empty return all courses
  43                                             except front page course.',
  44                                         VALUE_OPTIONAL)
  45                             ), 'options - operator OR is used', VALUE_DEFAULT, array())
  46                 )
  47         );
  48     }
  49
  50     /**
  51      * Get courses
  52      * @param array $options
  53      * @return array
  54      */
  55     public static function get_courses($options) {
  56         global $CFG, $DB;
  57         require_once($CFG->dirroot . "/course/lib.php");
  58
  59         //validate parameter
  60         $params = self::validate_parameters(self::get_courses_parameters(),
  61                         array('options' => $options));
  62
  63         //retrieve courses
  64         if (!key_exists('ids', $params['options'])
  65                 or empty($params['options']['ids'])) {
  66             $courses = $DB->get_records('course');
  67         } else {
  68             $courses = $DB->get_records_list('course', 'id', $params['options']['ids']);
  69         }
  70
  71         //create return value
  72         $coursesinfo = array();
  73         foreach ($courses as $course) {
  74
  75             // now security checks
  76             $context = get_context_instance(CONTEXT_COURSE, $course->id);
  77             try {
  78                 self::validate_context($context);
  79             } catch (Exception $e) {
  80                 $exceptionparam = new stdClass();
  81                 $exceptionparam->message = $e->getMessage();
  82                 $exceptionparam->courseid = $course->id;
  83                 throw new moodle_exception(
  84                         get_string('errorcoursecontextnotvalid', 'webservice', $exceptionparam));
  85             }
  86             require_capability('moodle/course:view', $context);
  87
  88             $courseinfo = array();
  89             $courseinfo['id'] = $course->id;
  90             $courseinfo['fullname'] = $course->fullname;
  91             $courseinfo['shortname'] = $course->shortname;
  92             $courseinfo['categoryid'] = $course->category;
  93             $courseinfo['summary'] = $course->summary;
  94             $courseinfo['summaryformat'] = $course->summaryformat;
  95             $courseinfo['format'] = $course->format;
  96             $courseinfo['startdate'] = $course->startdate;
  97             $courseinfo['numsections'] = $course->numsections;
  98
  99             //some field should be returned only if the user has update permission
 100             $courseadmin = has_capability('moodle/course:update', $context);
 101             if ($courseadmin) {
 102                 $courseinfo['categorysortorder'] = $course->sortorder;
 103                 $courseinfo['idnumber'] = $course->idnumber;
 104                 $courseinfo['showgrades'] = $course->showgrades;
 105                 $courseinfo['showreports'] = $course->showreports;
 106                 $courseinfo['newsitems'] = $course->newsitems;
 107                 $courseinfo['visible'] = $course->visible;
 108                 $courseinfo['maxbytes'] = $course->maxbytes;
 109                 $courseinfo['hiddensections'] = $course->hiddensections;
 110                 $courseinfo['groupmode'] = $course->groupmode;
 111                 $courseinfo['groupmodeforce'] = $course->groupmodeforce;
 112                 $courseinfo['defaultgroupingid'] = $course->defaultgroupingid;
 113                 $courseinfo['lang'] = $course->lang;
 114                 $courseinfo['timecreated'] = $course->timecreated;
 115                 $courseinfo['timemodified'] = $course->timemodified;
 116                 $courseinfo['forcetheme'] = $course->theme;
 117                 $courseinfo['enablecompletion'] = $course->enablecompletion;
 118                 $courseinfo['completionstartonenrol'] = $course->completionstartonenrol;
 119                 $courseinfo['completionnotify'] = $course->completionnotify;
 120             }
 121
 122             if ($courseadmin or $course->visible
 123                     or has_capability('moodle/course:viewhiddencourses', $context)) {
 124                 $coursesinfo[] = $courseinfo;
 125             }
 126         }
 127
 128         return $coursesinfo;
 129     }
 130
 131     /**
 132      * Returns description of method result value
 133      * @return external_description
 134      */
 135     public static function get_courses_returns() {
 136         return new external_multiple_structure(
 137                 new external_single_structure(
 138                         array(
 139                             'id' => new external_value(PARAM_INT, 'course id'),
 140                             'shortname' => new external_value(PARAM_TEXT, 'course short name'),
 141                             'categoryid' => new external_value(PARAM_INT, 'category id'),
 142                             'categorysortorder' => new external_value(PARAM_INT,
 143                                     'sort order into the category', VALUE_OPTIONAL),
 144                             'fullname' => new external_value(PARAM_TEXT, 'full name'),
 145                             'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL),
 146                             'summary' => new external_value(PARAM_RAW, 'summary'),
 147                             'summaryformat' => new external_value(PARAM_INT,
 148                                     'the summary text Moodle format'),
 149                             'format' => new external_value(PARAM_ALPHANUMEXT,
 150                                     'course format: weeks, topics, social, site,..'),
 151                             'showgrades' => new external_value(PARAM_INT,
 152                                     '1 if grades are shown, otherwise 0', VALUE_OPTIONAL),
 153                             'newsitems' => new external_value(PARAM_INT,
 154                                     'number of recent items appearing on the course page', VALUE_OPTIONAL),
 155                             'startdate' => new external_value(PARAM_INT,
 156                                     'timestamp when the course start'),
 157                             'numsections' => new external_value(PARAM_INT, 'number of weeks/topics'),
 158                             'maxbytes' => new external_value(PARAM_INT,
 159                                     'largest size of file that can be uploaded into the course',
 160                                     VALUE_OPTIONAL),
 161                             'showreports' => new external_value(PARAM_INT,
 162                                     'are activity report shown (yes = 1, no =0)', VALUE_OPTIONAL),
 163                             'visible' => new external_value(PARAM_INT,
 164                                     '1: available to student, 0:not available', VALUE_OPTIONAL),
 165                             'hiddensections' => new external_value(PARAM_INT,
 166                                     'How the hidden sections in the course are displayed to students',
 167                                     VALUE_OPTIONAL),
 168                             'groupmode' => new external_value(PARAM_INT, 'no group, separate, visible',
 169                                     VALUE_OPTIONAL),
 170                             'groupmodeforce' => new external_value(PARAM_INT, '1: yes, 0: no',
 171                                     VALUE_OPTIONAL),
 172                             'defaultgroupingid' => new external_value(PARAM_INT, 'default grouping id',
 173                                     VALUE_OPTIONAL),
 174                             'timecreated' => new external_value(PARAM_INT,
 175                                     'timestamp when the course have been created', VALUE_OPTIONAL),
 176                             'timemodified' => new external_value(PARAM_INT,
 177                                     'timestamp when the course have been modified', VALUE_OPTIONAL),
 178                             'enablecompletion' => new external_value(PARAM_INT,
 179                                     'Enabled, control via completion and activity settings. Disbaled,
 180                                         not shown in activity settings.',
 181                                     VALUE_OPTIONAL),
 182                             'completionstartonenrol' => new external_value(PARAM_INT,
 183                                     '1: begin tracking a student\'s progress in course completion
 184                                         after course enrolment. 0: does not',
 185                                     VALUE_OPTIONAL),
 186                             'completionnotify' => new external_value(PARAM_INT,
 187                                     '1: yes 0: no', VALUE_OPTIONAL),
 188                             'lang' => new external_value(PARAM_ALPHANUMEXT,
 189                                     'forced course language', VALUE_OPTIONAL),
 190                             'forcetheme' => new external_value(PARAM_ALPHANUMEXT,
 191                                     'name of the force theme', VALUE_OPTIONAL),
 192                         ), 'course'
 193                 )
 194         );
 195     }
 196
 197     /**
 198      * Returns description of method parameters
 199      * @return external_function_parameters
 200      */
 201     public static function create_courses_parameters() {
 202         $courseconfig = get_config('moodlecourse'); //needed for many default values
 203         return new external_function_parameters(
 204             array(
 205                 'courses' => new external_multiple_structure(
 206                     new external_single_structure(
 207                         array(
 208                             'fullname' => new external_value(PARAM_TEXT, 'full name'),
 209                             'shortname' => new external_value(PARAM_TEXT, 'course short name'),
 210                             'categoryid' => new external_value(PARAM_INT, 'category id'),
 211                             'idnumber' => new external_value(PARAM_RAW, 'id number', VALUE_OPTIONAL),
 212                             'summary' => new external_value(PARAM_RAW, 'summary', VALUE_OPTIONAL),
 213                             'summaryformat' => new external_value(PARAM_INT,
 214                                     'the summary text Moodle format', VALUE_DEFAULT, FORMAT_MOODLE),
 215                             'format' => new external_value(PARAM_ALPHANUMEXT,
 216                                     'course format: weeks, topics, social, site,..',
 217                                     VALUE_DEFAULT, $courseconfig->format),
 218                             'showgrades' => new external_value(PARAM_INT,
 219                                     '1 if grades are shown, otherwise 0', VALUE_DEFAULT,
 220                                     $courseconfig->showgrades),
 221                             'newsitems' => new external_value(PARAM_INT,
 222                                     'number of recent items appearing on the course page',
 223                                     VALUE_DEFAULT, $courseconfig->newsitems),
 224                             'startdate' => new external_value(PARAM_INT,
 225                                     'timestamp when the course start', VALUE_OPTIONAL),
 226                             'numsections' => new external_value(PARAM_INT, 'number of weeks/topics',
 227                                     VALUE_DEFAULT, $courseconfig->numsections),
 228                             'maxbytes' => new external_value(PARAM_INT,
 229                                     'largest size of file that can be uploaded into the course',
 230                                     VALUE_DEFAULT, $courseconfig->maxbytes),
 231                             'showreports' => new external_value(PARAM_INT,
 232                                     'are activity report shown (yes = 1, no =0)', VALUE_DEFAULT,
 233                                     $courseconfig->showreports),
 234                             'visible' => new external_value(PARAM_INT,
 235                                     '1: available to student, 0:not available', VALUE_OPTIONAL),
 236                             'hiddensections' => new external_value(PARAM_INT,
 237                                     'How the hidden sections in the course are displayed to students',
 238                                     VALUE_DEFAULT, $courseconfig->hiddensections),
 239                             'groupmode' => new external_value(PARAM_INT, 'no group, separate, visible',
 240                                     VALUE_DEFAULT, $courseconfig->groupmode),
 241                             'groupmodeforce' => new external_value(PARAM_INT, '1: yes, 0: no',
 242                                     VALUE_DEFAULT, $courseconfig->groupmodeforce),
 243                             'defaultgroupingid' => new external_value(PARAM_INT, 'default grouping id',
 244                                     VALUE_DEFAULT, 0),
 245                             'enablecompletion' => new external_value(PARAM_INT,
 246                                     'Enabled, control via completion and activity settings. Disbaled,
 247                                         not shown in activity settings.',
 248                                     VALUE_OPTIONAL),
 249                             'completionstartonenrol' => new external_value(PARAM_INT,
 250                                     '1: begin tracking a student\'s progress in course completion after
 251                                         course enrolment. 0: does not',
 252                                     VALUE_OPTIONAL),
 253                             'completionnotify' => new external_value(PARAM_INT,
 254                                     '1: yes 0: no', VALUE_OPTIONAL),
 255                             'lang' => new external_value(PARAM_ALPHANUMEXT,
 256                                     'forced course language', VALUE_OPTIONAL),
 257                             'forcetheme' => new external_value(PARAM_ALPHANUMEXT,
 258                                     'name of the force theme', VALUE_OPTIONAL),
 259                         )
 260                     ), 'courses to create'
 261                 )
 262             )
 263         );
 264     }
 265
 266     /**
 267      * Create  courses
 268      * @param array $courses
 269      * @return array courses (id and shortname only)
 270      */
 271     public static function create_courses($courses) {
 272         global $CFG, $DB;
 273         require_once($CFG->dirroot . "/course/lib.php");
 274         require_once($CFG->libdir . '/completionlib.php');
 275
 276
 277         $params = self::validate_parameters(self::create_courses_parameters(),
 278                         array('courses' => $courses));
 279
 280         $availablethemes = get_plugin_list('theme');
 281         $availablelangs = get_string_manager()->get_list_of_translations();
 282
 283         $transaction = $DB->start_delegated_transaction();
 284
 285         foreach ($params['courses'] as $course) {
 286
 287             // Ensure the current user is allowed to run this function
 288             $context = get_context_instance(CONTEXT_COURSECAT, $course['categoryid']);
 289             try {
 290                 self::validate_context($context);
 291             } catch (Exception $e) {
 292                 $exceptionparam = new stdClass();
 293                 $exceptionparam->message = $e->getMessage();
 294                 $exceptionparam->catid = $course['categoryid'];
 295                 throw new moodle_exception(
 296                         get_string('errorcatcontextnotvalid', 'webservice', $exceptionparam));
 297             }
 298             require_capability('moodle/course:create', $context);
 299
 300             // Make sure lang is valid
 301             if (key_exists('lang', $course) and empty($availablelangs[$course['lang']])) {
 302                 throw new moodle_exception(
 303                         get_string('errorinvalidparam', 'webservice', 'lang'));
 304             }
 305
 306             // Make sure theme is valid
 307             if (key_exists('forcetheme', $course)) {
 308                 if (!empty($CFG->allowcoursethemes)) {
 309                     if (empty($availablethemes[$course['forcetheme']])) {
 310                         throw new moodle_exception(
 311                                 get_string('errorinvalidparam', 'webservice', 'forcetheme'));
 312                     } else {
 313                         $course['theme'] = $course['forcetheme'];
 314                     }
 315                 }
 316             }
 317
 318             //force visibility if ws user doesn't have the permission to set it
 319             $category = $DB->get_record('course_categories', array('id' => $course['categoryid']));
 320             if (!has_capability('moodle/course:visibility', $context)) {
 321                 $course['visible'] = $category->visible;
 322             }
 323
 324             //set default value for completion
 325             if (completion_info::is_enabled_for_site()) {
 326                 if (!key_exists('enablecompletion', $course)) {
 327                     $course['enablecompletion'] = $courseconfig->enablecompletion;
 328                 }
 329                 if (!key_exists('completionstartonenrol', $course)) {
 330                     $course['completionstartonenrol'] = $courseconfig->completionstartonenrol;
 331                 }
 332             } else {
 333                 $course['enablecompletion'] = 0;
 334                 $course['completionstartonenrol'] = 0;
 335             }
 336
 337             $course['category'] = $course['categoryid'];
 338
 339             //Note: create_course() core function check shortname, idnumber, category
 340             $course['id'] = create_course((object) $course)->id;
 341
 342             $resultcourses[] = array('id' => $course['id'], 'shortname' => $course['shortname']);
 343         }
 344
 345         $transaction->allow_commit();
 346
 347         return $resultcourses;
 348     }
 349
 350     /**
 351      * Returns description of method result value
 352      * @return external_description
 353      */
 354     public static function create_courses_returns() {
 355         return new external_multiple_structure(
 356             new external_single_structure(
 357                 array(
 358                     'id'       => new external_value(PARAM_INT, 'course id'),
 359                     'shortname' => new external_value(PARAM_TEXT, 'short name'),
 360                 )
 361             )
 362         );
 363     }
 364
 365 }