[Summary view]

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 401 and 402] [Versions 401 and 403]

   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   * Core grades external functions
  19   *
  20   * @package    core_grades
  21   * @copyright  2012 Andrew Davis
  22   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   * @since Moodle 2.7
  24   */
  25  
  26  defined('MOODLE_INTERNAL') || die;
  27  
  28  require_once("$CFG->libdir/externallib.php");
  29  require_once("$CFG->libdir/gradelib.php");
  30  require_once("$CFG->dirroot/grade/edit/tree/lib.php");
  31  require_once("$CFG->dirroot/grade/querylib.php");
  32  
  33  /**
  34   * core grades functions
  35   */
  36  class core_grades_external extends external_api {
  37      /**
  38       * Returns description of method parameters
  39       *
  40       * @return external_function_parameters
  41       * @since Moodle 2.7
  42       */
  43      public static function update_grades_parameters() {
  44          return new external_function_parameters(
  45              array(
  46                  'source' => new external_value(PARAM_TEXT, 'The source of the grade update'),
  47                  'courseid' => new external_value(PARAM_INT, 'id of course'),
  48                  'component' => new external_value(PARAM_COMPONENT, 'A component, for example mod_forum or mod_quiz'),
  49                  'activityid' => new external_value(PARAM_INT, 'The activity ID'),
  50                  'itemnumber' => new external_value(
  51                      PARAM_INT, 'grade item ID number for modules that have multiple grades. Typically this is 0.'),
  52                  'grades' => new external_multiple_structure(
  53                      new external_single_structure(
  54                          array(
  55                              'studentid' => new external_value(PARAM_INT, 'Student ID'),
  56                              'grade' => new external_value(PARAM_FLOAT, 'Student grade'),
  57                              'str_feedback' => new external_value(
  58                                  PARAM_TEXT, 'A string representation of the feedback from the grader', VALUE_OPTIONAL),
  59                          )
  60                  ), 'Any student grades to alter', VALUE_DEFAULT, array()),
  61                  'itemdetails' => new external_single_structure(
  62                      array(
  63                          'itemname' => new external_value(
  64                              PARAM_ALPHANUMEXT, 'The grade item name', VALUE_OPTIONAL),
  65                          'idnumber' => new external_value(
  66                              PARAM_INT, 'Arbitrary ID provided by the module responsible for the grade item', VALUE_OPTIONAL),
  67                          'gradetype' => new external_value(
  68                              PARAM_INT, 'The type of grade (0 = none, 1 = value, 2 = scale, 3 = text)', VALUE_OPTIONAL),
  69                          'grademax' => new external_value(
  70                              PARAM_FLOAT, 'Maximum grade allowed', VALUE_OPTIONAL),
  71                          'grademin' => new external_value(
  72                              PARAM_FLOAT, 'Minimum grade allowed', VALUE_OPTIONAL),
  73                          'scaleid' => new external_value(
  74                              PARAM_INT, 'The ID of the custom scale being is used', VALUE_OPTIONAL),
  75                          'multfactor' => new external_value(
  76                              PARAM_FLOAT, 'Multiply all grades by this number', VALUE_OPTIONAL),
  77                          'plusfactor' => new external_value(
  78                              PARAM_FLOAT, 'Add this to all grades', VALUE_OPTIONAL),
  79                          'deleted' => new external_value(
  80                              PARAM_BOOL, 'True if the grade item should be deleted', VALUE_OPTIONAL),
  81                          'hidden' => new external_value(
  82                              PARAM_BOOL, 'True if the grade item is hidden', VALUE_OPTIONAL),
  83                      ), 'Any grade item settings to alter', VALUE_DEFAULT, array()
  84                  )
  85              )
  86          );
  87      }
  88  
  89      /**
  90       * Update a grade item and, optionally, student grades
  91       *
  92       * @param  string $source       The source of the grade update
  93       * @param  int $courseid        The course id
  94       * @param  string $component    Component name
  95       * @param  int $activityid      The activity id
  96       * @param  int $itemnumber      The item number
  97       * @param  array  $grades      Array of grades
  98       * @param  array  $itemdetails Array of item details
  99       * @return int                  A status flag
 100       * @since Moodle 2.7
 101       */
 102      public static function update_grades($source, $courseid, $component, $activityid,
 103          $itemnumber, $grades = array(), $itemdetails = array()) {
 104          global $CFG;
 105  
 106          $params = self::validate_parameters(
 107              self::update_grades_parameters(),
 108              array(
 109                  'source' => $source,
 110                  'courseid' => $courseid,
 111                  'component' => $component,
 112                  'activityid' => $activityid,
 113                  'itemnumber' => $itemnumber,
 114                  'grades' => $grades,
 115                  'itemdetails' => $itemdetails
 116              )
 117          );
 118  
 119          list($itemtype, $itemmodule) = normalize_component($params['component']);
 120  
 121          if (! $cm = get_coursemodule_from_id($itemmodule, $activityid)) {
 122              throw new moodle_exception('invalidcoursemodule');
 123          }
 124          $iteminstance = $cm->instance;
 125  
 126          $coursecontext = context_course::instance($params['courseid']);
 127  
 128          try {
 129              self::validate_context($coursecontext);
 130          } catch (Exception $e) {
 131              $exceptionparam = new stdClass();
 132              $exceptionparam->message = $e->getMessage();
 133              $exceptionparam->courseid = $params['courseid'];
 134              throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
 135          }
 136  
 137          $hidinggrades = false;
 138          $editinggradeitem = false;
 139          $editinggrades = false;
 140  
 141          $gradestructure = array();
 142          foreach ($grades as $grade) {
 143              $editinggrades = true;
 144              $gradestructure[ $grade['studentid'] ] = array('userid' => $grade['studentid'], 'rawgrade' => $grade['grade']);
 145          }
 146          if (!empty($params['itemdetails'])) {
 147              if (isset($params['itemdetails']['hidden'])) {
 148                  $hidinggrades = true;
 149              } else {
 150                  $editinggradeitem = true;
 151              }
 152          }
 153  
 154          if ($editinggradeitem && !has_capability('moodle/grade:manage', $coursecontext)) {
 155              throw new moodle_exception('nopermissiontoviewgrades', 'error', '', null,
 156                  'moodle/grade:manage required to edit grade information');
 157          }
 158          if ($hidinggrades && !has_capability('moodle/grade:hide', $coursecontext) &&
 159              !has_capability('moodle/grade:hide', $coursecontext)) {
 160              throw new moodle_exception('nopermissiontoviewgrades', 'error', '', null,
 161                  'moodle/grade:hide required to hide grade items');
 162          }
 163          if ($editinggrades && !has_capability('moodle/grade:edit', $coursecontext)) {
 164              throw new moodle_exception('nopermissiontoviewgrades', 'error', '', null,
 165                  'moodle/grade:edit required to edit grades');
 166          }
 167  
 168          return grade_update($params['source'], $params['courseid'], $itemtype,
 169              $itemmodule, $iteminstance, $itemnumber, $gradestructure, $params['itemdetails'], true);
 170      }
 171  
 172      /**
 173       * Returns description of method result value
 174       *
 175       * @return external_description
 176       * @since Moodle 2.7
 177       */
 178      public static function update_grades_returns() {
 179          return new external_value(
 180              PARAM_INT,
 181              'A value like ' . GRADE_UPDATE_OK . ' => OK, ' . GRADE_UPDATE_FAILED . ' => FAILED
 182              as defined in lib/grade/constants.php'
 183          );
 184      }
 185  
 186      /**
 187       * Returns description of method parameters
 188       *
 189       * @deprecated since Moodle 3.11 MDL-71031 - please do not use this function any more.
 190       * @todo MDL-71325 This will be deleted in Moodle 4.3.
 191       * @see core_grades\external\create_gradecategories::create_gradecategories()
 192       *
 193       * @return external_function_parameters
 194       * @since Moodle 3.10
 195       */
 196      public static function create_gradecategory_parameters() {
 197          return new external_function_parameters(
 198              [
 199                  'courseid' => new external_value(PARAM_INT, 'id of course', VALUE_REQUIRED),
 200                  'fullname' => new external_value(PARAM_TEXT, 'fullname of category', VALUE_REQUIRED),
 201                  'options' => new external_single_structure([
 202                      'aggregation' => new external_value(PARAM_INT, 'aggregation method', VALUE_OPTIONAL),
 203                      'aggregateonlygraded' => new external_value(PARAM_BOOL, 'exclude empty grades', VALUE_OPTIONAL),
 204                      'aggregateoutcomes' => new external_value(PARAM_BOOL, 'aggregate outcomes', VALUE_OPTIONAL),
 205                      'droplow' => new external_value(PARAM_INT, 'drop low grades', VALUE_OPTIONAL),
 206                      'itemname' => new external_value(PARAM_TEXT, 'the category total name', VALUE_OPTIONAL),
 207                      'iteminfo' => new external_value(PARAM_TEXT, 'the category iteminfo', VALUE_OPTIONAL),
 208                      'idnumber' => new external_value(PARAM_TEXT, 'the category idnumber', VALUE_OPTIONAL),
 209                      'gradetype' => new external_value(PARAM_INT, 'the grade type', VALUE_OPTIONAL),
 210                      'grademax' => new external_value(PARAM_INT, 'the grade max', VALUE_OPTIONAL),
 211                      'grademin' => new external_value(PARAM_INT, 'the grade min', VALUE_OPTIONAL),
 212                      'gradepass' => new external_value(PARAM_INT, 'the grade to pass', VALUE_OPTIONAL),
 213                      'display' => new external_value(PARAM_INT, 'the display type', VALUE_OPTIONAL),
 214                      'decimals' => new external_value(PARAM_INT, 'the decimal count', VALUE_OPTIONAL),
 215                      'hiddenuntil' => new external_value(PARAM_INT, 'grades hidden until', VALUE_OPTIONAL),
 216                      'locktime' => new external_value(PARAM_INT, 'lock grades after', VALUE_OPTIONAL),
 217                      'weightoverride' => new external_value(PARAM_BOOL, 'weight adjusted', VALUE_OPTIONAL),
 218                      'aggregationcoef2' => new external_value(PARAM_RAW, 'weight coefficient', VALUE_OPTIONAL),
 219                      'parentcategoryid' => new external_value(PARAM_INT, 'The parent category id', VALUE_OPTIONAL),
 220                      'parentcategoryidnumber' => new external_value(PARAM_TEXT, 'the parent category idnumber', VALUE_OPTIONAL),
 221                  ], 'optional category data', VALUE_DEFAULT, [])
 222              ]
 223          );
 224      }
 225  
 226      /**
 227       * Creates a gradecategory inside of the specified course.
 228       *
 229       * @deprecated since Moodle 3.11 MDL-71031 - please do not use this function any more.
 230       * @todo MDL-71325 This will be deleted in Moodle 4.3.
 231       * @see core_grades\external\create_gradecategories::create_gradecategories()
 232       *
 233       * @param int $courseid the courseid to create the gradecategory in.
 234       * @param string $fullname the fullname of the grade category to create.
 235       * @param array $options array of options to set.
 236       *
 237       * @return array array of created categoryid and warnings.
 238       */
 239      public static function create_gradecategory(int $courseid, string $fullname, array $options) {
 240          global $CFG, $DB;
 241  
 242          $params = self::validate_parameters(self::create_gradecategory_parameters(),
 243              ['courseid' => $courseid, 'fullname' => $fullname, 'options' => $options]);
 244  
 245          // Now params are validated, update the references.
 246          $courseid = $params['courseid'];
 247          $fullname = $params['fullname'];
 248          $options = $params['options'];
 249  
 250          // Check that the context and permissions are OK.
 251          $context = context_course::instance($courseid);
 252          self::validate_context($context);
 253          require_capability('moodle/grade:manage', $context);
 254  
 255          $categories = [];
 256          $categories[] = ['fullname' => $fullname, 'options' => $options];
 257          // Call through to webservice class for multiple creations,
 258          // Where the majority of the this functionality moved with the deprecation of this function.
 259          $result = \core_grades\external\create_gradecategories::create_gradecategories_from_data($courseid, $categories);
 260  
 261          return['categoryid' => $result['categoryids'][0], 'warnings' => []];
 262      }
 263  
 264      /**
 265       * Returns description of method result value
 266       *
 267       * @deprecated since Moodle 3.11 MDL-71031 - please do not use this function any more.
 268       * @todo MDL-71325 This will be deleted in Moodle 4.3.
 269       * @see core_grades\external\create_gradecategories::create_gradecategories()
 270       *
 271       * @return external_description
 272       * @since Moodle 3.10
 273       */
 274      public static function create_gradecategory_returns() {
 275          return new external_single_structure([
 276              'categoryid' => new external_value(PARAM_INT, 'The ID of the created category', VALUE_OPTIONAL),
 277              'warnings' => new external_warnings(),
 278          ]);
 279      }
 280  
 281      /**
 282       * Marking the method as deprecated. See MDL-71031 for details.
 283       * @since Moodle 3.11
 284       * @return bool
 285       */
 286      public static function create_gradecategory_is_deprecated() {
 287          return true;
 288      }
 289  }