[Summary view]

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

   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   * External grade report overview API
  19   *
  20   * @package    gradereport_overview
  21   * @copyright  2016 Juan Leyva <juan@moodle.com>
  22   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   */
  24  
  25  use core_external\external_api;
  26  use core_external\external_function_parameters;
  27  use core_external\external_multiple_structure;
  28  use core_external\external_single_structure;
  29  use core_external\external_value;
  30  use core_external\external_warnings;
  31  
  32  defined('MOODLE_INTERNAL') || die;
  33  
  34  require_once($CFG->libdir . '/gradelib.php');
  35  require_once($CFG->dirroot . '/grade/lib.php');
  36  require_once($CFG->dirroot . '/grade/report/overview/lib.php');
  37  
  38  /**
  39   * External grade overview report API implementation
  40   *
  41   * @package    gradereport_overview
  42   * @copyright  2016 Juan Leyva <juan@moodle.com>
  43   * @category   external
  44   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  45   */
  46  class gradereport_overview_external extends external_api {
  47  
  48      /**
  49       * Describes the parameters for get_course_grades.
  50       *
  51       * @return external_function_parameters
  52       * @since Moodle 3.2
  53       */
  54      public static function get_course_grades_parameters() {
  55          return new external_function_parameters (
  56              array(
  57                  'userid' => new external_value(PARAM_INT, 'Get grades for this user (optional, default current)', VALUE_DEFAULT, 0)
  58              )
  59          );
  60      }
  61  
  62      /**
  63       * Get the given user courses final grades
  64       *
  65       * @param int $userid get grades for this user (optional, default current)
  66       *
  67       * @return array the grades tables
  68       * @since Moodle 3.2
  69       */
  70      public static function get_course_grades($userid = 0) {
  71          global $USER;
  72  
  73          $warnings = array();
  74  
  75          // Validate the parameter.
  76          $params = self::validate_parameters(self::get_course_grades_parameters(),
  77              array(
  78                  'userid' => $userid
  79              )
  80          );
  81  
  82          $userid = $params['userid'];
  83          if (empty($userid)) {
  84              $userid = $USER->id;
  85          }
  86  
  87          $systemcontext = context_system::instance();
  88          self::validate_context($systemcontext);
  89  
  90          if ($USER->id != $userid) {
  91              // We must check if the current user can view other users grades.
  92              $user = core_user::get_user($userid, '*', MUST_EXIST);
  93              core_user::require_active_user($user);
  94              require_capability('moodle/grade:viewall', $systemcontext);
  95          }
  96  
  97          // We need the site course, and course context.
  98          $course = get_course(SITEID);
  99          $context = context_course::instance($course->id);
 100  
 101          // Get the course final grades now.
 102          $gpr = new grade_plugin_return(array('type' => 'report', 'plugin' => 'overview', 'courseid' => $course->id,
 103                                          'userid' => $userid));
 104          $report = new grade_report_overview($userid, $gpr, $context);
 105          // Force a regrade if required. As this is the overview report, we need to do all courses
 106          // the user is enrolled in, not just $course.
 107          $report->regrade_all_courses_if_needed();
 108          $coursesgrades = $report->setup_courses_data(true);
 109  
 110          $grades = array();
 111          foreach ($coursesgrades as $coursegrade) {
 112              $gradeinfo = array(
 113                  'courseid' => $coursegrade['course']->id,
 114                  'grade' => grade_format_gradevalue($coursegrade['finalgrade'], $coursegrade['courseitem'], true),
 115                  'rawgrade' => $coursegrade['finalgrade'],
 116              );
 117              if (isset($coursegrade['rank'])) {
 118                  $gradeinfo['rank'] = $coursegrade['rank'];
 119              }
 120              $grades[] = $gradeinfo;
 121          }
 122  
 123          $result = array();
 124          $result['grades'] = $grades;
 125          $result['warnings'] = $warnings;
 126          return $result;
 127      }
 128  
 129      /**
 130       * Describes the get_course_grades return value.
 131       *
 132       * @return external_single_structure
 133       * @since Moodle 3.2
 134       */
 135      public static function get_course_grades_returns() {
 136          return new external_single_structure(
 137              array(
 138                  'grades' => new external_multiple_structure(
 139                      new external_single_structure(
 140                          array(
 141                              'courseid' => new external_value(PARAM_INT, 'Course id'),
 142                              'grade' => new external_value(PARAM_RAW, 'Grade formatted'),
 143                              'rawgrade' => new external_value(PARAM_RAW, 'Raw grade, not formatted'),
 144                              'rank' => new external_value(PARAM_INT, 'Your rank in the course', VALUE_OPTIONAL),
 145                          )
 146                      )
 147                  ),
 148                  'warnings' => new external_warnings()
 149              )
 150          );
 151      }
 152  
 153      /**
 154       * Returns description of method parameters
 155       *
 156       * @return external_function_parameters
 157       * @since Moodle 3.2
 158       */
 159      public static function view_grade_report_parameters() {
 160          return new external_function_parameters(
 161              array(
 162                  'courseid' => new external_value(PARAM_INT, 'id of the course'),
 163                  'userid' => new external_value(PARAM_INT, 'id of the user, 0 means current user', VALUE_DEFAULT, 0)
 164              )
 165          );
 166      }
 167  
 168      /**
 169       * Trigger the user report events, do the same that the web interface view of the report
 170       *
 171       * @param int $courseid id of course
 172       * @param int $userid id of the user the report belongs to
 173       * @return array of warnings and status result
 174       * @since Moodle 3.2
 175       * @throws moodle_exception
 176       */
 177      public static function view_grade_report($courseid, $userid = 0) {
 178          global $USER;
 179  
 180          $params = self::validate_parameters(self::view_grade_report_parameters(),
 181              array(
 182                  'courseid' => $courseid,
 183                  'userid' => $userid
 184              )
 185          );
 186  
 187          $warnings = array();
 188          $course = get_course($params['courseid']);
 189  
 190          $context = context_course::instance($course->id);
 191          self::validate_context($context);
 192  
 193          $userid = $params['userid'];
 194          if (empty($userid)) {
 195              $userid = $USER->id;
 196          } else {
 197              $user = core_user::get_user($userid, '*', MUST_EXIST);
 198              core_user::require_active_user($user);
 199          }
 200          $systemcontext = context_system::instance();
 201          $personalcontext = context_user::instance($userid);
 202  
 203          $access = grade_report_overview::check_access($systemcontext, $context, $personalcontext, $course, $userid);
 204  
 205          if (!$access) {
 206              throw new moodle_exception('nopermissiontoviewgrades', 'error');
 207          }
 208  
 209          grade_report_overview::viewed($context, $course->id, $userid);
 210  
 211          $result = array();
 212          $result['status'] = true;
 213          $result['warnings'] = $warnings;
 214          return $result;
 215      }
 216  
 217      /**
 218       * Returns description of method result value
 219       *
 220       * @return \core_external\external_description
 221       * @since Moodle 3.2
 222       */
 223      public static function view_grade_report_returns() {
 224          return new external_single_structure(
 225              array(
 226                  'status' => new external_value(PARAM_BOOL, 'status: true if success'),
 227                  'warnings' => new external_warnings()
 228              )
 229          );
 230      }
 231  }