lib/classes/grades_external.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  * 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 use core_external\external_api;
  27 use core_external\external_function_parameters;
  28 use core_external\external_multiple_structure;
  29 use core_external\external_single_structure;
  30 use core_external\external_value;
  31 use core_external\external_warnings;
  32
  33 defined('MOODLE_INTERNAL') || die;
  34
  35 require_once("$CFG->libdir/gradelib.php");
  36 require_once("$CFG->dirroot/grade/edit/tree/lib.php");
  37 require_once("$CFG->dirroot/grade/querylib.php");
  38
  39 /**
  40  * core grades functions
  41  */
  42 class core_grades_external extends external_api {
  43     /**
  44      * Returns description of method parameters
  45      *
  46      * @return external_function_parameters
  47      * @since Moodle 2.7
  48      */
  49     public static function update_grades_parameters() {
  50         return new external_function_parameters(
  51             array(
  52                 'source' => new external_value(PARAM_TEXT, 'The source of the grade update'),
  53                 'courseid' => new external_value(PARAM_INT, 'id of course'),
  54                 'component' => new external_value(PARAM_COMPONENT, 'A component, for example mod_forum or mod_quiz'),
  55                 'activityid' => new external_value(PARAM_INT, 'The activity ID'),
  56                 'itemnumber' => new external_value(
  57                     PARAM_INT, 'grade item ID number for modules that have multiple grades. Typically this is 0.'),
  58                 'grades' => new external_multiple_structure(
  59                     new external_single_structure(
  60                         array(
  61                             'studentid' => new external_value(PARAM_INT, 'Student ID'),
  62                             'grade' => new external_value(PARAM_FLOAT, 'Student grade'),
  63                             'str_feedback' => new external_value(
  64                                 PARAM_TEXT, 'A string representation of the feedback from the grader', VALUE_OPTIONAL),
  65                         )
  66                 ), 'Any student grades to alter', VALUE_DEFAULT, array()),
  67                 'itemdetails' => new external_single_structure(
  68                     array(
  69                         'itemname' => new external_value(
  70                             PARAM_ALPHANUMEXT, 'The grade item name', VALUE_OPTIONAL),
  71                         'idnumber' => new external_value(
  72                             PARAM_INT, 'Arbitrary ID provided by the module responsible for the grade item', VALUE_OPTIONAL),
  73                         'gradetype' => new external_value(
  74                             PARAM_INT, 'The type of grade (0 = none, 1 = value, 2 = scale, 3 = text)', VALUE_OPTIONAL),
  75                         'grademax' => new external_value(
  76                             PARAM_FLOAT, 'Maximum grade allowed', VALUE_OPTIONAL),
  77                         'grademin' => new external_value(
  78                             PARAM_FLOAT, 'Minimum grade allowed', VALUE_OPTIONAL),
  79                         'scaleid' => new external_value(
  80                             PARAM_INT, 'The ID of the custom scale being is used', VALUE_OPTIONAL),
  81                         'multfactor' => new external_value(
  82                             PARAM_FLOAT, 'Multiply all grades by this number', VALUE_OPTIONAL),
  83                         'plusfactor' => new external_value(
  84                             PARAM_FLOAT, 'Add this to all grades', VALUE_OPTIONAL),
  85                         'deleted' => new external_value(
  86                             PARAM_BOOL, 'True if the grade item should be deleted', VALUE_OPTIONAL),
  87                         'hidden' => new external_value(
  88                             PARAM_BOOL, 'True if the grade item is hidden', VALUE_OPTIONAL),
  89                     ), 'Any grade item settings to alter', VALUE_DEFAULT, array()
  90                 )
  91             )
  92         );
  93     }
  94
  95     /**
  96      * Update a grade item and, optionally, student grades
  97      *
  98      * @param  string $source       The source of the grade update
  99      * @param  int $courseid        The course id
 100      * @param  string $component    Component name
 101      * @param  int $activityid      The activity id
 102      * @param  int $itemnumber      The item number
 103      * @param  array  $grades      Array of grades
 104      * @param  array  $itemdetails Array of item details
 105      * @return int                  A status flag
 106      * @since Moodle 2.7
 107      */
 108     public static function update_grades($source, $courseid, $component, $activityid,
 109         $itemnumber, $grades = array(), $itemdetails = array()) {
 110         global $CFG;
 111
 112         $params = self::validate_parameters(
 113             self::update_grades_parameters(),
 114             array(
 115                 'source' => $source,
 116                 'courseid' => $courseid,
 117                 'component' => $component,
 118                 'activityid' => $activityid,
 119                 'itemnumber' => $itemnumber,
 120                 'grades' => $grades,
 121                 'itemdetails' => $itemdetails
 122             )
 123         );
 124
 125         list($itemtype, $itemmodule) = normalize_component($params['component']);
 126
 127         if (! $cm = get_coursemodule_from_id($itemmodule, $activityid)) {
 128             throw new moodle_exception('invalidcoursemodule');
 129         }
 130         $iteminstance = $cm->instance;
 131
 132         $coursecontext = context_course::instance($params['courseid']);
 133
 134         try {
 135             self::validate_context($coursecontext);
 136         } catch (Exception $e) {
 137             $exceptionparam = new stdClass();
 138             $exceptionparam->message = $e->getMessage();
 139             $exceptionparam->courseid = $params['courseid'];
 140             throw new moodle_exception('errorcoursecontextnotvalid' , 'webservice', '', $exceptionparam);
 141         }
 142
 143         $hidinggrades = false;
 144         $editinggradeitem = false;
 145         $editinggrades = false;
 146
 147         $gradestructure = array();
 148         foreach ($grades as $grade) {
 149             $editinggrades = true;
 150             $gradestructure[ $grade['studentid'] ] = array('userid' => $grade['studentid'], 'rawgrade' => $grade['grade']);
 151         }
 152         if (!empty($params['itemdetails'])) {
 153             if (isset($params['itemdetails']['hidden'])) {
 154                 $hidinggrades = true;
 155             } else {
 156                 $editinggradeitem = true;
 157             }
 158         }
 159
 160         if ($editinggradeitem && !has_capability('moodle/grade:manage', $coursecontext)) {
 161             throw new moodle_exception('nopermissiontoviewgrades', 'error', '', null,
 162                 'moodle/grade:manage required to edit grade information');
 163         }
 164         if ($hidinggrades && !has_capability('moodle/grade:hide', $coursecontext) &&
 165             !has_capability('moodle/grade:hide', $coursecontext)) {
 166             throw new moodle_exception('nopermissiontoviewgrades', 'error', '', null,
 167                 'moodle/grade:hide required to hide grade items');
 168         }
 169         if ($editinggrades && !has_capability('moodle/grade:edit', $coursecontext)) {
 170             throw new moodle_exception('nopermissiontoviewgrades', 'error', '', null,
 171                 'moodle/grade:edit required to edit grades');
 172         }
 173
 174         return grade_update($params['source'], $params['courseid'], $itemtype,
 175             $itemmodule, $iteminstance, $itemnumber, $gradestructure, $params['itemdetails'], true);
 176     }
 177
 178     /**
 179      * Returns description of method result value
 180      *
 181      * @return \core_external\external_description
 182      * @since Moodle 2.7
 183      */
 184     public static function update_grades_returns() {
 185         return new external_value(
 186             PARAM_INT,
 187             'A value like ' . GRADE_UPDATE_OK . ' => OK, ' . GRADE_UPDATE_FAILED . ' => FAILED
 188             as defined in lib/grade/constants.php'
 189         );
 190     }
 191 }